Concepts

Command sandbox

Duscode runs Dus's commands in an OS sandbox. They can write only the session's folder, never see your credentials, and reach only package registries.

Every command Dus runs goes through an operating-system sandbox when your system has one: commands it runs for a task, the verification gate's checks, worker agents' commands, and the preview's install and dev server. The sandbox is the boundary. The blocklist and approvals are a second line behind it.

What a sandboxed command can do

• Write only the session's folder. The rest of the file system is read-only. The exceptions are package caches (npm, pnpm, pip, cargo, Go and others), the git folders a commit needs, and a private temporary folder.
• Not see your home folder. It gets an empty one instead. Your toolchains (such as nvm, volta, rustup and pyenv) are put back read-only, so node, pnpm and the rest still work.
• Not see your credentials. ~/.ssh, ~/.duscode, ~/.aws, ~/.config/gh, ~/.kube, ~/.docker, ~/.gnupg, ~/.npmrc, ~/.netrc, ~/.git-credentials and similar files stay hidden, even if the session folder is your home folder. So do Windows drives under WSL (/mnt) and the ssh-agent and keyring sockets.
• Not change git's hooks or config. They stay read-only, so a command can't plant code that runs at your next commit.
• Not inherit secrets. Variables that look like credentials (names ending in _TOKEN, _SECRET, _KEY, _PASSWORD, cloud provider variables, URLs with a password) are removed. A command gets a vault secret only when it names it.

Network

A sandboxed command can reach only:

• the package registries: npm, Yarn, PyPI, crates.io, Go, RubyGems and Maven
• the session's preview port

When a command needs another host, Dus asks you with a card that names the hosts. This is asked in every mode, Full Auto included. If you decline, Dus is told and can try another way.

To allow hosts for every command, list them in your user config, ~/.duscode/config.json:

{
  "network": { "allow": ["api.example.com"] }
}

Tools that use a proxy (curl, npm, pnpm, yarn, pip, cargo, git) work. Tools that ignore the proxy, including Node's built-in fetch, get no network at all: the sandbox fails closed.

Which systems have it

Stop and timeouts end everything a sandboxed command started, including programs that detach into the background.

Where you see it

Open Project details (click the project's name in the sidebar, then choose Project details). The Sandbox fact says, for example:

• On (bubblewrap) · network: registries only
• Off · commands run as you, with approvals; Full Auto is off. With the reason and how to fix it

duscode doctor prints the same line ("Sandbox: Off — commands run as you"). Without the sandbox, a line above the message box says so in every session, every session starts in Ask, and Full Auto can't be chosen.

Full Auto needs it

The Full Auto permission mode can be chosen only while the sandbox works. Without it, the mode menu says Full Auto needs the OS sandbox.

If the sandbox stops working during a session, Duscode switches to Auto at the next step and tells you in the chat. Irreversible actions (pushes, deploys, migrations, secrets) and hosts outside the allowlist still ask in Full Auto.

Settings

Set sandbox in your user config, ~/.duscode/config.json:

A project's own .duscode/config.json can only make it stricter ("required"). It can't turn the sandbox off or allow network hosts, so a repository you clone can't loosen its own limits.

Known limits

• The preview's dev server shares your network, because your browser has to reach it. Its files and environment are still sandboxed.
• Data could be sent out through an allowed package registry.
• Files a command writes in the session folder that other tools run later, outside the sandbox, aren't covered: for example .envrc with direnv, or .vscode/tasks.json.
• A command can empty the writable package caches. They download again.
• Private registries that need credentials in ~/.npmrc don't work inside the sandbox yet.
• On macOS, reads of /tmp and other system folders are allowed.