Provider extension

The standard driver contract

A small provider-specific service can connect any full shell sandbox to ArenAPI. It receives normalized requests and returns normalized responses.

Version 2026-07-19

Every request includes x-arenapi-driver-version and x-arenapi-provider. The provider token is forwarded as a bearer credential.

Required routes

Method and path	Response
`POST /sandboxes`	`{"id":"external-id","status":"running","endpoints":{}}`
`GET /sandboxes/:id`	`{"status":"running"}`
`DELETE /sandboxes/:id`	Any successful empty response
`POST /sandboxes/:id/exec`	`{"stdout":"","stderr":"","exit_code":0}`
`GET /sandboxes/:id/files?path=...`	Binary body or base64 object
`PUT /sandboxes/:id/files?path=...`	Accept a binary body
`POST /sandboxes/:id/archive`	Gzip tar binary or base64 object

Create request

{
  "id": "sbx_arenapi_id",
  "image": "python:3.13-slim",
  "timeout_seconds": 300,
  "metadata": {},
  "spec": {},
  "required_capabilities": ["lifecycle", "commands", "files"]
}

Lifecycle states

Return one of creating, running, paused, stopped, destroyed, or failed. Drivers should treat repeated deletion as success.

Deployment boundary

Run drivers on a private network when possible. ArenAPI can call a local or remote driver URL, but production deployments should use encrypted transport and restrict inbound access to the control plane.