# Subdirectories in the cmd Directory of gastownhall/gastown: A Complete Guide

> Explore the cmd directory in gastownhall/gastown. Discover the subdirectories gt, gt-proxy-server, and gt-proxy-client for Gas Town system command-line access.

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

---

**The `cmd` directory contains three subdirectories:** `gt`**,** `gt-proxy-server`**, and** `gt-proxy-client`**, each providing distinct command-line entry points for the Gas Town system.**

The `gastownhall/gastown` repository organizes its command-line binaries under the `cmd` directory following standard Go project conventions. This directory houses three focused subdirectories that define the entire command-line surface of the system, from the main agent coordination interface to secure proxy components for sandboxed environments.

## Overview of the cmd Directory Structure

The `cmd` directory follows the canonical Go layout where each subdirectory represents a separate binary entry point. Unlike monolithic CLI applications, Gastown separates concerns into three distinct executables: the primary user-facing tool, a server-side proxy for secure container communication, and a lightweight client wrapper. This architecture ensures that privileged operations run isolated while providing convenient access to external processes.

## The Three Subdirectories Explained

### cmd/gt – The Main Gas Town CLI

The `cmd/gt` subdirectory contains the primary **Gas Town CLI** used for everyday agent coordination, issue tracking, and workspace management. Its entry point at [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go) delegates to `cmd.Execute()` to dispatch subcommands such as `status`, `bd ready`, and `nudge`. This binary serves as the main interface for developers interacting with the Gas Town system.

### cmd/gt-proxy-server – The mTLS Proxy Server

The `cmd/gt-proxy-server` subdirectory implements an **mTLS proxy server** that runs on the host machine to expose safe `gt` and `bd` subcommands to containers. Located at [`cmd/gt-proxy-server/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go), this component parses configuration flags, loads or generates a Certificate Authority (CA), and configures the specific subcommands allowed through the proxy boundary. This isolation mechanism prevents containers from accessing privileged operations directly.

### cmd/gt-proxy-client – The Proxy Client Wrapper

The `cmd/gt-proxy-client` subdirectory provides a thin **client wrapper** that communicates with the proxy server over mutually authenticated TLS. Implemented in [`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go), this binary forwards user commands to the proxy server, allowing external processes to invoke proxy-mediated commands safely without direct access to the host's `gt` binary.

## Key Source Files and Entry Points

Each subdirectory contains a [`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go) file that serves as the compilation entry point:

- **[`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go)**: Calls `cmd.Execute()` to initialize the CLI framework and register subcommands.
- **[`cmd/gt-proxy-server/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go)**: Sets up the HTTP listener, configures mTLS certificates from the specified `-ca-dir`, and validates allowed commands against the `-town-root` configuration.
- **[`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go)**: Establishes the mTLS connection to the proxy address specified by `-proxy` and forwards the remaining arguments as a remote procedure call.

## Practical Usage Examples

Below are typical invocations for each binary built from the `cmd` directory subdirectories.

Running the main CLI:

```bash

# Check workspace status

gt status

# List issues ready for development

gt bd ready

# Send a message to the mayor agent

gt nudge mayor "Hi!"

```

Starting the proxy server:

```bash
gt-proxy-server \
  -listen=:9876 \
  -admin-listen=127.0.0.1:9877 \
  -ca-dir=~/gt/.runtime/ca \
  -town-root=~/gt

```

Using the proxy client:

```bash
gt-proxy-client \
  -proxy=localhost:9876 \
  gt status

```

## Summary

- The `cmd` directory contains exactly three subdirectories: `gt`, `gt-proxy-server`, and `gt-proxy-client`.
- Each subdirectory maps to a distinct binary with a specific security and operational role in the Gas Town ecosystem.
- The entry points ([`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go) files) implement the separation between user-facing commands, host-level proxy services, and client-side wrappers.
- All other files under `cmd/` are supporting Go source files; no additional nested subdirectories exist beyond these three.

## Frequently Asked Questions

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

The `cmd` directory organizes the command-line binaries following Go standards, containing three subdirectories that provide the complete command-line surface for the Gas Town system: the main CLI, a proxy server, and a proxy client.

### How does the gt-proxy-server differ from the main gt binary?

The `gt-proxy-server` runs as a privileged host daemon that exposes a subset of `gt` commands over mTLS to sandboxed containers, while the `gt` binary executes directly with full user privileges for interactive development workflows.

### Can I run Gastown commands without using the proxy components?

Yes. The `gt` binary in `cmd/gt` operates independently; the proxy components (`gt-proxy-server` and `gt-proxy-client`) are only required when running commands from within restricted container environments that need to access host-managed resources.

### Where are the entry points for each cmd subdirectory located?

Each subdirectory contains a [`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go) file at its root: [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go), [`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). These files compile into the respective binaries and handle flag parsing, initialization, and command dispatch.