curl -fsSL https://app.globalstacks.dev/cli/install.sh | sh

gstacks auth login --base-url https://app.globalstacks.dev --api-key <key>

gstacks CLI

Use gstacks when you want repeatable command-line access to the control plane.

CLI naming convention:

• operator-facing command namespaces are singular, for example gstacks host ..., gstacks volume ..., and gstacks sandbox ...
• HTTP API endpoints remain plural collection paths such as /api/hosts, /api/sandboxes, and /api/volumes

Install

Run the installer command on this page. It downloads the latest CLI release and places the binary in your install location.

Authenticate

Create a CLI API key in the GlobalStacks console, then run the login command on this page once for each control plane. The CLI stores the base URL and API key in the local config file.

After successful login, you should see:

authenticated

Show the installed CLI version:

gstacks version

Upgrade the installed CLI in place:

gstacks upgrade

The installer and gstacks upgrade also refresh the Bash, Zsh, and Fish completion files for the current user.

Generate shell completion:

gstacks completion zsh
gstacks completion bash
gstacks completion fish

Common tasks

List connected hosts:

gstacks host list

Inspect one host with routing metadata:

gstacks host info --host-id <host-id>

Update operator-managed host routing rules:

gstacks host update --host-id <host-id> --tag pool:edge --sandbox-eligible true

Ownership and classification remain control-plane managed and are not mutable from the CLI.

List control-plane volumes:

gstacks volume list

Volumes are created detached from any host:

gstacks volume create <volume-id>

Inspect one volume:

gstacks volume info <volume-id>

List one volume’s attachments:

gstacks volume attachment list <volume-id>

Create a host attachment:

gstacks volume attachment create <volume-id> --target-kind host --target-id <host-id>

Create a sandbox attachment:

gstacks volume attachment create <volume-id> --target-kind sandbox --target-id <sandbox-id> --mount-path /data

Delete one attachment:

gstacks volume attachment delete <volume-id> <attachment-id>

Current implementation note:

• a detached volume becomes available on a host by creating a host attachment
• on a given host, many logical volumes share one underlying JuiceFS filesystem mount and use separate subdirectories
• a sandbox attachment can auto-realize the required host attachment and carry the bind mount into the sandbox runtime
• --read-only is currently meaningful for sandbox attachments
• attachment records are immutable; to change mount path or read-only mode, delete the attachment and create a new one

Create a runtime network:

gstacks network create dev

Attach a sandbox to the network and publish an alias:

gstacks network attach dev <sandbox-id> --alias api --port 8080

Manage aliases:

gstacks network alias list dev
gstacks network alias add dev <sandbox-id> worker --port 9090
gstacks network alias remove dev worker

Allow and test traffic:

gstacks network policy allow dev --from local --to api --port 8080
gstacks network resolve dev api
gstacks network test dev local api:8080

Join the mesh locally or forward one service:

gstacks mesh join dev
gstacks mesh status
gstacks mesh forward dev api:8080 --local 18080

Open an interactive host shell:

gstacks host ssh --host-id <host-id>

The shell is proxied through the connected host agent. The control plane does not expose its own server shell for host access.

This shell path is only for interactive operator access. Control-plane-managed features must not depend on shell-proxied host commands.

Check or clear the local single-instance lock used by the host agent service:

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

List sandboxes:

gstacks sandbox list

List archived sandboxes only:

gstacks sandbox list --archived

List stopped sandboxes only:

gstacks sandbox list --stopped

sandbox list shows the sandbox status, the assigned host with its connection state, the image, and the requested CPU and memory. Archived sandboxes are hidden by default.

Create a sandbox with routing constraints:

gstacks sandbox create --host-id <host-id> --require-trait docker --require-tag pool:edge

Inspect one sandbox:

gstacks sandbox info <sandbox-id>

Deprovision and archive a sandbox while retaining its record and logs:

gstacks sandbox delete <sandbox-id>

Stop one sandbox:

gstacks sandbox stop <sandbox-id>

Start one stopped sandbox:

gstacks sandbox start <sandbox-id>

Open an interactive sandbox shell:

gstacks sandbox ssh <sandbox-id>

Inspect the current CLI reference payload used by the docs site:

gstacks reference-json

Config file

By default, the CLI stores its config at:

~/.config/gstacks/config.json

Use --config-file if you need an alternate location in automation or when working with multiple environments.

Next step

Use the CLI Reference page for exact command flags and examples.