GitHub - alexs60/safe-sde: Role-separated container isolation for AI-assisted development on macOS, DNS+iptables egress allowlist, host-side credential broker, grant-based git push.

Role-separated container isolation for AI-assisted development on macOS.

sde is a single-binary CLI that boots a private, network-isolated environment for your project — a workspace container where your code (and AI agents) run, role-separated data services, an egress firewall, and a credential broker that keeps secrets on the host and out of the container filesystem.

Think docker compose up for AI-agent-safe development: your agent gets what it needs to work, nothing more.

Why

Running an AI agent against your codebase means giving it a shell. That shell can curl, git push, aws s3 cp, and read every .env on your disk. sde draws the boundary in the right place:

• Egress allowlist by default — the workspace can only reach the domains you list. Everything else is NXDOMAIN at the DNS layer and DROP at iptables. Cloud instance-metadata (169.254.169.254) is always blocked.
• Credentials never leave the host — Git tokens live in your macOS Keychain. The workspace talks to a Unix-socket broker; tokens are minted per-operation and injected via GIT_CONFIG_COUNT env vars (no .gitconfig on the container filesystem).
• Write access is grant-based — git pull is default-allowed; git push requires an explicit, time-boxed sde grant push from your host terminal. Your agent can read; you decide when it can write.
• AWS via credential_process — no static keys in the container. sde injects a ~/.aws/config inside the workspace that calls back to the broker via credential_process; the broker shells out to aws configure export-credentials on the host, so short-lived SSO credentials are vended per-operation without touching the container filesystem.

Install

Build from source using git, go, and make — no package manager needed:

git clone https://github.com/alexs60/safe-sde.git ~/src/sde
cd ~/src/sde
make build helper
sudo make install

Full instructions, Intel/arm64 notes, container image build, and air-gapped workflow: see docs/INSTALL-LOCAL.md.

Homebrew: brew tap alexs60/sde && brew trust alexs60/sde && brew install sde. The brew trust step is required for any third-party tap. See docs/INSTALL.md.

Verify

sde doctor checks the configured runtime, Keychain access, credential store, and your topology file — run it any time something feels off.

Requirements

• macOS 13 (Ventura) or later — Apple Silicon or Intel
• Colima (brew install colima) — free, Apache 2.0, Docker-API compatible container runtime
• Git

Optional:

• AWS CLI v2 (aws configure export-credentials) if you want AWS credentials available inside containers

Alternative runtime

OrbStack works with a one-line topology change. See docs/RUNTIMES.md for installation, licensing, and the runtime_options reference.

Five-minute tour

# 1. Store a GitHub PAT so workspace containers can clone private repos
sde auth github --store

# 2. Go to your project
cd ~/my-project

# 3. Generate a topology.yaml from the detected stack
sde init

# 4. Boot the environment (detaches by default)
sde up

# 5. Open a shell in the workspace container
sde shell

# 6. Grant write access when you want to push
sde grant push --repo my-org/my-project --ttl 10m

# 7. Stop everything
sde down

sde up is idempotent — run it twice and it tells you the environment is already running. sde down stops containers but preserves volumes; sde nuke wipes state entirely.

For a full walkthrough including AWS SSO and first-run setup, see docs/GETTING-STARTED.md.

What a topology looks like

project: my-project

networks:
  subnet: 172.30.0.0/16
  egress:
    deny_all_else: true
    allow:
      - registry.npmjs.org
      - github.com
      - api.anthropic.com

services:
  dev:
    role: workspace
    image: ghcr.io/alexs60/sde/node-22-pnpm:latest
    mounts:
      - { type: bind, source: ., target: /workspace }
      - { type: volume, source: node_modules, target: /workspace/node_modules }
    ports: [3000, 3001]

  db:
    role: datastore
    image: postgres:16
    env:
      POSTGRES_DB: myapp
      POSTGRES_PASSWORD: dev
    volumes: [pgdata]
    ports: [5432]

