sde: macOS tool isolates AI agents in containers with credential firewalls

sde is a single-binary CLI tool for macOS that boots a role-separated, network-isolated container environment—called a workspace—where your code and AI agents can run safely. The core idea is to apply the principle of least privilege: give an agent what it needs to work (read access, ability to fetch dependencies, make git commits), nothing more (no raw internet access, no static credentials, no uncontrolled write access).

The tool enforces isolation through three mechanisms. First, egress control: the workspace container can only reach domains you explicitly list in a topology.yaml file. All other traffic is blocked at the DNS resolver (a sidecar container that returns NXDOMAIN) and again at iptables within the workspace. Cloud instance metadata (169.254.169.254) is always blocked, preventing an agent from stealing cloud-provider secrets. Second, credential brokerage: Git tokens live in macOS Keychain on the host; when the workspace needs to git clone or git push, it talks to a Unix-socket broker running on the host, which mints short-lived tokens per-operation and injects them via GIT_CONFIG_COUNT environment variables—no .gitconfig file in the container. AWS credentials work similarly: sde injects a ~/.aws/config into the workspace that uses credential_process to call back to the broker, which shells out to aws configure export-credentials on the host, vending short-lived SSO credentials without storing static keys in the container. Third, write gating: git pull is allowed by default, but git push requires an explicit grant you issue from your host terminal (e.g., sde grant push --repo my-org/my-project --ttl 10m), time-boxing push access to the window you specify.

Installation is available via Homebrew (brew tap alexs60/sde && brew trust alexs60/sde && brew install sde) or by building from source using Git, Go, and Make. The tool requires macOS 13 or later, Colima (a free, Docker-API-compatible container runtime), and Git; AWS CLI v2 is optional if you want AWS credentials available. The container runtime can be switched from Colima to OrbStack with a one-line topology change.

The workflow is five steps: store a GitHub PAT (sde auth github --store), navigate to your project, generate a topology.yaml (sde init, which auto-detects your stack), boot the environment (sde up), open a shell in the workspace (sde shell), and then grant write access when needed (sde grant push --ttl 10m) or stop everything (sde down). The topology.yaml file specifies networks, services (workspace and datastore containers), egress policy, and credential providers; a reference example includes a Node.js workspace with pnpm, a Postgres datastore, and an allowlist for npm registry, GitHub, and Anthropic API.

The tool is under active development and licensed under GPL-3.0-or-later. The v1 target covers workspace isolation, credential brokerage, egress policy, and AWS/GitHub integration on macOS; Linux runtime support and additional token providers are on the roadmap. Latest E2E verification was 2026-07-21. The author notes in SECURITY.md that sde is a guardrail, not a jail: it raises the cost of an agent going off the rails or a dependency phoning home, but does not survive a container escape, and an allowlisted domain that serves arbitrary user content is a data channel by design.

sde addresses a real security gap in AI-assisted development: when you run an agent against your codebase, you typically grant it a shell with access to secrets, Git history, and cloud credentials—a broad permission surface that a compromised agent or malicious dependency could abuse. The tool implements three complementary layers of isolation. First, network isolation: the workspace can only reach domains you explicitly allowlist; everything else is blocked at the DNS resolver (a sidecar container) and at iptables, and cloud instance metadata is always blocked. Second, credential isolation: secrets never reside in the container filesystem—they live in the host's macOS Keychain and are brokered per-operation, so even if an attacker gains a shell in the workspace, they cannot harvest static keys. Third, write control: the agent cannot modify code or infrastructure without an explicit, time-boxed grant you issue from the host terminal, decoupling agent read access (which is needed for context) from write capability (which should be gated).

The architecture is modular: Colima is the default container runtime, but OrbStack works with a single topology change, and the codebase uses a hexagonal architecture where the core domain has zero external imports. Installation is straightforward—Homebrew or Go build from source—and the CLI is designed to be primary interface. The author is transparent about limitations: sde is a guardrail, not a jail, so it does not defend against container escape, and an allowlisted domain that serves arbitrary user content is a data channel by design. Latest E2E verification was 2026-07-21.

No comments yet. Be the first to share your thoughts!