RareCloud AI Sandboxes: run untrusted code from your agent

In one paragraph: an AI sandbox is a small, isolated Linux environment that you create with one API call, use to run code an AI model wrote (or anything else you do not want on your own machines), and throw away when you are done. Each sandbox runs in its own hardened container in our European cloud region (Bucharest), cannot see other customers or our internal networks, and can reach the public internet so pip install and npm install work. You drive it through the public API at https://api.rarecloud.io/v1, the CLI (version 0.4.0) or the Terraform provider (version 0.4.0). AI Sandboxes are in beta; the section What is not ready yet lists exactly what still behaves differently from the final product.

Before you start

• A RareCloud account and an API token. Create the token in the console under Account, then API tokens with services:read (list, get, read files) and services:write (create, run, write files, delete). Scopes match exactly, so :write does not include :read.
• The CLI, the Terraform provider, or any HTTP client. The examples use the CLI and curl:

export RARECLOUD_TOKEN=rc_pat_...

Templates

A template decides what is installed and how big the sandbox is.

Every template runs as an unprivileged user (uid 10001) in /home/user. The system files are read only; /home/user (2 GB) and /tmp (1 GB) are writable and last as long as the sandbox does. Through the API you can also start from your own public container image by passing image (for example "image": "nginx:1.27"); the template you pick still sets the size. Private images are not supported yet. In 0.4.0 the CLI takes a custom image with rarecloud sandbox create --image <ref>, and the Terraform provider with the image argument of rarecloud_sandbox (changing it replaces the sandbox).

Step by step

1. Create a sandbox

rarecloud sandbox create --template python

curl -s https://api.rarecloud.io/v1/sandboxes \
  -H "Authorization: Bearer $RARECLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "python"}' | jq .data

The response carries the sandbox id (it starts with sbx-), its status (pending, running or terminated), the template, createdAt and timeoutMs. A new sandbox is pending for a few seconds while it starts; a call made too early answers that the sandbox is not ready yet, so retry shortly.

2. Run code

rarecloud sandbox run <id> --code 'import pandas as pd; print(pd.__version__)'
rarecloud sandbox run <id> --file analysis.py
echo 'console.log(6 * 7)' | rarecloud sandbox run <id> --language node

curl -s https://api.rarecloud.io/v1/sandboxes/<id>/run_code \
  -H "Authorization: Bearer $RARECLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"language": "python", "code": "print(2 + 2)"}' | jq .data

You get back stdout, stderr and exitCode. The CLI prints the two streams to your own stdout and stderr and exits with an error when the remote exit code is not zero, so it works in scripts. language is python or node; use the template that has that runtime (the base template has neither).

Each call is a fresh process. Variables and imports do not carry over from one run to the next. Keep state in files (step 4) or send the whole script in one call.

3. Run shell commands

rarecloud sandbox exec <id> -- pip install duckdb
rarecloud sandbox exec <id> -- ls -la /home/user

curl -s https://api.rarecloud.io/v1/sandboxes/<id>/commands \
  -H "Authorization: Bearer $RARECLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cmd": "python -c \"import sys; print(sys.version)\""}' | jq .data

The command runs with sh -c, so pipes and && work. The CLI joins everything after -- into one command line; quote anything your local shell would otherwise expand.

4. Read and write files

From the CLI 0.4.0 use rarecloud sandbox files get <id> <path> and rarecloud sandbox files put <id> <path>, or the API calls below. Paths must be absolute, and parent directories are created for you.

# Write a file
curl -s -X PUT https://api.rarecloud.io/v1/sandboxes/<id>/files \
  -H "Authorization: Bearer $RARECLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/user/data.csv", "content": "a,b\n1,2\n3,4\n"}'

# Read it back
curl -s "https://api.rarecloud.io/v1/sandboxes/<id>/files?path=/home/user/data.csv" \
  -H "Authorization: Bearer $RARECLOUD_TOKEN" | jq -r .data.content

File content travels as a text string (up to 1,000,000 characters per write). For binary data, encode it (for example base64) and decode it inside the sandbox with a command.

