API reference

GlobalStacks now ships contract sources in-repo:

• openapi/openapi.yaml for the HTTP control-plane API
• proto/globalstacks/agent/v1/control_plane.proto for the agent-control WebSocket API

Current API coverage includes:

• authentication and current-user session status
• infrastructure clusters for BYO and GlobalStacks-managed sandbox capacity
• connected hosts, host overview, host logs, host terminal sessions, and routing metadata
• sandboxes, sandbox terminal sessions, and runtime activity
• sandbox blueprints under /api/blueprints, including image-backed create, list, get, activate, deactivate, and delete
• blueprint capture from existing sandboxes with POST /api/sandboxes/{sandboxId}/blueprints
• blueprint registry discovery, repository inventory, artifact inventory, and short-lived credential issuance under /api/registry
• external registry connections under /api/registry-connections
• runtime networks under /api/networks, including members, aliases, policies, routes, mesh join, and agent-backed diagnostics
• control-plane volume resources under /api/volumes, including detached create and first-class attachment records under /api/volumes/{volumeId}/attachments
• provisioning tokens and CLI API keys
• provisioning tokens are cluster-scoped and can only target BYO clusters
• interactive host terminal sessions are carried through the connected agent transport
• control-plane-managed feature operations should use typed agent APIs; volume lifecycle must move to first-class agent RPCs rather than shell-proxied command execution

Naming conventions

• HTTP collection endpoints use plural resource names such as /api/clusters, /api/hosts, /api/sandboxes, and /api/volumes
• record-specific operations hang off those collection paths, for example /api/hosts/{hostId} or /api/volumes/{volumeId}/attachments/{attachmentId}
• the operator CLI intentionally uses singular command namespaces, for example gstacks host ..., gstacks volume ..., and gstacks sandbox ...

Volume model

• volumes are control-plane resources, not host-owned records
• POST /api/volumes creates a detached volume record
• POST /api/volumes/{volumeId}/attachments creates a first-class attachment record
• DELETE /api/volumes/{volumeId}/attachments/{attachmentId} removes one attachment record
• attachment records are intentionally immutable; change is modeled as delete-and-recreate
• current implementation supports both host and sandbox attachments through that attachment collection
• creating a sandbox attachment auto-realizes the required host-side volume attachment when needed
• the current agent implementation realizes many logical volumes on one host as subdirectories inside one shared JuiceFS filesystem mount
• sandbox bind-mount intent is applied by the host agent runtime
• the public HTTP API does not expose JuiceFS-specific tuning fields
• interactive host shell transport is not the execution path for volume lifecycle; using shell-proxied gstacks-agent volume ... commands is not an acceptable long-term transport

Network model

• POST /api/networks creates an explicit runtime network boundary
• POST /api/sandboxes/{sandboxId}/networks/{networkId}/attach attaches a sandbox and publishes aliases
• aliases are unique within a network and resolve as <alias>.<network>.gstacks
• GET /api/networks/{networkId}/routes lists published aliases and ports
• POST /api/networks/{networkId}/mesh-join issues short-lived credentials for local mesh access
• POST /api/networks/{networkId}/diagnostics asks participating agents to run read-only mesh checks
• network diagnostics are agent-executed typed control messages, not host shell commands

Blueprint model

• GET /api/blueprints lists blueprint records for the active tenant
• POST /api/blueprints creates an image-backed blueprint from name, image, optional description, optional registry_connection_id, and optional metadata
• GET /api/blueprints/{blueprintId} returns one blueprint
• POST /api/blueprints/{blueprintId}/activate marks a blueprint usable for sandbox creation
• POST /api/blueprints/{blueprintId}/deactivate keeps the record and artifact metadata but removes it from sandbox creation
• DELETE /api/blueprints/{blueprintId} removes an unused blueprint record and is blocked while live sandboxes reference it
• POST /api/sandboxes/{sandboxId}/blueprints creates a blueprint record from an existing sandbox and preserves source-sandbox provenance
• POST /api/sandboxes accepts either image or blueprint; requests that set both are rejected
• when blueprint is provided, the control plane resolves the active blueprint by ID or unique name, uses its immutable artifact_ref as the sandbox image source, and stores source_blueprint_id on the sandbox record
• POST /api/sandboxes also accepts optional repository bootstrap fields: repository_id, repository_url, repository_branch, repository_commit, repository_path, and repository_credential_secret_ref
• repository bootstrap metadata is returned on the sandbox record with repository_bootstrap_status, repository_url, repository_branch, repository_commit, and repository_path

Created blueprints are stored in the internal blueprint repository. External registries are read-only sources for image-backed blueprints; GlobalStacks records the source connection and publishes its own internal artifact reference for later sandbox provisioning.

The current retention policy is conservative: deactivate blueprints that should no longer be selected for new sandboxes, delete only unused blueprint records, and retain internal artifact metadata for auditability.

Registry model

• GET /api/registry returns internal blueprint registry discovery data, including URL, namespace, storage driver, S3 configuration status, supported digest behavior, and default credential TTL
• /registry/v2/ serves the embedded OCI registry API for internal blueprint artifacts
• GET /api/registry/repositories lists internal blueprint repositories
• GET /api/registry/artifacts lists locally published blueprint artifacts and digest references
• POST /api/registry/credentials issues a short-lived pull or push credential scoped to a repository and optional artifact
• GET /api/registry-connections lists external source registry connections
• POST /api/registry-connections creates an external source registry connection with provider, URL, username, secret reference, project, TLS, and metadata fields
• GET /api/registry-connections/{registryConnectionId} returns one external source registry connection
• PATCH /api/registry-connections/{registryConnectionId} updates one external source registry connection
• DELETE /api/registry-connections/{registryConnectionId} deletes a registry connection when no active blueprint depends on it

Internal registry pull credentials are short-lived and scoped to one repository action. Agents request pull credentials through the typed control-plane stream before pulling blueprint artifacts by digest. Registry credentials are stored as secret references, not plaintext passwords. Provider aliases are normalized for Docker Hub, GHCR, GitLab, AWS ECR, Google Artifact Registry, Azure Container Registry, and custom registries. A blank Docker Hub registry URL defaults to https://docker.io.

S3-backed blueprint repository storage is the durable mode for production. In that mode, manifests, blobs, and upload state live in the configured S3-compatible bucket and local files are only rebuildable cache. Local filesystem storage remains useful for development and single-node testing. Agents cache blueprint images locally by immutable digest, report cache status to the control plane, and can receive warm-cache jobs so placement can prefer an already-warmed host when capacity and policy are otherwise comparable.

Recommended usage

For product usage:

• use the console for interactive workflows
• use gstacks for supported command-line workflows
• use the contract files when building tooling, tests, or integrations against the current control-plane surface

Contract files

• HTTP: openapi/openapi.yaml
• Generated TypeScript types: openapi/generated/types.d.ts
• WebSocket: proto/globalstacks/agent/v1/control_plane.proto