Skip to main content
Configuration and Security

Sandbox

A protective layer for handling untrusted code or high-risk commands: enabling the sandbox, isolation boundaries, and related configuration.

The Sandbox allows Qoder CLI to execute commands and tools within a restricted, isolated environment, reducing the risk of accidental operations or untrusted code. When the sandbox is enabled, file system and network access for commands are confined to defined boundaries, and any operations exceeding these boundaries are denied. The sandbox is ideal for handling untrusted code, executing potentially risky commands, or adding an extra layer of protection to automated workflows. This page covers how to enable the sandbox, its isolation capabilities, and related configurations.

Enabling the Sandbox

There are three ways to enable the sandbox, in order of priority: Environment Variables > Command-line Arguments > Configuration Files.

Command-line Arguments

-s, --sandbox is a boolean flag used solely to enable the sandbox; it does not accept a backend name: 
qodercli --sandbox
The backend used is determined by the environment variable QODER_SANDBOX or the configuration file. If neither is specified, it is automatically detected based on the platform (see below).

Environment Variables

export QODER_SANDBOX=docker
qodercli

Configuration File

Set this in settings.json (requires a restart after modification): 
{
  "tools": {
    "sandbox": "docker"
  }
}
Or use the object format for finer control: 
{
  "tools": {
    "sandbox": {
      "enabled": true,
      "command": "docker",
      "image": "custom/image:tag",
      "allowedPaths": ["/tmp"],
      "networkAccess": false
    }
  }
}
If it is detected that the process is already running inside a sandbox (the SANDBOX environment variable is set), Qoder CLI will not enable nested sandboxing.

Supported Sandbox Backends

sandbox can be set to a boolean value, a configuration object, or one of the following specific sandbox commands:
CommandPlatformDescription
dockerLinux / GeneralUses Docker container isolation (requires Docker to be installed).
podmanLinuxAn alternative to Docker.
sandbox-execmacOSNative macOS sandbox, automatically detected on macOS.
runscLinuxgVisor isolation, requires Docker, supported only on Linux, and is not automatically detected.
lxcLinuxLXC containers, must be pre-created and running, and are not automatically detected.
windows-nativeWindowsNative Windows sandbox.

Auto-Detection

When sandbox is set to true without specifying a concrete command, Qoder CLI automatically selects one based on the platform: it prefers sandbox-exec on macOS; otherwise, it tries docker and then podman in sequence. If the sandbox is enabled but no available command is found, an error will prompt you to install Docker/Podman or explicitly specify a command. runsc and lxc are not automatically detected and must be explicitly specified.

Isolation Capabilities

File System Isolation

  • By default, only the Workspace Directory is mounted as read-write.
  • You can grant additional access to specific absolute paths via tools.sandboxAllowedPaths (or allowedPaths in the object configuration).
  • Sensitive files and version control directories are isolated from sandbox access.

Network Isolation

  • Controlled by tools.sandboxNetworkAccess (or networkAccess in the object configuration), defaulting to false (network access denied).
  • When network access is denied or a sandbox proxy is configured, an internal network is created for the sandbox to restrict its external connections.
  • You can configure a proxy command for internal sandbox requests via the environment variable QODER_SANDBOX_PROXY_COMMAND, and proxy-related environment variables will be forwarded into the sandbox.

Command Execution

  • Command execution is subject to security checks based on the classification of known safe/dangerous commands.
  • Sensitive environment variables are sanitized before being passed into the sandbox to prevent key leakage into the isolated environment.

Sandbox Images

For Container-Based Backends (docker / podman), you can specify a custom image:
  • The image field in the configuration object.
  • The environment variable QODER_SANDBOX_IMAGE (or the default image variable QODER_SANDBOX_IMAGE_DEFAULT).
If not specified, the built-in default image is used. Native sandboxes (sandbox-exec, lxc, windows-native) do not require an image.

Tool-Level Sandbox

In addition to sandboxing the entire CLI process, you can enable a more granular Tool-Level Sandbox: 
{
  "security": {
    "toolSandboxing": true
  }
}
security.toolSandboxing (defaults to false, requires a restart) isolates the execution of individual tools rather than the entire CLI process, making it suitable for scenarios where you only want to restrict specific high-risk operations.
VariableDescription
QODER_SANDBOXSpecifies the sandbox command or flag.
QODER_SANDBOX_IMAGECustom sandbox image.
QODER_SANDBOX_IMAGE_DEFAULTDefault sandbox image.
QODER_SANDBOX_PROXY_COMMANDInternal proxy command for the sandbox.
SANDBOXInjected by the sandbox environment to detect whether it is already running inside a sandbox and avoid nesting (usually no need to set manually).

Next Steps

Getting Started
Core Concepts
Using Qoder CLI
Extending Qoder CLI
Remote and Integrations
Configuration and Security
Reference
Troubleshooting