Run DeepCode inside a container it cannot escape.
Deepsand is a desktop app that gives each project its own Docker-contained DeepCode instance. The container sees the project directory and whatever you explicitly share with it — nothing else. When DeepCode needs more, it has to ask, and you decide.
Create a project, name it, point it at a working directory:
┌─ Deepsand ──────────────────────────────────────────────────────────────┐
│ Projects │ my-website │
│ ▸ my-website ●run │ D:\work\my-website → /workspace │
│ ▸ api-server │ [Terminal] [Permissions 2] [Tools] │
│ │ [Secrets] [Activity] │
│ [+ New project] │ Deep Code v0.4.3 │
│ │ > add a dark mode toggle to the header │
│ │ │
│ │ ● DeepCode is trying to access │
│ │ C:\Users\me\Documents\brand │
│ │ [Not now] [Don't ask again] [Grant access] │
└─────────────────────────────────────────────────────────────────────────┘
Press Run and Deepsand:
- builds one
docker runcommand (you can read it in full — see the Activity tab), - starts the DeepCode CLI inside it under a real PTY, which the terminal pane renders,
- answers any permission request DeepCode makes by asking you first.
DeepCode knows it cannot see everything, and it has an API for saying so:
| It says | You get |
|---|---|
"I need C:\Users\me\Documents\brand" |
"DeepCode is trying to access C:\Users\me\Documents\brand" with that exact path shown, read-only pre-selected |
| "I need the my-website repo — but this sandbox can't tell me where that is" | "DeepCode is requesting access to the my-website repo" with a folder picker, because only you know where it lives |
Approving recreates the container with the new mount attached and resumes the session, so the conversation continues where it left off. Refusing has two forms: Don't ask again is final and DeepCode is told so, while Not now refuses this time and says DeepCode may ask again later.
Every project carries its own policy, so a throwaway repository and a client codebase do not have to share one.
| Setting | Where | Notes |
|---|---|---|
| Network mode | deepsandctl network <project> <mode>, with the app-wide default in Settings |
allowlisted (default), with a list of hostnames, addresses and ports; internet for anything; none for nothing; or full. |
| DeepCode mode | Project settings | strict additionally makes DeepCode prompt for network, MCP and out-of-workspace access in the terminal, on top of the container boundary. |
| Tools | Tools tab | Per-tool switches, plus Enable all / Disable all for each section and globally. Nothing is enabled by default: a new project installs no tools until you choose. Sections are ordered Capabilities, Languages, Package managers, Utilities, Reverse Engineering. The selection decides how the image is built, so the next Run rebuilds it — with its progress shown. |
| Model | Header dropdown | Defer to Config by default, which runs whatever your configuration resolves to. Otherwise one of the models the configured API reports, or a name you type in yourself. Saved and pushed into a running sandbox, like the thinking intensity. |
| Thinking intensity | Tools tab | none / low / high / max, or deferring to your host settings.json. Pushed into a running sandbox as well as saved for the next start. |
| Secrets | Secrets tab | Per project. Encrypted at rest with the operating system's keystore, injected as environment variables at start. Values travel one way only: the interface shows names and lengths, never the value. |
| Limits | Project settings | Memory, CPUs, pids. |
| Credentials | Project settings | Inherit your host DeepCode configuration, or give this project its own model, base URL and key. |
A terminal cannot paste a picture: the keystroke goes to the program inside it, and a clipboard image is never mentioned to anybody. Deepsand takes those pastes and drops instead and puts the file inside the sandbox, then types the path where the CLI can read it.
- Paste (Ctrl+V, or right-click → Paste) with a file or an image on the clipboard: it is copied in and its path is typed. Text pastes as text.
- Drop a file on the terminal: a file already in the project folder is named where the
sandbox already sees it (
/workspace/...), and anything else is copied in. - Files land in the sandbox's own
~/.deepcode/attachments, not in your repository, and anything over 25 MB is refused with a message rather than copied. - Nothing is attached unless a sandbox is running, and a file that fails is reported on its own rather than losing the files that worked.
Ctrl+C copies the terminal's selection (Ctrl+Shift+C does the same). It is no longer passed to the program inside the sandbox. To send the interrupt that Ctrl+C used to send, press Ctrl+T -- the escape hatch is still there for a process that needs stopping.
If DeepCode exits on its own -- a crash, or exit typed into it -- Deepsand starts it again
automatically and resumes the session. A session that exits again almost immediately is retried a
few times and then left stopped with a message; use Stop whenever you mean to end the sandbox.
Deepsand keeps the tools it builds (Rust binaries, npm globals) in a cache so a build copies them instead of compiling them again. A cache only helps if it can go stale safely, so:
- A key covers everything a build can see — platform, tool selection, and a fingerprint of the install steps — and changes the moment any of those do.
- An entry older than two weeks is rebuilt.
- Every six hours, and once shortly after startup, Deepsand asks npm and crates.io what they offer for the versions the cache holds. If something has moved, that entry is emptied and the next build installs it again. It never builds anything by itself.
- The DeepCode CLI is exempt: it is refreshed on every build regardless.
- Settings → Updates has the switch that turns those automatic checks off, and a Check now button that works either way. When the check finds something, the window says so — a cache quietly emptying itself would otherwise show up as a mysteriously slow build.
Two settings, both off by default, in Settings:
- Starting up — Off, In the background, or With the window. In the background Deepsand starts with your computer and no window at all: the tray icon opens it, and it is running so your sandboxes can be.
- Closing — off, the close button does what it always did: the sandboxes stop and Deepsand quits. On, the window hides and everything keeps running.
The tray icon appears exactly when hiding is possible, and its menu has Open Deepsand and Quit and stop the sandboxes — the honest pair, because those are the two things an operator wants from a tray: get back to it, or actually finish.
Requires Docker Desktop (or Docker Engine on Linux) and, to build from source, Node.js ≥ 22 and Rust ≥ 1.90 — the self-updater plugin is what sets that floor.
git clone https://github.com/L1lith/Deepsand
cd Deepsand
npm install
npm run runtime:build # build the sandbox image (once, ~3 min)
npm run app:build # produce the installer for your platformFor development, npm run app:dev starts the app with hot reload.
A local release build signs its update bundles, so it needs the key in the environment or
it stops with an error about updater artifacts. TAURI_SIGNING_PRIVATE_KEY may be the key
itself or a path to it:
$env:TAURI_SIGNING_PRIVATE_KEY = "C:\Users\you\.tauri\deepsand.key"
npm run app:buildexport TAURI_SIGNING_PRIVATE_KEY=~/.tauri/deepsand.key
npm run app:build
npm run runtime:buildusesruntime/Dockerfile, which installs@vegamo/deepcode-clifrom npm. SetDEEPSAND_BUILD_TOOLS=1inDEEPSAND_BUILD_ARGSif you want compilers inside the sandbox as well.
Deepsand reads your existing DeepCode configuration for the model, base URL and API key:
~/.deepcode/settings.json (Linux/macOS)
%USERPROFILE%\.deepcode\settings.json (Windows)
If that file does not exist, set the values per project under Project settings → Model credentials. The key is copied into Deepsand's own data directory and injected into the sandbox at start; it is never written into your project.
The desktop app is a shell over deepsand-core, and everything is available
without a display:
deepsandctl doctor # Docker, image, credentials, hardening
deepsandctl project add my-website D:\work\my-website
deepsandctl plan my-website # print the exact docker run command
deepsandctl run my-website # attach the sandbox to this terminal
deepsandctl watch my-website # in a second terminal: be the broker
deepsandctl grants my-website add D:\work\brand --purpose "site palette"
deepsandctl network my-website restricteddeepsandctl plan --offline <project> prints the command and the generated
configuration without needing Docker running, which is the easiest way to review
what the sandbox will be.
The container has no reference to the host filesystem other than the mounts Deepsand chose. That is the whole guarantee — everything else is defence in depth.
- Mounts.
/workspace, the directories you granted (under/grants,:rounless you said otherwise), Deepsand's own generated config and state (:ro), a write-only request spool, and a named volume for session history. Nothing else. No home directory, no/var/run/docker.sock. - Privileges. The entrypoint runs as root just long enough to install egress
rules and adopt a volume, then drops every capability, the bounding set and
uid 0. DeepCode runs as uid 1000 with
--read-onlyand--security-opt=no-new-privileges. - Network. Default is allowlisted: an allowlist through a filtering proxy,
plus any address you name reached directly, and everything else refused. List a
hostname — any port, or
host:portfor one — and it goes through the proxy; list an address such as192.168.1.50:5432and the sandbox reaches it directly, which is what a database or any non-HTTP client needs. A port you name is also published on this machine's loopback, so you can reach a server the sandbox runs. A hostname that resolves into local or private address space stays refused — list the address itself to reach it on purpose.internetis one click away for work that needs the open web, andnoneleaves only the model API reachable. - Requests you never see. Asking for something the sandbox already has — a
directory inside
/workspaceor inside a directory you already shared, a host already on the allowlist, a tool already in the image — is refused automatically, with a note saying where it already is. It is a refusal rather than an automatic approval, because an approval is yours to give; anything ambiguous still reaches you. - Turning the questions off. One checkbox in the Permissions tab stops a project being asked anything, and the request dialog has a quiet "Stop asking" button that sets it. Off means off: every request already waiting is refused with the reason, the sandbox is told not to ask, and a request written straight into its spool is refused on arrival rather than shown to you. On is the default.
- Kernel hardening. A hardened seccomp profile is on by default and
attached with
--security-opt=seccomp=. Its 16 rules deny 69 syscalls, among themmount,unshare,setns,pivot_root,chroot,bpf,ptrace,keyctl,pidfd_getfd,init_module,open_by_handle_at,userfaultfd,perf_event_open,io_uring_*, everyCLONE_NEW*flag, and the exotic socket families (AF_VSOCK,AF_ALG,AF_PACKET,AF_TIPC,AF_XDP). The image also carries the profile's digest, and a sandbox refuses to start unless the profile being applied is byte-for-byte the one the image was built with. If the profile cannot be found, no plan is built at all rather than a weaker container starting. - Permissions. The sandbox can write requests and read answers. The answer directory is mounted read-only, so a compromised sandbox cannot forge an approval or rewrite its own grant list. It can only ask. The request file itself is not authenticated — it cannot be, since the bridge is the agent's own child process — so the prompt you answer is the control, and there is deliberately no auto-approve path that could turn a forged request into a silent grant. See docs/SECURITY.md.
Every one of those claims has tests. See docs/SECURITY.md, which also lists what this does not protect against.
Deepsand/
├─ AGENTS.md how to work on this repository
├─ crates/deepsand-core/ Rust: path guards, policy, store, broker, proxy, secrets
│ └─ src/bin/deepsandctl.rs headless driver
├─ src-tauri/ Tauri app: the commands, PTY hosting, remote server
├─ src/ SolidJS UI: terminal, permissions, tools, secrets, activity
├─ runtime/ The in-container half
│ ├─ Dockerfile
│ ├─ bin/entrypoint.sh settings, egress rules, privilege drop
│ ├─ bin/netfilter.sh the network policy
│ ├─ bin/deepsand-mcp-bridge.mjs the API DeepCode asks through
│ ├─ skills/ Agent Skills installed into the sandbox
│ └─ seccomp-hardened.json the hardened profile, attached by default
├─ probe/ escape probes to compile and run inside the sandbox
└─ docs/ ARCHITECTURE.md, SECURITY.md
The GUI contains no policy: that lives in deepsand-core, which is why the
desktop app and the headless CLI cannot behave differently.
npm run app:dev # app with hot reload
npm run core:test # 374 core tests: paths, policy, broker, proxy, credentials, seccomp, durability
npm run app:test # 13 tests in the app crate: the zombie guard, and the log file
npm run test:bridge # 55 checks: the permission protocol end to end
npm test # both suites
npm run core:check # cargo check --workspace
npm run build # typecheck + bundle the frontend
npm run runtime:icons # regenerate src-tauri/icons from codenpm run app:build produces what you would ship, and it is slow on purpose: the release
profile is lto = true with codegen-units = 1, which makes the final link a
whole-program one. The other three exist because most local builds are not shipping:
| Command | What it does | When it is right |
|---|---|---|
npm run app:dev |
dev profile, hot reload, no bundling | iterating on code — seconds, not minutes |
npm run app:build:debug |
debug profile, NSIS installer only | you want to install your change and click around |
npm run app:build:fast |
release profile with LTO off, NSIS only, unsigned | you want something close to the real thing, quickly |
npm run app:build:binary |
builds the executable, packages nothing | checking that it compiles |
npm run app:build |
release, every bundle target, LTO on, signed | making a release |
On Windows the release build makes two installers (MSI and NSIS) because
bundle.targets is "all" so that each platform in the release matrix builds its own.
The --bundles nsis in the fast variants skips WiX and the MSI entirely.
app:build:fast turns LTO off because that is the only thing that measurably helps.
Swapping the linker does not: a release relink after touching one file measures 219 s
with the MSVC linker and 212 s with rust-lld, because with lto = true the time is LLVM
optimizing across every crate before a linker is invoked. Turning LTO off is what takes
the minutes out. It produces a slightly larger, slightly slower binary, which is why the
shipping build keeps lto = true.
A release build also needs the updater key in the environment, or it stops with an error about updater artifacts (see Install).
The interesting tests are the ones that assert containment rather than behaviour — a_plan_never_mounts_a_container_runtime_socket, the_reply_channel_can_never_be_written_by_the_sandbox, symlinks_are_resolved_before_guards_run. They are listed in docs/SECURITY.md.
Contributors and coding agents should read AGENTS.md first: it lists the invariants that are load-bearing, the platform quirks that will otherwise cost you an afternoon, and what counts as done.
Everything the app says about itself is written to deepsand.log in its data directory
(%LOCALAPPDATA%\Deepsand\data on Windows; the Activity tab shows the path and copies it on
request). That includes every error the window showed in a corner box, every command that
failed, and any panic. A Windows release build has no console, so this file is the only place
those are readable after the fact — and the boxes themselves can be copied with the button in
the corner, or selected directly.
If your project list comes back smaller than you left it, the notice at the top says which file it was read from: Deepsand keeps a dated copy of its configuration once a day, and falls back to the live file, then its rolling backup, then a dated copy, then anything it previously set aside. It only ever tells you about a copy it actually used.
A build that stops producing output for ten minutes is stopped and reported, rather than left
running until you close the app -- and there is a Stop build button while one is running, in
the header and on the progress bar, so you do not have to wait for that. Stopping is safe:
finished steps are kept, so starting again carries on from where it stopped. That is a limit on silence, not on how long a build may take:
apt, npm and cargo all print as they go, so a build that has said nothing for ten minutes is not
one that is about to finish. Closing Deepsand also ends any docker command it started, so a
stuck build cannot hold the image tag the next one needs.
If a runtime file is damaged — a crash can leave a file the right size and full of NULs — the
next build repairs it from the copy inside the app and says which files it replaced, rather
than failing with Docker's unknown instruction on a Dockerfile you never wrote.
If Docker Desktop itself misbehaves — its volumes flagged, its daemon not answering while the
window is up, a build dying with an RPC error — that is Docker Desktop's VM rather than
Deepsand. Restarting Docker Desktop cleared all three here, and the five deepsand-state-*
volumes came back readable with their contents intact. Nothing in Deepsand deletes a volume.
Pushing to the release branch, or running the release workflow from the Actions tab, builds installers for Windows, Linux (x86_64 and ARM64) and macOS (Apple Silicon and Intel), signs them, and opens a draft GitHub release. Review the artifacts and the notes, then publish the draft — the update manifest (latest.json) is only served from a published release, so nothing is offered to installed copies until you do.
The app updates itself. It checks a few seconds after startup and says so if something newer exists; Settings → Updates has the current version, a Check for updates button, and the install button. Installing restarts Deepsand, which stops any running sandbox, so the dialog says that before you click rather than after.
Two things are worth knowing before the first release:
- The signing key is a secret, and losing it is permanent.
npm run tauri signer generate -- -w ~/.tauri/deepsand.keycreates it; the public half goes insrc-tauri/tauri.conf.jsonand the private half goes in the repository'sTAURI_SIGNING_PRIVATE_KEYsecret (and, only if you set one,TAURI_SIGNING_PRIVATE_KEY_PASSWORD). The workflow refuses to build without it. Whoever holds that key can sign an update that every installed copy will accept, and if it is lost, no already-installed copy can ever be updated again. - Bump all three version fields together —
src-tauri/tauri.conf.json,package.jsonand the workspaceCargo.toml. The tag, the release name and the update manifest all come from them, and the workflow fails early if they disagree, because a mismatch produces a release that tells installed copies they are already up to date.
macOS builds are ad-hoc signed, not notarised: there is no Apple Developer certificate here, so macOS will warn about the first launch of a downloaded copy. Windows builds are unsigned, so SmartScreen will warn too. Neither warning is about the update signature, which is separate and always enforced.
Deepsand is an independent wrapper and is not affiliated with the DeepCode project. It drives the published @vegamo/deepcode-cli package from inside a container; the DeepCode source is never vendored into this repository (a checkout under reference/ is gitignored).