5. List and delete

rarecloud sandbox list
rarecloud sandbox get <id>
rarecloud sandbox rm <id>

curl -s -X DELETE https://api.rarecloud.io/v1/sandboxes/<id> \
  -H "Authorization: Bearer $RARECLOUD_TOKEN"

Delete every sandbox when you are done with it. A sandbox is stopped and deleted when its lifetime (timeoutMs, shown as expiresAt) runs out, and billing stops then at the latest, but deleting it earlier stops the charge sooner.

Every CLI command

From the 0.4.0 release binary. rarecloud sbx and rarecloud sandboxes are aliases for rarecloud sandbox, and every command accepts the global flags (-o json, --token, --api). sandbox create --run (or --entrypoint, or a command after --) starts the image's own program instead of waiting for commands; the sandbox ends when it exits, and sandbox logs shows its output.

Terraform

The rarecloudio/rarecloud provider 0.4.0 has one sandbox resource. Terraform creates and deletes sandboxes; running code in them is done with the CLI or the API.

rarecloud_sandbox

Exports id, status (pending, running, terminated, or exited in run mode), created_at, expires_at (when the sandbox stops and is deleted) and exit_code (run mode, once the program has exited). A sandbox that no longer exists drops out of state and is created again on the next apply; an exited run-mode sandbox disappears 24 hours after it ended.

resource "rarecloud_sandbox" "ci" {
  template   = "python"
  timeout_ms = 300000 # 5 minutes
}

output "sandbox_id" {
  value = rarecloud_sandbox.ci.id
}

rarecloud sandbox run "$(terraform output -raw sandbox_id)" --code 'print("hello")'

MCP tools

The MCP server (@rarecloudio/mcp-server 0.4.0) has ten sandbox tools: list_sandboxes, get_sandbox, list_sandbox_templates, read_sandbox_file, get_sandbox_logs, create_sandbox, delete_sandbox, run_sandbox_code, run_sandbox_command and write_sandbox_file. They answer 503 until AI Sandboxes launch in production.

API reference

All routes are under https://api.rarecloud.io/v1 with Authorization: Bearer <token>. Responses use the { "ok": true, "data": ... } envelope; errors are { "ok": false, "error": { "code", "message" } }.

A sandbox id that belongs to another account answers 404, exactly like one that does not exist.

Isolation and network

• Each account gets its own isolated space; sandboxes of different customers never share it.
• Nothing can connect into a sandbox from outside.
• A sandbox can connect out to the public internet on any port (package indexes, git, your own APIs). Private address ranges, link-local addresses (including cloud metadata services) and our internal networks are blocked.
• A sandbox never holds credentials for the platform it runs on.

Limits

What is not ready yet

AI Sandboxes are a beta. These are the gaps today, all checked against the current code:

• Preview URLs are not available. POST /sandboxes/{id}/ports/{port} answers 501 and sandbox expose says so: a sandbox accepts no inbound connections. Read results with run, exec, logs or the files commands.
• The prices below are provisional. Runtime is metered per second, from the moment the sandbox runs until you delete it or it expires, onto the monthly cloud invoice.
• Rich results are not returned. run_code gives you stdout, stderr and the exit code; charts and dataframes are not sent back as objects. Save a chart to a file and read the file instead.
• Private custom images are not supported, only public ones.
• Test mode: outside production the API can answer in a test mode where every response carries "mocked": true and code is not really executed. Treat any response with mocked as a test answer, never as a real result. Production never answers in test mode: without a sandbox cluster every sandbox call answers 503.

Pricing

Provisional beta prices. Billed per second from when the sandbox first runs until you delete it or it expires, on your cloud invoice.

That is EUR 0.04 per vCPU per hour plus EUR 0.012 per GB of RAM per hour. These numbers can change before general availability.

Troubleshooting

Links

• API reference: console.rarecloud.io/docs/api
• CLI releases: github.com/RareCloudio/rarecloud-cli
• Terraform provider: registry.terraform.io/providers/rarecloudio/rarecloud
• Product page: AI Sandboxes