Architecture (integrator view)
How the Sandbox gateway routes requests — logical model for API consumers.
L4 products (Prism, CTP, DynamicSession, FinanceOTS, trainers) call one hostname — the gateway — and pick routes by intent. You do not talk to Harbor workers, Pub/Sub, or cloud drivers directly.
Platform engineering detail (L0–L4 layers, package graph, ADRs) lives in the GitHub repo, not here:
Logical topology
| Surface | Prefix | Typical use |
|---|---|---|
| Catalog | /sandbox/v1/catalog | Discover agents, languages, profiles |
| Harbor | /sandbox/harbor/v2/... | Benchmark datapoint, async jobs, SSE |
| Agent Runtime | /sandbox/agent/v1/... | Ad-hoc agentic runs (harbor_extensions) |
| CodeEdit | /sandbox/codeedit/v1/... | Sandboxed code execution |
| Browser | /sandbox/browser/v1/... | Remote browser sessions |
| CI Runner | /sandbox/cirunner/v1/... | CI-style runs in sandbox |
| Admin | /sandbox/v1/admin/credential-plane/... | KeyHive teams / LLM keys |
Request lifecycle (Harbor job)
Agent Runtime uses POST /sandbox/agent/v1/runs (202) with the same auth headers; catalog union at GET /sandbox/agent/v1/agents.
Trust boundaries (what you need to know)
| Boundary | Integrator responsibility |
|---|---|
| Internet → gateway | Send X-Api-Key or KeyHive Bearer; TLS in prod |
| Gateway → services | Transparent — same hostname, path prefix selects backend |
| Credentials | Use credential-plane admin routes or pre-provisioned KeyHive tokens — never embed cloud keys in task payloads |
Internal boundaries (L2 quota, Redis admission, Pub/Sub, GCS, K8s drivers) are owned by the platform — see HLD in GitHub if you operate the cluster.
Contract artifacts
Same hostname as the API — paths work in every environment:
| Artifact | Path |
|---|---|
| This docs site | /docs |
| Merged OpenAPI | /openapi/sandbox-platform.yaml |
| Postman collection | docs/postman/sandbox_platform.postman_collection.json in the repo |
| Engineer Swagger | /internal/swagger |
Local default gateway: http://localhost:8780 · Production: https://sandbox.turing.com (or your deployed ingress host).