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 local agent proxy listeners
• the source agent checks network policy
• the source agent forwards traffic over the embedded mesh
• the target agent forwards traffic into the target sandbox

Sandboxes do not run mesh software. Host agents own DNS, proxying, mesh membership, and policy enforcement.

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

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. Configure GLOBALSTACKS_MESH_CONTROL_URL with the tsnet-compatible control URL, 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.