Docs/ AI Assistant/ AI Sandbox

AI Sandbox

A full-featured Alpine Linux container that gives the AI assistant hands-on access to your application environment for debugging, testing, and analysis.

What is the AI Sandbox

The AI Sandbox is a dedicated Alpine Linux container that runs alongside your application. It shares the app's network namespace, meaning it can reach your app via localhost, and has access to the app's mounted volumes. This gives the AI assistant a real environment to work in -- not a simulation.

Inside the sandbox, the AI can install packages, clone repositories, build and run applications, inspect files, test network connectivity, and execute arbitrary commands. It is the difference between an AI that reads logs and guesses, and an AI that can actually poke at your running service.

Enabling the Sandbox

The sandbox is disabled by default. To enable it, go to your app's Settings page in the dashboard and toggle AI Sandbox on. Alternatively, use the API:

Terminal

curl -X PATCH https://your-server:9000/api/v1/apps/:id \
  -H "Authorization: Bearer $SH0_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sandbox_enabled": true}'

Tip

The sandbox is created on-demand when the first sandbox tool is called. If you toggle sandbox_enabled but never use a sandbox tool, no container is created.

Container Specifications

Each sandbox container is provisioned with the following specifications:

Property	Value
Image	Alpine 3.19
User	root
RAM	1 GB
CPU	2 cores
Network	Shared with app (container network mode)
Volumes	App volumes mounted (writable)
Command timeout	5 minutes
Output limit	100 KB
Pre-installed tools	`curl`, `wget`, `dig`, `nc`, `jq`, `git`, `node`, `npm`, `python3`, `pip`, `bash`

What AI Can Do

With sandbox access, the AI assistant can perform hands-on debugging and analysis:

Debug application endpoints

Since the sandbox shares the app's network, the AI can call your application directly:

Sandbox

curl localhost:3000/health
curl -v localhost:8080/api/users | jq .

Analyze source code and dependencies

Clone the repository, install dependencies, and inspect the project:

Sandbox

git clone https://github.com/user/app.git /tmp/app
cd /tmp/app && npm install
npm audit

Test connectivity

Verify that services can reach each other:

Sandbox

nc -zv db 5432
dig redis.internal
curl -s http://api:8000/healthz

Inspect files and logs

Read configuration files, environment files, and log output from mounted volumes:

Sandbox

cat /app/config/production.json
ls -la /app/logs/
tail -100 /app/logs/error.log

Run code and test fixes

Execute scripts and validate fixes before applying them to the actual application:

Sandbox

python3 -c "import json; print(json.loads(open('/app/config.json').read()))"
node -e "const db = require('./db'); db.ping().then(console.log)"

Sandbox Tools

The AI interacts with the sandbox through five dedicated MCP tools:

Tool	Risk	Description	Example
`sandbox_exec`	Medium	Execute a command in the sandbox container	`curl localhost:3000/health`
`sandbox_read_file`	Low	Read a file from the sandbox filesystem	`/app/config.json`
`sandbox_write_file`	High	Write a file to the sandbox filesystem	`/tmp/test-script.sh`
`sandbox_status`	Low	Check if the sandbox is running and healthy	--
`sandbox_reset`	Medium	Destroy and recreate the sandbox container	--

Lifecycle

The sandbox container follows the lifecycle of its parent application:

Created: On-demand when the first sandbox tool is invoked. Creation is non-blocking and happens asynchronously after deploy.
Started: Automatically when the parent app starts. The sandbox stays running as long as the app is running.
Stopped: When the parent app is stopped. The sandbox container is stopped alongside it.
Destroyed: When the parent app is deleted. The sandbox container and all its data are permanently removed.

The sandbox has no restart policy. If it crashes, it stays stopped until the next sandbox tool call triggers a recreation.

Command Validation

The sandbox applies a minimal blocklist to prevent catastrophic operations. The following commands are rejected:

rm -rf / -- filesystem destruction
mkfs -- disk formatting
shutdown / reboot -- host-level operations
Fork bombs (e.g., :() patterns)

Everything else is allowed. The sandbox is intentionally permissive because its purpose is to give the AI the same capabilities a human developer would have when debugging. The container itself is the security boundary, not the command filter.

Security Model

The sandbox's security model relies on container isolation rather than command filtering:

Isolated filesystem: The sandbox has its own root filesystem. Only explicitly mounted volumes are shared with the app.
Resource limits: Hard caps on RAM (1 GB) and CPU (2 cores) prevent resource exhaustion on the host.
Disposable: The container can be destroyed and recreated at any time without affecting the application.
No restart policy: A crashed sandbox does not restart automatically, preventing infinite crash loops.
Command timeout: Every command has a 5-minute timeout to prevent runaway processes.
Output cap: Command output is truncated at 100 KB to prevent memory exhaustion in the MCP transport.

Warning

The sandbox has write access to your app's volumes. While this is necessary for AI to properly debug and test, be aware that the AI can modify files in mounted volumes.

MCP Server

Tools Reference