New sw dev tool for safe local AI usage

Notifications You must be signed in to change notification settings

Fork 0

Star 0

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

43 Commits

43 Commits

.github/workflows

.github/workflows

Formula

Formula

cmd

cmd

docs

docs

images

images

internal

internal

pkg/protocol

pkg/protocol

test

test

testdata

testdata

.gitignore

.gitignore

.golangci.yml

.golangci.yml

.trivyignore.yaml

.trivyignore.yaml

CHANGELOG.md

CHANGELOG.md

COPYRIGHT

COPYRIGHT

LICENSE

LICENSE

Makefile

Makefile

README.md

README.md

go.mod

go.mod

go.sum

go.sum

topology.example.yaml

topology.example.yaml

Repository files navigation

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 version sde doctor

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

Command What it does

sde init Detect the project stack and generate topology.yaml. --template 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 Run a one-off command in the workspace container.

sde logs [-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 --ttl 10m Grant time-boxed push access to a repo.

sde revoke [--all | --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

] [--device-code] Trigger AWS SSO re-auth from inside a container.

sde doctor Diagnose runtime, credentials, socket, and topology.

sde version Version information.

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.

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

Resources

Readme

GPL-3.0 license

Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks

Report repository