Permissions & sandbox
Where commands run and what the agent may touch without asking you first.
Where commands run
The default for new projects. Each project can still choose from the chip beside the prompt.
Default sandbox
Where a project's commands run, unless the project chooses otherwise. Also the image that a container starts from when the project has no Dockerfile and Koda detects no base.
Share Docker host
Gives a project's container a Docker of its own, so docker and docker compose work there. What they start runs in that Docker, apart from this machine's containers and volumes, and ports they publish are forwarded to localhost on this machine.
Shell for commands
The shell a command runs in when its project runs on this computer. Automatic is sh on macOS and Linux, and Git Bash from Git for Windows on Windows. Projects in Docker or Podman use the container's shell.
File Access
Everything outside the open project is refused unless listed here.
Additional Directories
Directories outside the workspace that the agent may read and write. A change in one goes to approval like any other change. A disabled entry is refused but stays in the list.
Autonomous tasks outside the project
Autonomous tasks are approved automatically inside the project. Switch this on to let them read and write outside it too.
Approvals
What a project or MCP server starts with until it makes its own choice.
Changes inside the project
Ask before each file edit and each command that adds, edits, deletes or downloads files, or apply them directly. A project's own choice on its Runs on chip wins.
Commands that reach outside the project
Ask first, allow or deny a command that touches paths outside the project, rewrites git history or changes the system. A project's own choice on its Runs on chip wins. Allow here applies to your sessions. Autonomous tasks run these commands only when the project itself chooses Allow.
MCP tools
The approval that an MCP server starts with. Auto asks unless the server marks a tool read-only. Writes asks for anything that is not read-only. Always asks for every call. Never does not ask. A server's own approval in MCP servers wins.
Secrets
What reaches the model provider.
Mask secrets
Mask keys, tokens and passwords before anything goes to the model provider. A key that you type becomes a «secret:N» placeholder. Koda restores the value on your machine when a command uses it. The value is stored encrypted, with one key in your system keychain.
Defaults and config keys
| Setting | Default | config.toml |
|---|---|---|
| Default sandbox | Host (no isolation). Image ubuntu:24.04 | [sandbox] kind, image |
| Share Docker host | Off | [sandbox] share_docker_host |
| Shell for commands | Automatic: sh, or Git Bash on Windows | shell |
| Additional Directories | /tmp, switched off and not mounted | [[allowed_directory]] |
| Autonomous tasks outside the project | Off | [background] outside_project |
| Changes inside the project | Ask before each on this computer. Apply directly in a container | [sandbox] apply_edits_host, apply_edits_container |
| Commands that reach outside the project | Ask first on this computer. Allow in a container | [sandbox] outside_commands_host, outside_commands_container = ask, allow, deny |
| MCP tools | Auto (Auto, Writes, Always, Never) | mcp_approval |
| Mask secrets | Off | mask_secrets |
You can enable or disable each Additional Directory. Mark it Mount in sandbox to make it appear inside a project's container. See Approvals, Isolation and Redaction.