curl -fsSL https://app.globalstacks.dev/install.sh | sh -s -- --role provisioning

Host agent

The GlobalStacks host agent connects Linux, Linux ARM64, macOS, Apple Silicon, Windows, Proxmox, and other infrastructure you operate to the control plane. It is the local process that reports host state, accepts typed control-plane requests, and performs runtime work on the target host.

The agent is not a general-purpose shell bridge for product features. Host terminals are interactive operator sessions, while lifecycle operations for sandboxes, networks, blueprints, and volumes use typed agent APIs or control messages.

Responsibilities

The host agent currently owns:

• host enrollment and long-lived control-plane connectivity
• host telemetry, version reporting, architecture reporting, traits, and tags
• sandbox provisioning, start, stop, reprovision, archive, terminal, log, and file access
• Tailscale-compatible mesh membership, runtime network DNS, proxying, policy checks, and diagnostics
• transparent Access egress enforcement for supported sandbox runtimes
• blueprint capture, image cache reporting, and image cache warming
• sandbox volume bind-mount realization when a volume attachment targets a sandbox

The release channel publishes host-agent artifacts for Linux AMD64, Linux ARM64, macOS AMD64, and macOS ARM64. ARM64 hosts report an arm64 trait so placement can distinguish Apple Silicon and ARM Linux capacity when needed.

Enrollment model

Host enrollment starts with a provisioning token from the console. The token is used for registration only. After enrollment succeeds, the control plane issues credentials for normal stream operation.

Provisioning tokens are cluster-scoped. BYO clusters are the current host enrollment path, so a host appears inside the selected cluster and participates in sandbox placement for that cluster.

Runtime model

The agent keeps a long-lived connection to the control plane. Through that connection, the control plane can dispatch typed work to the host without SSHing into the control-plane server.

Sandbox placement depends on the selected cluster, host connectivity, host traits, tags, runtime health, and capacity. When the agent provisions a sandbox, it applies the runtime configuration locally and reports lifecycle and runtime state back to the control plane.

The current Docker-backed sandbox runtime uses classic Docker containers. Docker Sandboxes, the Docker sbx microVM feature, are planned as a separate coming-soon runtime and are not scheduled by the agent yet.

Blueprint-backed sandboxes use the agent’s local blueprint cache. The agent downloads immutable artifacts with scoped control-plane credentials, verifies them by digest, records local cache metadata, and gives the sandbox runtime only a local cache handle. Docker uses a locally loaded image reference; LXC, Firecracker, QEMU, and Proxmox archive runtimes use local artifact paths and validate their configured host tooling before returning a cache handle. Sandbox provisioning fails clearly when the local cache or required runtime tools are missing instead of falling back to a Docker pull from the control plane.

For Access egress, the agent owns transparent runtime interception and the egress component outside the sandbox workload. The sandbox should not need proxy environment variables or application-level proxy configuration. Runtimes are unsupported for Access when the agent cannot control the sandbox network namespace, firewall, routing rules, or attached egress component.

HTTPS egress is split between opaque and intercepted behavior. Opaque HTTPS can be allowed or denied by destination but cannot receive injected HTTP headers. Header injection for HTTPS requires intercepted TLS with sandbox trust configured for a GlobalStacks-controlled CA, and certificate-pinned clients may reject that mode.

Mesh networking

The host agent joins mesh networks with Tailscale tsnet. Cluster-scoped infra meshes connect agents and agent-managed data-plane services without exposing those records to sandbox DNS. User-created sandbox networks connect approved sandbox service aliases across agents.

Sandbox workloads do not run mesh clients or receive mesh credentials. They resolve names such as api.dev.gstacks through the agent DNS path. The agent maps those names to virtual loopback addresses, checks network policy, forwards accepted traffic over the mesh to the target agent, and the target agent delivers the connection to the target sandbox.

CLI touchpoints

Use gstacks for operator workflows against the control plane:

gstacks host list
gstacks host ssh <host-id-or-name>
gstacks sandbox create --host-id <host-id>

Host and sandbox terminals can be opened from the browser console or from the CLI. Both paths create control-plane terminal sessions and stream through the connected host agent.

Use gstacks-agent only for host-local service and diagnostic operations on the machine where the agent is installed:

gstacks-agent service lock status
gstacks-agent service lock clear --force

Do not build product behavior by running gstacks-agent through a host shell session. If a feature changes infrastructure state, it should use a first-class API or typed agent RPC.

Operational checks

After installation, verify:

• the host appears as connected in the console
• the host overview shows the running agent version and architecture
• host logs show agent operational events
• host terminal access is available for operator sessions
• sandbox creation succeeds on eligible hosts

If the host does not appear, check that the provisioning token is valid, the host can reach the control plane, release artifacts are available, and the host service manager started gstacks-agent.

Related docs

• Start with Getting Started for first host enrollment.
• Use CLI for command-line workflows and command naming conventions.
• Use API and Contracts for the HTTP and protobuf contract surfaces.
• Use Sandboxes and Networks for runtime behavior after a host is connected.
• Use the Blueprint Cache Operations runbook for cache warming, archive runtime prerequisites, and troubleshooting.