Python client
SandboxClient — a thin typed wrapper over the gateway HTTP API.
SandboxClient wraps the same HTTP API described in this documentation. It handles
the base URL, the credential header, and correlation-id propagation, so you are not
assembling requests by hand.
from sandbox_core.clients.sandbox_client import SandboxClient
client = SandboxClient.from_env() # SANDBOX_GATEWAY_URL + SANDBOX_API_KEYRequest bodies are passed as dictionaries matching the schemas in the API reference — the client does not redefine them, so anything valid on the wire is valid here.
Synchronous methods
client.catalog(kind="agent")
client.run_code_execution(
{"language": "python3.12", "files": {"main.py": "print(1)"}}
)
client.run_agent(
{
"agent_id": "opencode",
"instruction": "list the files",
"model": "anthropic/claude-sonnet-4-5",
},
correlation_id="my-eval-run-42",
)Asynchronous methods
Benchmark submission and everything job-keyed is async:
job_id = await client.submit_execute_tasks(
{
"task_slug": "example",
"metadata": {"task_archive_url": "https://storage.example/tasks/example.zip"},
"agents": [{"name": "a", "harbor_agent": "oracle"}],
},
correlation_id="my-eval-run-42",
)
record = await client.get_job(job_id)
inventory = await client.list_job_artifacts(job_id)
archive = await client.get_artifact_archive_bytes(job_id)run_datapoint(body) is the synchronous-on-the-wire variant: it awaits the
completed result instead of returning a job id. Use submit_execute_tasks for
anything long-running — see
synchronous vs. asynchronous.
To follow a run rather than poll it:
async for event in client.stream_job_events(job_id, last_event_id=None):
print(event)Pass last_event_id to resume after a dropped connection instead of replaying from
the start.
Other methods
| Method | Purpose |
|---|---|
cancel_job(job_id) | Request cancellation |
retry_errored_trials(job_id) | Enqueue a follow-up job that refills only errored pass@k attempts |
get_test_stdout_bytes(job_id, path) | One verifier's captured output |
harbor_capabilities() / agent_capabilities() | What this deployment supports |
healthz() / sandbox_healthz() | Liveness, unauthenticated and authenticated |
Correlation ids
Pass correlation_id= on submission and the client sends it as x-correlation-id,
which the platform carries through logs, traces and async jobs. Use one stable id per
logical run: Observability.