curl -fsSL https://app.globalstacks.dev/cli/install.sh | sh -s -- --base-url https://app.globalstacks.dev --auth device

irm https://app.globalstacks.dev/cli/install.ps1 | iex

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, places the binary in your install location, and starts device login against this control plane.

The Linux and macOS installer places gstacks in ~/.local/bin by default, registers PATH hooks, installs Bash, Zsh, and Fish completions, and prints manual completion commands if a shell profile cannot be updated. Release artifacts include Linux AMD64, Linux ARM64, macOS AMD64, and macOS ARM64 builds, including Apple Silicon Macs. The Windows installer places gstacks.exe and a gstacks command shim in %LOCALAPPDATA%\GlobalStacks\bin, prepends that directory to your user PATH, installs PowerShell completion for the current user, and prints the exact dot-source line if your PowerShell profile is not writable.

Authenticate

The recommended installer command starts OAuth device login after installation. The CLI prints a verification URL and one-time user code, opens the browser when it can, and waits while you approve access in the console. Complete the browser consent flow once for each control plane. The CLI stores the base URL and rotating OAuth tokens in the local config file.

After successful login, you should see:

authenticated

API-key login remains available for automation that cannot use device login.

Run device login manually when gstacks is already installed:

gstacks auth device-login --base-url <control-plane-url>

Show the installed CLI version:

gstacks version

Upgrade the installed CLI in place:

gstacks upgrade

The installer and gstacks upgrade also refresh shell completion files for the current user. Windows installs PowerShell completion; Linux and macOS install Bash, Zsh, and Fish completion.

Generate shell completion:

gstacks completion zsh
gstacks completion bash
gstacks completion fish
gstacks completion powershell

Common tasks

List connected hosts:

gstacks host list

Inspect one host with routing metadata:

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

Open an interactive host terminal:

gstacks host ssh <host-id-or-name>

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 a sandbox terminal or install OpenSSH aliases for sandbox SSH clients:

gstacks sandbox ssh <sandbox-id-or-name>
gstacks ssh config --write
ssh gs-<sandbox-name>

Create a write-only Access secret and an outbound policy:

gstacks access secret create example-token --value-env EXAMPLE_TOKEN
gstacks access policy create api-example \
  --host api.example.com \
  --header 'Authorization=Bearer {{secret:example-token}}' \
  --header 'X-Tenant=customer-123'

Access policy headers are generic safe outbound request headers. They are not limited to authentication headers, and provider-specific helpers are layered on top of the same header model when needed.

Connect a source-control provider and repository for Git-backed builds:

gstacks source connection connect internal-gitea \
  --provider gitea \
  --transport https \
  --base-url https://git.example.com \
  --username git-user \
  --value-env GITEA_TOKEN

gstacks source repo connect rustfs-extension \
  --connection <source-connection-id> \
  --url https://git.example.com/global-stacks/global_stacks_integrations.git \
  --default-branch main

Use that repository connection when building a blueprint or extension runtime from a private repository:

gstacks build create \
  --name rustfs-runtime \
  --repo-connection <repository-connection-id> \
  --ref extensions/rustfs/v0.1.0 \
  --context extensions/rustfs \
  --dockerfile extensions/rustfs/Dockerfile \
  --cluster-id <cluster-id> \
  --follow

gstacks extensions setup rustfs \
  --cluster-id <cluster-id> \
  --repo-connection <repository-connection-id>

gstacks sandbox create \
  --cluster-id <cluster-id> \
  --blueprint dev-ready \
  --repo-connection <repository-connection-id> \
  --repo-path /workspace/app

Source-control connections are backed by broker secrets and brokered Access policies. Build and sandbox bootstrap flows receive provider credentials only through brokered HTTPS authorization headers or the typed Source SSH broker stream. SSH private keys stay in the control-plane trust boundary.

Attach an Access policy to a blueprint or sandbox:

gstacks blueprint access attach dev-ready api-example
gstacks sandbox access attach gssbx_123 api-example
gstacks sandbox egress gssbx_123

Access egress is transparent-only. Unsupported runtimes report Access egress as unavailable instead of requiring application-level proxy configuration.

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>

Generate OpenSSH config entries for GlobalStacks sandbox aliases:

gstacks ssh config --gateway-host ssh.globalstacks.dev --cli-binary gstacks.exe

Append the generated block to your OpenSSH config. After that, connect to a sandbox by stable ID or by name:

ssh gs-<sandbox-name>
ssh gssbx_<sandbox-id>

On Windows, write the managed OpenSSH config block directly:

gstacks ssh config --write --gateway-host ssh.globalstacks.dev --cli-binary gstacks.exe

This writes %USERPROFILE%\.ssh\globalstacks.conf and adds a managed Include block to %USERPROFILE%\.ssh\config. VS Code Remote-SSH and Cursor Remote-SSH can then connect to gs-<sandbox-name> or direct gssbx_<sandbox-id> aliases through the GlobalStacks SSH gateway.

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.