Skip to main content

Hosted APIs

SandboxMesh exposes hosted APIs for the SaaS product. Sandbox creation belongs to those hosted services, not to a customer-cluster API.

At a high level:

  • browser-facing portal routes live in portalapi
  • organization-scoped control-plane routes live in the hosted control plane
  • agent-scoped coordination routes live in the hosted control plane
  • customer clusters do not expose a sandbox-creation API

Portal-facing API​

These are the main browser-facing routes used by the hosted portal today:

  • GET /v1/portal/org
  • GET /v1/portal/entitlement
  • GET /v1/portal/clusters
  • POST /v1/portal/clusters
  • GET /v1/portal/sandboxes
  • GET /v1/portal/sandboxes/{sandboxId}
  • POST /v1/portal/sandboxes
  • DELETE /v1/portal/sandboxes/{sandboxId}

These routes are the normal user-facing sandbox management surface for the SaaS product.

Local MCP wrapper​

The sb CLI can now expose a local stdio MCP server with sandbox and cluster tools:

SANDBOX_MESH_PORTAL_API_URL=https://portal-api.example \
SANDBOX_MESH_PORTAL_TOKEN=<workos-access-token> \
SANDBOX_MESH_PORTAL_ORG=<org-id> \
sb mcp serve

That MCP server is a local wrapper over the hosted portal API. It does not add a separate hosted MCP backend, and it does not expose customer-cluster sandbox CRUD.

Control-plane routes​

The hosted control plane also exposes organization-scoped routes used by internal services and portal backends.

Examples include:

  • PUT /v1/orgs/{orgId}
  • PUT /v1/orgs/{orgId}/entitlement
  • POST /v1/orgs/{orgId}/clusters:register
  • POST /v1/orgs/{orgId}/sandboxes
  • GET /v1/orgs/{orgId}/sandboxes

These routes own authoritative sandbox state, cluster registration, entitlements, and lease allocation.

Agent routes​

Cluster agents use a separate hosted coordination surface:

  • POST /v1/agent/session
  • POST /v1/agent/heartbeat
  • GET /v1/agent/assignments
  • POST /v1/agent/assignments/{sandboxId}/status

The agent uses these routes to authenticate, renew short-lived sessions, fetch leased assignments, and report local runtime status back to the control plane.

API semantics to keep in mind​

  • Hosted sandbox creation is asynchronous and returns 202 Accepted.
  • Quota exhaustion is represented as PendingCapacity, not as an immediate create failure.
  • Cluster registration returns the bootstrap token once at registration time.
  • Entitlement writes replace the stored entitlement state rather than incrementing it.
  • Customer clusters receive work through the agent pull loop rather than through an in-cluster sandbox CRUD API.