You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+20-11Lines changed: 20 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,19 @@
1
1
# devsandbox
2
2
3
-
Sandbox your AI coding assistants. Run Claude Code, Copilot, aider, and other tools without exposing SSH keys, cloud credentials, or secrets.
3
+
Your real dev environment, sandboxed per project. Run Claude Code, Copilot, aider, and other AI coding agents safely -- without giving up your shell, your `mise`-managed tools, or your editor configs.
4
4
5
-
## The Problem
5
+
## The DX gap
6
6
7
-
AI coding assistants execute shell commands, install packages, and make network requests on your machine -- with full access to your `~/.ssh` keys, `~/.aws` credentials, `.env` secrets, and everything else. An AI agent with unrestricted access could read your `~/.ssh/id_ed25519`, exfiltrate `~/.aws/credentials` via an API call, or `rm -rf` your home directory.
7
+
Docker and VMs isolate by *replacing* your dev environment. Fresh shell with no aliases. No `mise`, no editor, no prompt. Reinstall every tool inside the container, fight file watchers across the VM boundary, and wait 10-30 seconds for cold starts. So most people skip isolation entirely and let agents run on the host -- with full access to `~/.ssh`, cloud credentials, `.env` secrets, and every other project on disk.
8
8
9
-
devsandbox removes that risk. It wraps any command in a sandbox scoped to your current working directory -- the directory you run `devsandbox` from becomes the project root with full read/write access, while everything outside it (credentials, keys, secrets, other projects) is blocked. An optional proxy mode logs every HTTP/HTTPS request for inspection.
9
+
devsandbox closes that gap. It wraps any command in a sandbox scoped to your current working directory and brings the rest of your real environment with it:
10
+
11
+
-**Your shell, aliases, history.** Detected from `$SHELL` and bound read-only.
-**Sub-second startup.** bubblewrap on Linux shares the host kernel; native file watching works.
15
+
16
+
The isolation boundary is still real. Inside the sandbox, the agent sees the project directory and your tools -- and nothing else. SSH keys, cloud credentials (`~/.aws`, `~/.azure`, `~/.gcloud`), `.env` files, sibling projects, and parent directories are invisible. `.git` is read-only by default. An optional MITM proxy logs every HTTP/HTTPS request for inspection.
DX is the headline; isolation is the floor. The defaults are tuned so an agent inside a fresh sandbox can do its job and nothing more -- no flags required.
128
137
129
-
**CAN:** Read/write your project files, run build commands, install dependencies, make API calls (logged in proxy mode).
138
+
**CAN:** Read/write your project files, use your `mise`-managed tools, inherit your shell and editor configs, run build commands, install dependencies, make API calls (logged in proxy mode).
130
139
131
140
**CANNOT:** Read SSH keys, access cloud credentials (AWS/Azure/GCloud), read `.env` secrets, see other projects, push to git (by default), or modify your system.
132
141
133
-
### Security Details
142
+
### Resource access defaults
134
143
135
144
| Resource | Default Access |
136
145
|---|---|
@@ -149,13 +158,13 @@ Everything is configurable. See [Configuration](docs/configuration.md) for detai
149
158
150
159
## Features
151
160
152
-
-**Zero-config security** -- SSH keys, cloud credentials, `.env` files, and git credentials are blocked by default
153
-
-**Your tools, your shell** -- mise-managed tools, shell configs, editor setups (nvim, starship, tmux) all work inside the sandbox
161
+
-**Your real dev env, inside the sandbox** -- mise-managed tools, shell configs, editor setups (nvim, starship, tmux) auto-detected and bound, no Dockerfile required
162
+
-**Sub-second startup** -- [bubblewrap](https://github.com/containers/bubblewrap) namespaces on Linux share the host kernel; native file watching works. Docker layer caching keeps macOS restarts at 1-2s
163
+
-**Per-project isolation** -- each project gets its own sandbox home, caches, and logs
164
+
-**Zero-config security baseline** -- SSH keys, cloud credentials, `.env` files, and git credentials blocked by default
154
165
-**MITM proxy** -- optional traffic inspection with log viewing, filtering, and export
155
166
-**HTTP filtering** -- whitelist/blacklist domains, or interactively approve requests one at a time
156
167
-**Content redaction** -- scan outgoing requests for secrets, block or replace them before they leave your machine
157
-
-**Cross-platform** -- [bubblewrap](https://github.com/containers/bubblewrap) namespaces on Linux (sub-second startup), Docker containers on macOS
158
-
-**Per-project isolation** -- each project gets its own sandbox home, caches, and logs
159
168
-**Git modes** -- readonly (default), readwrite (with SSH/GPG), or disabled
160
169
-**Desktop notifications** -- sandboxed apps can send notifications to the host via XDG Desktop Portal (Linux)
<title>devsandbox — sandbox AI coding assistants safely</title>
7
-
<metaname="description" content="Run Claude Code, Copilot, aider, and any other AI coding tool safely. devsandbox sandboxes the agent to your project directory — your SSH keys, cloud credentials, and other projects stay invisible. Skip permission prompts without giving up your home directory.">
6
+
<title>devsandbox — your dev environment, sandboxed</title>
7
+
<metaname="description" content="Sandbox AI coding agents without rebuilding your dev env. Your shell, mise-managed tools, and editor configs come with you. SSH keys, cloud credentials, and other projects stay invisible.">
<metaproperty="og:title" content="devsandbox — sandbox AI coding assistants safely">
17
-
<metaproperty="og:description" content="Run Claude Code, Copilot, aider, and friends without exposing SSH keys or cloud credentials. Skip permission prompts safely.">
16
+
<metaproperty="og:title" content="devsandbox — your dev environment, sandboxed">
17
+
<metaproperty="og:description" content="Sandbox AI coding agents without rebuilding your dev env. Your shell, mise tools, and editor configs come with you. Credentials and other projects stay invisible.">
18
18
<metaname="twitter:card" content="summary">
19
-
<metaname="twitter:title" content="devsandbox — sandbox AI coding assistants safely">
20
-
<metaname="twitter:description" content="Run Claude Code, Copilot, aider, and friends without exposing SSH keys or cloud credentials.">
19
+
<metaname="twitter:title" content="devsandbox — your dev environment, sandboxed">
20
+
<metaname="twitter:description" content="Sandbox AI coding agents without rebuilding your dev env. Your shell and mise tools come with you.">
<h1>Run AI coding tools without giving them your SSH keys.</h1>
35
+
36
+
<pclass="eyebrow">Sandboxing for AI coding agents · Linux + macOS</p>
37
+
<h1>
38
+
Sandbox the agent. <em>Keep your dev env.</em>
39
+
</h1>
36
40
<pclass="lede">
37
-
<strong>devsandbox</strong> sandboxes Claude Code, Copilot, aider, and any other CLI tool to the directory you're working in.
38
-
Skip permission prompts safely — your<code>~/.ssh</code>, cloud credentials, and other projects stay invisible.
41
+
Docker and VMs isolate by replacing your environment — fresh shell, no <code>mise</code>, no editor config, slow rebuilds. So most people skip isolation entirely.
42
+
<strong>devsandbox</strong> brings your real shell, mise-managed tools, and editor setup into a per-project sandbox. Your<code>~/.ssh</code>, cloud credentials, and other projects stay invisible.
39
43
</p>
40
44
41
45
<divclass="install">
42
46
<pre><codeid="install-cmd">mise use -g github:zekker6/devsandbox</code></pre>
Open source · MIT · Sub-second startup on Linux (bubblewrap) · Docker-backed on macOS
53
57
</p>
54
58
</div>
55
59
</header>
56
60
57
-
<sectionclass="why">
61
+
<sectionclass="dxgap">
58
62
<divclass="container">
59
-
<h2>Why devsandbox</h2>
60
-
<divclass="cards">
61
-
<articleclass="card">
62
-
<h3>Secrets stay yours</h3>
63
-
<p>
64
-
<code>~/.ssh</code>, <code>~/.aws</code>, <code>.env</code>, parent directories, and other projects are <em>invisible</em> inside the sandbox. An AI agent can't exfiltrate what isn't mounted.
65
-
</p>
66
-
</article>
67
-
<articleclass="card">
68
-
<h3>No more permission fatigue</h3>
69
-
<p>
70
-
Run with <code>--dangerously-skip-permissions</code> and actually mean it. Auto-approve commands without trusting your whole home directory.
71
-
</p>
72
-
</article>
73
-
<articleclass="card">
74
-
<h3>Tool-agnostic</h3>
75
-
<p>
76
-
Claude Code, GitHub Copilot, aider, Cursor CLI, OpenCode — anything with a shell. Wraps the binary, no plugin needed.
77
-
</p>
78
-
</article>
63
+
<pclass="section-tag">/ 01 — the DX gap</p>
64
+
<h2>Most isolation tools make you rebuild your dev env from zero.</h2>
65
+
<pclass="section-lede">
66
+
Spin up a Docker container or VM and you land in a stranger's machine: bash with no aliases, no <code>mise</code>, no editor, no prompt. Reinstall everything, fight file watchers, eat 10–30s cold starts. Eventually you give up and let the agent run on the host. devsandbox closes that gap.
67
+
</p>
68
+
69
+
<divclass="comparison">
70
+
<divclass="col col-pain">
71
+
<pclass="col-tag">Docker · VM</p>
72
+
<ulclass="checklist negative">
73
+
<li>Fresh shell — no aliases, no history, no prompt</li>
74
+
<li>Reinstall every tool inside the container</li>
<li>File-watching breaks across the VM boundary</li>
79
+
</ul>
80
+
</div>
81
+
<divclass="col col-win">
82
+
<pclass="col-tag">devsandbox</p>
83
+
<ulclass="checklist positive">
84
+
<li>Your shell, your aliases, your history</li>
85
+
<li><code>mise</code> tools mounted read-only — Go, Node, Python, all of it</li>
86
+
<li>Editor + LSP configs come along, untouched</li>
87
+
<li>Starship, tmux, nvim, fish, zsh — all preserved</li>
88
+
<li>Sub-second restart on Linux, 1–2s on macOS</li>
89
+
<li>Native file watching — bubblewrap shares the host kernel</li>
90
+
</ul>
91
+
</div>
79
92
</div>
80
93
</div>
81
94
</section>
82
95
83
96
<sectionclass="how">
84
97
<divclass="container">
85
-
<h2>How it works</h2>
98
+
<pclass="section-tag">/ 02 — how it works</p>
99
+
<h2>Wrap any command. Inherit your env. Block the rest.</h2>
86
100
87
101
<olclass="steps">
88
102
<li>
89
-
<h3>Wrap the command.</h3>
90
-
<p>Use <code>devsandbox</code> as a prefix. The directory you run it from becomes the sandbox root — everything else is blocked.</p>
103
+
<pclass="step-num">01 · wrap</p>
104
+
<h3>Prefix the command.</h3>
105
+
<p>The directory you run <code>devsandbox</code> from becomes the sandbox root. Everything outside it is gone.</p>
91
106
<pre><code>cd ~/projects/my-app
92
107
devsandbox claude --dangerously-skip-permissions</code></pre>
93
108
</li>
94
109
<li>
95
-
<h3>Filesystem locked down.</h3>
96
-
<p>Project files are read/write. Credentials, parent directories, sibling projects, and <code>.env</code> files are gone. <code>.git</code> is read-only by default.</p>
110
+
<pclass="step-num">02 · inherit</p>
111
+
<h3>Your env follows you in.</h3>
112
+
<p>mise tools, shell configs, editor and prompt — auto-detected, bound read-only. No reinstall, no Dockerfile, no <code>mise install</code> twice.</p>
97
113
<pre><code># inside the sandbox
98
-
ls ~/.ssh
114
+
mise ls # your real toolchain
115
+
which nvim # your real editor
116
+
echo $STARSHIP_* # your real prompt</code></pre>
117
+
</li>
118
+
<li>
119
+
<pclass="step-num">03 · isolate</p>
120
+
<h3>Credentials stay out.</h3>
121
+
<p>SSH keys, cloud creds, <code>.env</code>, sibling projects — invisible. <code>.git</code> is read-only by default. Now <code>--dangerously-skip-permissions</code> actually means something.</p>
122
+
<pre><code>ls ~/.ssh
99
123
# No such file or directory
100
124
101
125
cat .env
102
126
# (empty — masked with /dev/null)</code></pre>
103
127
</li>
104
128
<li>
105
-
<h3>Network optional.</h3>
106
-
<p>Add <code>--proxy</code> to log every HTTP request. Block outbound entirely with a filter rule, or interactively approve each domain.</p>
129
+
<pclass="step-num">04 · observe</p>
130
+
<h3>Network, on your terms.</h3>
131
+
<p>Add <code>--proxy</code> to log every HTTP call. Block, allow, or interactively approve domains as the agent runs.</p>
107
132
<pre><code>devsandbox --proxy claude --dangerously-skip-permissions
<h2>Zero-config defaults. <em>Reach what isn't mounted.</em></h2>
143
+
<pclass="section-lede">
144
+
DX is the headline; isolation is the floor. The defaults are tuned so that an agent inside a fresh sandbox can do its job and nothing more — no flags required.
0 commit comments