What Is the Purpose of the cmd Directory in gastownhall/gastown?

The cmd directory in gastownhall/gastown contains the entry-point executables that form the Gas Town command-line ecosystem, including the main gt CLI and the secure proxy binaries that enable sandboxed containers to execute commands safely.

The gastownhall/gastown repository organizes its executable programs under the cmd directory following standard Go project conventions. This directory houses self-contained binaries that handle everything from direct user interaction to secure cross-container communication. Understanding the purpose of the cmd directory in gastownhall/gastown is essential for deploying the Gas Town multi-agent system securely.

Architecture of the cmd Directory

The cmd directory structure reflects a security-conscious design pattern where each sub-directory compiles to a single binary. These executables work together to provide both standard CLI functionality and sandboxed execution capabilities for the Gas Town platform.

cmd/gt – The Primary CLI Entry Point

The cmd/gt subdirectory contains the main Gas Town CLI binary. In cmd/gt/main.go, the application initializes the Cobra command hierarchy by calling cmd.Execute() and exits with the returned status code. This binary boots the top-level command tree defined in internal/cmd and dispatches user requests to sub-commands such as bd, hook, mail, and polecat.

cmd/gt-proxy-server – Host-Side mTLS Proxy

The cmd/gt-proxy-server binary runs on the host machine and exposes a secure HTTP façade for sandboxed containers. According to the source code in cmd/gt-proxy-server/main.go, this server loads or generates a CA certificate, builds an allow-list of safe sub-commands using defaultAllowedSubcmds and parseAllowedSubcmds, and starts both the proxy server and an optional admin server. This architecture prevents containers (called polecats) from gaining direct shell access while still permitting audited operations like gt prime or bd ready.

cmd/gt-proxy-client – Container-Side Forwarder

Running inside containers, the cmd/gt-proxy-client binary acts as a thin wrapper that forwards CLI arguments to the host-side proxy. The implementation in cmd/gt-proxy-client/main.go establishes a TLS connection to the gt-proxy-server using the certificates generated by the server side, ensuring encrypted communication for all forwarded commands.

Secure Command Execution Flow

These three binaries implement a defense-in-depth strategy for the Gas Town multi-agent system. When running outside containers, users invoke gt directly. Inside sandboxes, the system intercepts calls through the proxy client, validates them against the allow-list, and executes only permitted commands on the host.

The workflow proceeds as follows:

1. Direct execution: Users run gt status to execute commands directly on the host.
2. Container forwarding: Inside sandboxes, the container executes gt-proxy-client gt ready to forward the request.
3. Validation and execution: The host-side gt-proxy-server validates the command against its allow-list and executes it safely, returning the result to the container.

Implementation Details and Usage Examples

Each binary in the cmd directory is designed to be compiled and invoked independently. The following examples demonstrate typical usage patterns:

# Run the main Gas Town CLI directly

gt status

# Start the proxy server on the host with CA configuration

gt-proxy-server -listen 0.0.0.0:9876 -ca-dir ~/gt/.runtime/ca

# Execute a safe command from inside a sandboxed container

gt-proxy-client gt ready

The gt-proxy-server specifically restricts dangerous operations while allowing workflow commands like bd create, bd update, and gt hook through its configurable allow-list mechanism.

Summary

• The cmd directory in gastownhall/gastown contains three primary binaries: gt, gt-proxy-server, and gt-proxy-client.
• cmd/gt/main.go serves as the entry point for the main CLI, executing the Cobra command tree via cmd.Execute().
• cmd/gt-proxy-server/main.go provides host-side mTLS proxying with command allow-list validation via defaultAllowedSubcmds.
• cmd/gt-proxy-client/main.go enables secure command forwarding from sandboxed containers to the host.
• Together, these executables isolate privileged operations while permitting audited commands in multi-agent environments.

Frequently Asked Questions

What is the purpose of the cmd directory in gastownhall/gastown?

The cmd directory houses the entry-point programs for the Gas Town command-line ecosystem. Each subdirectory compiles to a self-contained binary that handles either direct user interaction (gt) or secure proxy communication (gt-proxy-server and gt-proxy-client).

How does the gt-proxy-server validate commands?

The server uses the defaultAllowedSubcmds configuration and parseAllowedSubcmds function defined in cmd/gt-proxy-server/main.go to build an allow-list of safe sub-commands. It only executes commands matching patterns like gt:prime,hook or bd:create,update, rejecting any unauthorized requests from containerized clients.

Can I run the gastown CLI without the proxy components?

Yes. The gt binary in cmd/gt functions independently as a standard CLI tool. The proxy components are only required when operating within sandboxed containers (polecats) where direct shell access must be restricted for security reasons.

Where are the main entry points defined for each binary?

The entry points are defined in their respective main.go files: cmd/gt/main.go for the primary CLI, cmd/gt-proxy-server/main.go for the host-side proxy, and cmd/gt-proxy-client/main.go for the container-side client.

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