# New sw dev tool for safe local AI usage

> Source: <https://github.com/alexs60/safe-sde>
> Published: 2026-07-29 01:53:45+00:00

**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 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.

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](/alexs60/safe-sde/blob/main/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`

```
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](https://github.com/abiosoft/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](/alexs60/safe-sde/blob/main/docs/RUNTIMES.md) for installation, licensing, and
the `runtime_options`

reference.

```
# 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](/alexs60/safe-sde/blob/main/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](/alexs60/safe-sde/blob/main/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](/alexs60/safe-sde/blob/main/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/](/alexs60/safe-sde/blob/main/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, 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.

GNU General Public License v3.0 or later (`GPL-3.0-or-later`

) — see
[ LICENSE](/alexs60/safe-sde/blob/main/LICENSE) for the full text and

[for the notice and third-party summary.](/alexs60/safe-sde/blob/main/COPYRIGHT)

`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](/alexs60/safe-sde/blob/main/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.*