Skip to main content

​
Container Sandbox

The Container Sandbox runs agent exec commands inside ephemeral Docker containers instead of directly on your host machine. This provides strong isolation — each command runs in a fresh container with dropped capabilities, constrained resources, and optional network restrictions.

​
How it works

The sandbox uses the bollard Rust crate to communicate with the Docker daemon.

​
Enabling the sandbox

  1. Install Docker on your system (Docker Desktop or Docker Engine)
  2. Go to Settings → Advanced
  3. Toggle Container Sandbox to enabled
  4. Optionally select a preset or configure manually
:::warning Docker must be installed and running for the sandbox to work. If Docker is unavailable, exec commands will fail when the sandbox is enabled. :::

​
Configuration

SettingDefaultDescription
enabledfalseWhether sandboxing is active
imagealpine:latestDocker image used for containers
timeout30sMaximum execution time per command
memory256 MBMemory limit for the container
cpu_shares512Relative CPU weight (default Docker is 1024)
networkDisabledWhether the container has network access
workdir/workspaceWorking directory inside the container
bind_mounts[]Host-to-container directory mounts (host:container:mode)

​
Security hardening

Every sandboxed container runs with strict security defaults:
  • CAP_DROP ALL: All Linux capabilities are dropped — no privilege escalation possible
  • No privileged mode: Containers cannot access host devices or kernel features
  • Output truncation: Command output is truncated at 50,000 characters to prevent memory exhaustion
  • Ephemeral: Containers are destroyed after each command — no persistent state between executions

​
Presets

Pawz includes 4 pre-built sandbox profiles for common use cases. Select a preset to instantly configure all settings.

​
Minimal

The most restrictive configuration. Ideal for simple shell commands where you want maximum isolation.
SettingValue
Imagealpine:latest
Memory128 MB
Timeout15s
CPU shares512
NetworkDisabled
Workdir/workspace
Best for: Quick file operations, text processing, basic shell utilities.

​
Development

A balanced profile with Node.js available and network access enabled. Suitable for running build scripts, linting, and test suites.
SettingValue
Imagenode:20-alpine
Memory512 MB
Timeout60s
CPU shares512
NetworkEnabled
Workdir/workspace
Best for: JavaScript/TypeScript development, package installation, running tests, build processes.

​
Python

Similar to Development but with Python 3.12 pre-installed. Great for data analysis, scripting, and ML tasks.
SettingValue
Imagepython:3.12-alpine
Memory512 MB
Timeout60s
CPU shares512
NetworkEnabled
Workdir/workspace
Best for: Python scripts, pip package installation, data processing, Jupyter-style tasks.

​
Restricted

The most locked-down profile. Minimal resources, no network, very short timeout. Use this when running untrusted or potentially dangerous commands.
SettingValue
Imagealpine:latest
Memory64 MB
Timeout10s
CPU shares256
NetworkDisabled
Workdir/workspace
Best for: Evaluating untrusted code, sandboxing risky commands, maximum isolation scenarios.

​
Command risk assessment

The sandbox includes a built-in command risk scoring system that classifies commands into four levels:
Risk levelExamplesDescription
Criticalrm -rf /, mkfs, dd of=/dev/..., fork bombsSystem-destroying commands
Highsudo, su, chmod 777, `curlsh, eval`Privilege escalation, piped execution
Mediumcurl, wget, rm, pip install, npm install, aptNetwork access, file modifications, package installs
Lowls, cat, echo, grepRead-only, safe operations
:::info Risk assessment is informational — it helps you understand what agents are doing. The sandbox enforces isolation regardless of risk level. All capabilities are dropped and containers are ephemeral. :::

​
Bind mounts

You can mount host directories into the container to give agents access to specific files: 
/home/user/project:/workspace:ro
Format: host_path:container_path:mode
ModeDescription
roRead-only access
rwRead-write access
:::warning Be careful with rw mounts — the agent can modify files on your host filesystem through the container. Use ro when the agent only needs to read files. :::

​
Use cases

​
Safe code execution

Let agents run code in a sandboxed environment where mistakes can’t damage your system: 
You: Write and run a Python script that calculates prime numbers up to 1000

Agent: [uses exec tool → runs inside Python sandbox container]

​
Untrusted command evaluation

When an agent suggests a shell command you’re unsure about, the sandbox provides a safety net:
  • If the command is destructive, it only affects the ephemeral container
  • All Linux capabilities are dropped, preventing privilege escalation
  • Network can be disabled to prevent data exfiltration

​
Build and test isolation

Run project builds and test suites without polluting your host environment:
  • Dependencies installed in the container don’t affect your system
  • Failed builds can’t leave behind broken state
  • Each run starts from a clean image
:::tip For development workflows, use the Development or Python preset with bind mounts pointing to your project directory. This gives agents access to your code while keeping execution sandboxed. :::