Runtime networks

Networks are explicit runtime boundaries for sandbox connectivity. They are not environment settings and they are not derived from sandbox names.

Each network publishes aliases under:

<alias>.<network>.gstacks

For example:

api.dev.gstacks
postgres.dev.gstacks

Aliases are unique within a network. A sandbox can publish more than one alias, and each alias exposes one or more ports.

Traffic model

The current runtime mode is agent_proxy.

In this mode:

• sandboxes use the host agent for DNS resolution
• DNS names resolve to deterministic virtual loopback addresses for local agent proxy listeners
• the source agent checks network policy
• the source agent forwards traffic over the embedded Tailscale-compatible mesh
• the target agent forwards traffic into the target sandbox

Sandboxes do not run mesh software or receive mesh credentials. Host agents own DNS, proxying, mesh membership, and policy enforcement. The agent currently synthesizes IPv4 loopback addresses in the 127.64.0.0/10 range for sandbox DNS records, then binds local proxy listeners for the published alias and port.

routed_mesh is documented as an optional future mode for hosts that can safely allow route and firewall management.

Network planes

GlobalStacks separates infrastructure traffic from sandbox traffic. A host agent can participate in more than one Tailscale-compatible mesh through tsnet, but each mesh has a separate scope, credential, topology, and exposure path.

Control plane
  |
  | typed agent control messages
  v
Host agents
  |
  +-- Infra mesh, cluster scoped
  |     Members: host agents and agent-managed data-plane services
  |     Carries: metadata stores, object-store endpoints, health checks, backups
  |     Exposed to sandboxes: no
  |
  +-- Sandbox mesh, network scoped
        Members: sandbox service routes and optional user/dev joins
        Carries: application traffic between approved aliases and ports
        Exposed to sandboxes: only through agent DNS and policy-checked proxies

Sandbox process
  |
  +-- sees app DNS aliases and mounted filesystems
  +-- does not receive infra mesh credentials
  +-- does not see infra DNS records or infra proxy listeners

The infra mesh is created and joined by agents for a cluster. It uses the same Tailscale-compatible join machinery as sandbox networks, but is not returned by the user-facing Networks API, cannot be joined with gstacks mesh join, and is not published through the sandbox DNS/proxy runtime.

The sandbox mesh is what users create with gstacks network create. It is the only mesh plane that exposes aliases such as api.dev.gstacks to sandbox workloads or local development clients. The control plane sends each agent a topology containing network DNS suffixes, published aliases, ports, target agents, and policy rules.

Shared volume work uses these layers as separate boundaries:

• sandbox process reads and writes a mounted filesystem path
• host agent owns the JuiceFS mount and runtime enforcement
• JuiceFS metadata traffic uses the infra mesh
• object traffic uses an infra object-store endpoint or an explicitly configured external object store
• sandbox network policies do not grant access to metadata or object-store control endpoints

Create and attach

Create a network:

gstacks network create dev

Attach a sandbox and publish an alias:

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

Add another alias to an attached sandbox:

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

List aliases:

gstacks network alias list dev

Remove an alias:

gstacks network alias remove dev worker

Existing sandboxes may need restart or reattach before they use the agent DNS path. Once a sandbox is attached to a network, alias and policy changes are applied live by the agent.

Policy and diagnostics

Allow traffic from one source selector to one target alias and port:

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

Resolve an alias:

gstacks network resolve dev api

Test policy and route state:

gstacks network test dev local api:8080

The console Networks page also includes diagnostics for the selected network. Diagnostics are sent to the connected host agents through typed control messages; they are not executed through a shell on the control-plane server.

Current diagnostics check:

• the agent has joined the mesh network
• the topology version has been applied
• DNS records are loaded
• the requested alias and port has a route
• the policy allows or denies the requested source selector

Local development

Join a network from a developer machine:

gstacks mesh join dev

Show local join state:

gstacks mesh status

Forward one alias and port to localhost:

gstacks mesh forward dev api:8080 --local 18080
curl http://127.0.0.1:18080

Local mesh joins use short-lived credentials issued by the control plane. The local node is separate from agent nodes and should be treated as user-initiated development traffic.

The control plane needs a mesh control URL and an auth-key source before agents or CLI users can join the embedded mesh. In production, configure GLOBALSTACKS_MESH_CONTROL_URL with a dedicated tsnet-compatible origin such as https://mesh.globalstacks.dev, routed to the Headscale listener. For local development, use a separate HTTPS mesh port, for example https://devops.28stacks.net:3987 proxied to the private Headscale listener; managed mesh mode derives this from APP_HOST and GLOBALSTACKS_MESH_HEADSCALE_LISTEN_ADDR when the URL is omitted. Then provide either GLOBALSTACKS_MESH_AUTH_KEY for a pre-created key or GLOBALSTACKS_MESH_API_URL, GLOBALSTACKS_MESH_API_TOKEN, and optional GLOBALSTACKS_MESH_USER so GlobalStacks can mint short-lived pre-auth keys through the mesh control API.

Agents start a local DNS listener on 127.0.0.1:1053 and local proxy listeners on loopback addresses by default. Override those with GLOBALSTACKS_AGENT_MESH_DNS_ADDR and GLOBALSTACKS_AGENT_MESH_PROXY_BIND when the host needs different bind settings.

Console workflow

Use the Networks page to:

• inspect network status, DNS suffix, and topology version
• select a network and view aliases
• add or remove aliases for attached sandboxes
• run diagnostics against participating agents

Use the Sandbox detail page to inspect which networks a sandbox is attached to and which aliases it publishes.