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

Host agent

The GlobalStacks host agent connects 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
• runtime network DNS, proxying, mesh membership, policy checks, and diagnostics
• blueprint capture, image cache reporting, and image cache warming
• sandbox volume bind-mount realization when a volume attachment targets a sandbox

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.

CLI touchpoints

Use gstacks for operator workflows against the control plane:

gstacks host list
gstacks host terminal <host-id>
gstacks sandbox create --host-id <host-id>

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.