Get started
Quickstart
Your first sandbox and your first background job in about five minutes – from Python or from any language over HTTPS.
Using ChatGPT or Claude? You don't need any of this – connect your AI with one URL and it creates sandboxes itself.
-
Get an API key
Create a free account, then open API keys and create a key. Treat it like a password – anyone with the key can start sandboxes on your account.
-
Set up your environment
pip install wbxsandbox export WBXSANDBOX_URL=https://sandbox.wbx.cz export WBXSANDBOX_API_KEY=YOUR_API_KEY
One small package without dependencies, Python 3.9 or newer.
export WBX=https://sandbox.wbx.cz export WBX_KEY=YOUR_API_KEY
Nothing to install – the examples use
curlandjq. The same calls work from any language. -
Run code in a sandbox
from wbxsandbox import Sandbox with Sandbox.create(template="base") as sb: # a fresh computer, ready in a moment r = sb.run("python3 -c 'print(6 * 7)'") print(r.exit_code, r.stdout) # 0 42 sb.files.write("/home/user/hello.txt", "hi") print(sb.files.read_text("/home/user/hello.txt")) # leaving the block destroys the sandbox
SB=$(curl -s -X POST $WBX/v1/sandboxes -H "Authorization: Bearer $WBX_KEY" \ -H "Content-Type: application/json" -d '{"template": "base", "timeout_s": 300}' | jq -r .id) curl -s -X POST $WBX/v1/sandboxes/$SB/exec -H "Authorization: Bearer $WBX_KEY" \ -H "Content-Type: application/json" -d '{"cmd": "python3 -c \"print(6 * 7)\""}' # {"exit_code": 0, "stdout": "42\n", "stderr": "", ...} curl -s -X DELETE $WBX/v1/sandboxes/$SB -H "Authorization: Bearer $WBX_KEY" -
Hand over longer work as a job
A background job runs in its own sandbox without an open connection. You come back later for the log, the result files and the cost.
from wbxsandbox import run_job job = run_job(command="mkdir -p output && python3 -c 'print(sum(range(10**7)))' > output/sum.txt", save_artifacts=True, max_cost="0.10") job.wait() print(job.status, job.summary()["cost"]) job.download("output/sum.txt", "sum.txt")JOB=$(curl -s -X POST $WBX/v1/jobs -H "Authorization: Bearer $WBX_KEY" -H "Content-Type: application/json" \ -d '{"command": "mkdir -p output && python3 -c \"print(sum(range(10**7)))\" > output/sum.txt", "artifacts": ["output/"], "max_cost": "0.10"}' | jq -r .id) curl -s -X POST $WBX/v1/jobs/wait -H "Authorization: Bearer $WBX_KEY" -d "{\"job_ids\": [\"$JOB\"]}" curl -s $WBX/v1/jobs/$JOB/artifacts/output/sum.txt -H "Authorization: Bearer $WBX_KEY"