# Main Entry Points for the gastownhall/gastown Application in the cmd Directory

> Discover the main entry points for the gastownhall/gastown application within the cmd directory: gt CLI, gt-proxy-server, and gt-proxy-client. Learn how to use them.

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

---

**The gastownhall/gastown repository provides three executable entry points in the `cmd` directory: `gt` (the CLI), `gt-proxy-server` (the mTLS proxy), and `gt-proxy-client` (the container shim).**

The `cmd` directory in the gastownhall/gastown repository houses the main entry points that launch the Gas Town ecosystem. Understanding these three binaries is essential for developers who want to interact with the CLI directly, deploy sandboxed container environments, or debug the application's bootstrap process. Each entry point serves a specific architectural role, from handling user commands to mediating secure container access.

## The Three Main Entry Points in cmd/

The `cmd` directory contains three separate [`main.go`](https://github.com/gastownhall/gastown/blob/main/main.go) files, each producing a distinct binary. Together they form the complete launch surface of the Gas Town application.

### gt – The Primary CLI Entry Point ([`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go))

The `gt` binary is the user-facing command-line interface that developers interact with directly. Located at [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go), this entry point loads the internal command dispatcher defined in `internal/cmd/` and executes commands like `gt prime`, `gt nudge`, or `bd`. The process exits with the dispatcher's return code, making it the standard entry point for everyday Gas Town operations.

### gt-proxy-server – The Host-Side mTLS Proxy ([`cmd/gt-proxy-server/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go))

The `gt-proxy-server` binary runs on the host machine and exposes a secure HTTP endpoint for sandboxed containers. According to the gastownhall/gastown source code, this entry point located at [`cmd/gt-proxy-server/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go) loads a Certificate Authority (or creates one if absent), builds a `proxy.Config` from command-line flags or a JSON configuration file, and starts the proxy service. It listens on configurable addresses (default `0.0.0.0:9876` for the proxy and `127.0.0.1:9877` for the admin UI).

### gt-proxy-client – The Container-Side Shim ([`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go))

Installed inside containers, the `gt-proxy-client` acts as a thin wrapper that detects proxy environment variables. As implemented in [`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go), it checks for `GT_PROXY_URL`, `GT_PROXY_CERT`, `GT_PROXY_KEY`, and `GT_PROXY_CA`. When these variables are present, it forwards command arguments to the proxy server via mTLS and returns the remote output. If any variable is missing, it falls back by executing the real `gt` binary at `/usr/local/bin/gt.real`.

## Building and Running the Entry Points

Developers can compile and run these entry points directly from the repository root.

### Running the gt CLI

Build and invoke the main CLI to see available commands:

```bash
go run ./cmd/gt --help

```

### Starting the Proxy Server

Launch the mTLS proxy with custom listen addresses:

```bash
go run ./cmd/gt-proxy-server \
    -listen=0.0.0.0:9876 \
    -admin-listen=127.0.0.1:9877

```

### Using the Proxy Client in Containers

Inside a container configured with the proxy environment, commands are automatically forwarded:

```bash
export GT_PROXY_URL=https://172.17.0.1:9876
export GT_PROXY_CERT=/etc/gt/proxy.crt
export GT_PROXY_KEY=/etc/gt/proxy.key
export GT_PROXY_CA=/etc/gt/proxy-ca.crt

# The binary name determines which tool is proxied

gt version      # Request forwarded to proxy server

bd ready        # Request forwarded to proxy server

```

If these environment variables are unset, the client executes `/usr/local/bin/gt.real` directly.

## Key Configuration Files

Beyond the main entry points, supporting files define the proxy behavior:

- **[`cmd/gt-proxy-server/config.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/config.go)** – Handles JSON configuration for the proxy server, including allowed command paths and TLS settings.
- **`internal/cmd/`** – Contains the concrete command implementations that the `gt` CLI dispatches to.

## Summary

- **[`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go)** produces the `gt` binary, the primary CLI entry point that loads the internal command dispatcher.
- **[`cmd/gt-proxy-server/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go)** produces the `gt-proxy-server` binary, which initializes an mTLS proxy for secure container communication.
- **[`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go)** produces the `gt-proxy-client` binary, a shim that routes commands to the proxy or falls back to the real binary.
- The proxy client relies on four environment variables (`GT_PROXY_URL`, `GT_PROXY_CERT`, `GT_PROXY_KEY`, `GT_PROXY_CA`) to determine whether to proxy or execute locally.
- Configuration for the proxy server is managed via [`cmd/gt-proxy-server/config.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/config.go) and supports both flags and JSON config files.

## Frequently Asked Questions

### What is the difference between gt and gt-proxy-client?

The `gt` binary is the full command-line interface that executes Gas Town commands directly on the host system. In contrast, `gt-proxy-client` is a thin wrapper designed to run inside containers that either forwards commands to a `gt-proxy-server` via mTLS or falls back to executing the real `gt` binary at `/usr/local/bin/gt.real` when proxy environment variables are unavailable.

### How does gt-proxy-server handle TLS certificates?

According to the gastownhall/gastown source code, the `gt-proxy-server` entry point in [`cmd/gt-proxy-server/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go) automatically loads an existing Certificate Authority or creates one if it does not exist. It then constructs a `proxy.Config` from command-line flags or a JSON configuration file to secure the HTTP endpoint.

### Can I run the gt CLI without the proxy infrastructure?

Yes. The `gt` binary at [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go) operates independently and does not require the proxy server or client. It directly loads the command dispatcher from `internal/cmd/` and executes subcommands like `prime`, `nudge`, or `bd` on the local machine.

### Where are the actual command implementations located?

While the entry points reside in `cmd/`, the concrete command implementations are located in `internal/cmd/`. The `gt` entry point acts as a thin bootstrapper that delegates to this internal package, keeping the main entry point focused solely on initialization and exit code handling.