cleankoda logo

Sandbox Configuration

cleankoda prioritizes security and traceability above all else. Thanks to integrated sandboxing, potentially destructive shell commands, test runs, or build processes are not executed unchecked on your host system; instead, they are encapsulated and isolated within a dedicated Docker container.

Isolation and Security Model

When a sandbox is activated, strict protection mechanisms apply:

  • Isolated Command Execution: All Bash commands issued by the coding agent run exclusively within the sandbox’s Docker container.

  • Filesystem Binding: The current project directory is mounted into the container.

  • No Access to Host System: File operations such as read, write, and directory listing are strictly limited to the current project directory. The agent has no access to parent folders, your user directory, or other sensitive areas of your computer.

Controlling the Sandbox (/sandbox)

Management is handled directly via the terminal using a slash command:

/sandbox

This command opens a selection dialog where you can choose from pre-configured environments:

  • Python + uv: Optimized for modern Python projects, including fast tool and dependency management via uv.

  • Java + Maven: Designed for Java applications using Maven builds and standard JDK environments.

  • Node.js: Set up for JavaScript and TypeScript development using npm, yarn, or pnpm.

Deactivating the Sandbox

If you prefer to execute commands directly on your development machine, you can disable the sandbox at any time:

  • Via direct command:
/sandbox off
  • Or via the /sandbox selection dialog by choosing the host option.

Note: In host mode, commands run directly in your local shell without Docker isolation. ## Persistence in config.json Your selection is automatically saved in the global configuration file:

~/.config/cleankoda/config.json

Example structure:

{
  "provider": "anthropic",
  "model": "claude-3-7-sonnet-20250219",
  "sandbox": "python-uv"
}

The next time cleankoda is started in the project directory, the selected sandbox will be automatically restored and initialized.