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

> Discover the purpose of the cmd directory in gastownhall/gastown. It houses entry-point executables for the main gt CLI and secure proxy binaries for safe container command execution.

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

---

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

```bash

# 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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go) provides host-side mTLS proxying with command allow-list validation via `defaultAllowedSubcmds`.
- [`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/main.go) files: [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go) for the primary CLI, [`cmd/gt-proxy-server/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go) for the host-side proxy, and [`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go) for the container-side client.