# How the cmd Directory Fits into the Gas Town Architecture

> Understand the cmd directory's role in the Gas Town architecture. Discover how it manages executables and powers the gt CLI and mTLS proxy for secure container communication.

- Repository: [Gas Town Hall/gastown](https://github.com/gastownhall/gastown)
- Tags: architecture
- Published: 2026-07-07

---

**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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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:

```go
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`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go):

```bash

# 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:

```bash

# 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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go)** and **[`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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.