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.
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 isNXDOMAIN
at the DNS layer andDROP
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 viaGIT_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-boxedsde 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 viacredential_process
; the broker shells out toaws configure export-credentials
on the host, so short-lived SSO credentials are vended per-operation without touching the container filesystem.
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
. Thebrew trust
step is required for any third-party tap. See[.]docs/INSTALL.md
sde version
sde doctor
sde doctor
checks the configured runtime, Keychain access, credential store, and your topology file — run it any time something feels off.
- 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
OrbStack works with a one-line topology change. See
docs/RUNTIMES.md for installation, licensing, and
the runtime_options
reference.
sde auth github --store
cd ~/my-project
sde init
sde up
sde shell
sde grant push --repo my-org/my-project --ttl 10m
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.
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 | What it does |
|---|---|
sde init |
|
Detect the project stack and generate topology.yaml . --template <name> for a named template. |
|
sde up |
|
Boot the environment. Detaches by default; --foreground for debugging. |
|
sde down |
|
| Stop containers and the broker. Preserves volumes. | |
sde nuke |
|
| Stop everything and delete named volumes for this project. | |
sde shell [service] |
|
| Interactive shell in a container (default: workspace). | |
sde run <cmd...> |
|
| Run a one-off command in the workspace container. | |
sde logs <service> [-f] |
|
| Stream container logs. | |
sde ports |
|
| Table of service → host URL. | |
sde status (alias sde ps ) |
|
| Services, broker, AWS server, active grants, DNS. | |
sde grant push --repo <r> --ttl 10m |
|
| Grant time-boxed push access to a repo. | |
| `sde revoke [--all | --id <id>]` |
| Revoke one or all active grants. | |
sde audit [--tail N] [--project P] |
|
| Read the JSONL credential audit log. | |
sde auth github --store |
|
| Store a GitHub PAT in macOS Keychain. | |
sde auth github --status |
|
| Check whether a PAT is configured. | |
sde auth aws [--profile <p>] [--device-code] |
|
| Trigger AWS SSO re-auth from inside a container. | |
sde doctor |
|
| Diagnose runtime, credentials, socket, and topology. | |
sde version |
|
| Version information. |
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 cangit 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
.
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.
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, standardos/exec
, standardtext/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.
GNU General Public License v3.0 or later (GPL-3.0-or-later
) — see LICENSE for the full text and
for the notice and third-party summary.
COPYRIGHT
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.
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.
Latest E2E verification: 2026-07-21. Binary: sde 2fa6dcd.