WBX Sandbox
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.
  1. 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.

  2. 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 curl and jq. The same calls work from any language.

  3. 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"
  4. 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"

Next steps