How the cmd Directory Fits into the Gas Town Architecture

The cmd directory contains the executable entry points that wire together Gas Town's higher-level services, including the primary gt CLI and the mTLS proxy components that enable secure communication between sandboxed containers and the host.

The cmd directory in gastownhall/gastown serves as the repository's binary front door, housing thin wrappers that expose the platform's orchestration capabilities to users and sandboxed agents. These entry points delegate to the comprehensive service layer implemented in internal/*, maintaining a clean separation between command interfaces and business logic. Understanding how these binaries connect to the broader architecture reveals how Gas Town maintains its security boundaries and cross-platform compatibility.

What the cmd Directory Contains

The cmd folder organizes four distinct binary targets that serve different architectural roles:

• cmd/gt – The primary CLI binary that users interact with directly
• cmd/gt-proxy-server – Host-side mTLS proxy for container-to-host communication
• cmd/gt-proxy-client – Client-side component running inside Polecat containers
• cmd/gt/build_test.go – Cross-platform compilation verification

Each binary acts as a thin adapter, parsing input and delegating to the service implementations in internal/cmd, internal/proxy, and other internal packages.

The Primary CLI Entry Point

cmd/gt/main.go implements the main gt binary that exposes sub-commands like gt install, gt up, and gt sling. Rather than containing business logic directly, this file serves as a minimal bootstrapper that calls cmd.Execute() from internal/cmd.

The execution flow follows this path:

1. The user invokes the gt binary built from cmd/gt/main.go
2. Arguments are parsed and global configuration (~/.gt/.runtime) is loaded
3. cmd.Execute() routes requests to appropriate services (daemon, Mayor, Witness, Refinery)
4. State persistence occurs through the Git-backed Beads ledger via the bd tool
5. OpenTelemetry events emit to the Deacon, Witness, and Refinery monitoring processes

This architecture ensures the CLI remains a lightweight interface while the heavy orchestration logic resides in testable internal packages.

The Proxy Architecture for Container Communication

Gas Town runs user workloads in sandboxed Polecat containers that must communicate with host services. The cmd directory implements a secure proxy pattern to maintain the boundary between container and host.

The Host-Side Proxy

cmd/gt-proxy-server/main.go runs on the host and exposes an HTTP API with mTLS validation. It enforces an allow-list of safe sub-commands through the defaultAllowedSubcmds variable, ensuring containers cannot execute arbitrary gt operations on the host system.

When the server receives a validated request, it forwards the command to the underlying gt binary, effectively proxying container requests through a secure, filtered channel.

The Container-Side Client

cmd/gt-proxy-client/main.go runs inside Polecat containers. It builds an HTTP client that automatically handles TLS certificates and connects to the host proxy server. This client allows containers to invoke gt and bd commands without direct access to the host filesystem or daemon.

The security flow works as follows:

1. A Polecat container runs gt-proxy-client to initiate communication
2. The client connects to gt-proxy-server on the host via mTLS
3. The server validates the sub-command against defaultAllowedSubcmds
4. Valid requests forward to the host gt binary; invalid requests are rejected

This pattern ensures sandboxed workloads can trigger orchestration events while maintaining strict security isolation.

Cross-Platform Build Verification

cmd/gt/build_test.go contains a cross-platform build test that compiles the entire codebase for every supported operating system and architecture combination. This test guards against platform-specific breakage, which is critical for Gas Town's "run anywhere" promise.

The test runs go build with explicit environment variables:

cmd := exec.Command("go", "build", "-o", os.DevNull, ".")
cmd.Env = append(os.Environ(),
    "GOOS=linux", "GOARCH=amd64", "CGO_ENABLED=0")
output, err := cmd.CombinedOutput()
if err != nil {
    t.Errorf("build failed for %s/%s:\n%s", "linux", "amd64", string(output))
}

Running go test ./cmd/gt -run TestCrossPlatformBuild ensures the CLI compiles for all target platforms before deployment to heterogeneous container environments.

Practical Usage Examples

Initializing a Gas Town Workspace

To start using the CLI built from cmd/gt/main.go:

# Initialize a new Gas Town workspace (HQ)

gt install ~/gt --shell --git

# Start background services (daemon, Mayor, Witnesses, etc.)

gt up

# Create a convoy and dispatch work to a Polecat

gt convoy create "Add feature X" gt-abc12
gt sling gt-abc12 myproject

Container-to-Host Communication

Inside a Polecat container, the proxy client enables secure command execution:

# The container runs the proxy client, forwarding the request to the host

gt-proxy-client --listen http://localhost:9876 \
    sling gt-abc12 /gt/myproject

The client contacts the proxy server, which verifies that sling appears in the allowed sub-command list before executing the operation on the host.

Summary

• The cmd directory houses executable entry points that serve as thin wrappers around Gas Town's internal service layer
• cmd/gt/main.go bootstraps the primary CLI by calling cmd.Execute() from internal/cmd, which dispatches to daemon, Mayor, and agent services
• cmd/gt-proxy-server/main.go and cmd/gt-proxy-client/main.go implement an mTLS proxy pattern that allows sandboxed Polecat containers to invoke host commands safely through an allow-list (defaultAllowedSubcmds)
• cmd/gt/build_test.go ensures cross-platform compatibility by testing compilation for all supported OS/architecture combinations
• All binaries maintain clean separation from business logic, delegating to packages in internal/* for actual orchestration, state management via Beads, and telemetry emission

Frequently Asked Questions

Why does the cmd directory contain separate binaries instead of a single CLI?

Gas Town separates concerns into distinct binaries to enforce security boundaries and deployment flexibility. The main gt binary handles user-facing orchestration, while the proxy server and client exist as distinct binaries to isolate container-to-host communication through mTLS. This separation prevents sandboxed containers from accessing the full CLI surface area, limiting potential attack vectors to only the allow-listed sub-commands defined in cmd/gt-proxy-server/main.go.

How does the gt binary communicate with the Beads issue tracker?

The gt binary never manipulates the Beads ledger directly. Instead, it shells out to the bd tool or calls bd sub-commands that act as thin wrappers around the Beads library. This indirection occurs through the service layer in internal/cmd, ensuring all state changes pass through the Git-backed storage abstraction rather than direct file manipulation.

What happens if a Polecat container tries to execute a non-allowed command?

The gt-proxy-server validates every incoming request against the defaultAllowedSubcmds list. If a container attempts to invoke a sub-command not explicitly whitelisted (such as destructive operations or configuration changes), the proxy server rejects the request before it reaches the host's gt binary. This enforcement point preserves the security boundary between untrusted container workloads and host orchestration services.

Where does the actual command logic reside if not in the cmd directory?

Business logic resides in internal/cmd for CLI operations, internal/proxy for the proxy implementation, and other internal/* packages for services like the daemon, Mayor, Witness, and Refinery. The cmd directory contains only entry points that parse arguments and delegate to these internal implementations, following Go standard project layout practices that separate binary interfaces from reusable library code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}