credentials:
  provider: pat            # or "github-app" for teams
  push_requires_grant: true

aws:
  profile: bedrock-dev
  region: us-west-2

See topology.example.yaml for the full reference.

Command reference

How it fits together

Host (macOS)                          Container runtime
────────────────                      ─────────────────

  sde CLI ────────► broker daemon ◄────── credential helper
                    (~/.sde/broker.sock)  (in workspace container)
                          │
                    macOS Keychain          workspace: node/pnpm/git/gh
                    (PATs, AWS creds)             │
                                                  │
  aws CLI ◄── aws configure export-credentials    │
  (host process, reads SSO cache)                 │
                                                  ▼
                                          DNS resolver container
                                          (allowlist enforcement,
                                           IMDS always blocked)
                                                  │
                                                  ▼
                                          datastore containers
                                          (postgres, redis, ...)

The container runtime is Colima by default; OrbStack is an alternative — see docs/RUNTIMES.md.

• Workspace containers run your code and any AI agent. They can git pull freely but need a grant to push.
• Datastore containers are network-reachable by workspaces (db.myproject.sde.local) but have no external network access.
• The credential broker runs on the host, listens on a Unix socket bind-mounted into workspace containers, mints per-operation tokens.
• The DNS resolver runs as a sidecar container on a pinned bridge IP; workspace containers use it via --dns. iptables inside the workspace drops raw-IP traffic to block DNS bypass.

The full architecture lives in docs/ once you have it locally, but the CLI is the primary interface — start with sde --help.

Building from source

git clone https://github.com/alexs60/safe-sde.git
cd sde
go mod download
make build          # produces bin/sde and bin/sde-credential-helper
make test           # unit tests
make test-int      # integration tests (requires Colima or OrbStack running)
make lint

Go 1.25+ required. No CGo dependencies — binaries are fully static.

Design principles

• Hexagonal architecture. Core domain (internal/core/) has zero external imports. Everything crosses a port interface (internal/port/) to reach an adapter (internal/adapter/). Colima is the default; swapping to another Docker-API-compatible runtime (e.g. OrbStack) requires one topology line change and one interface implementation.
• Boring where possible. No custom crypto, no bespoke daemon frameworks. Unix sockets, JSON-newline protocol, standard os/exec, standard text/template, github.com/docker/docker SDK, miekg/dns, github.com/spf13/cobra.
• Failure closes. Broker crash → containers lose credential access, not gain it. Missing allowlist → deny by default. iptables not available in a BYOI image → warn and continue with DNS-layer protection only.
• Zero sudo for the happy path. mDNS/Bonjour handles *.sde.local name resolution on the host. No /etc/hosts writes, no LaunchDaemon requiring root.

License

GNU General Public License v3.0 or later (GPL-3.0-or-later) — see LICENSE for the full text and COPYRIGHT for the notice and third-party summary.

sde is copyleft: if you distribute it, or a modified version, you must make the corresponding source available to your recipients under the same licence. Running it — including inside your own organisation — carries no such obligation.

The GPL covers sde's own source. The container images under images/ aggregate Debian/Ubuntu packages and third-party CLIs under their own licences; that aggregation does not relicense them. See COPYRIGHT.

Status

sde is under active development. The v1 target covers workspace isolation, credential brokerage, egress policy, and AWS/GitHub credential integration on macOS with Colima (default) or OrbStack. Linux runtime support and additional token providers are on the roadmap.

Bug reports and contributions welcome via GitHub issues and pull requests.

Security issues go to SECURITY.md, not the issue tracker. That file is also the honest account of what sde does and does not defend against — worth reading before you rely on it. In short: it is a guardrail, not a jail. It raises the cost of an agent going off the rails or a dependency phoning home; it does not survive a container escape, and an allowlisted domain that serves arbitrary user content is a data channel by design.

Latest E2E verification: 2026-07-21. Binary: sde 2fa6dcd.