Run Your First Sandbox
Run Your First Sandbox
This walkthrough runs the minimal local sandbox lifecycle through API + worker.
Prerequisites
- local setup completed from
getting-started/local-development.md - API and worker are running
1) Create a sandbox request
curl -X POST http://localhost:4000/v1/sandboxes \
-H 'content-type: application/json' \
-d '{
"registryId": "default",
"repository": "sealant/workspaces/demo",
"tag": "opencode",
"spec": {
"source": "https://github.com/example/repo",
"harness": "opencode",
"os": "nix",
"target": {
"runtime": "docker"
}
}
}'Expected result: 202 response with a sandboxId.
2) Poll sandbox status
curl "http://localhost:4000/v1/sandboxes?ownerUserId=<userId>"
curl "http://localhost:4000/v1/sandboxes/<sandboxId>"Common statuses include queued, running, succeeded, and failed.
3) Optional low-level job inspection
If you have a job id:
curl "http://localhost:4000/v1/workspace-build-jobs/<jobId>"This route is internal/operator-oriented compared to the primary sandbox lifecycle routes.
4) Verify image in registry
curl "http://localhost:4000/v1/registries/default/tags?repository=sealant/workspaces/demo"5) Troubleshoot quick checks
404 Unknown registry: verifyregistryIdmatchesREGISTRY_NAME(defaultdefault).502from create sandbox: check RabbitMQ reachability/config.failedstatus: inspect worker logs and stored error payloads.