# How to Use the gastownhall/gastown cmd Directory: Building and Running Gas Town CLI Tools

> Learn to use the gastownhall/gastown cmd directory to build and run Gas Town CLI tools including gt, gt-proxy-server, and gt-proxy-client for your project.

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

---

**The `cmd` directory in the gastownhall/gastown repository contains three compiled binaries—`gt`, `gt-proxy-server`, and `gt-proxy-client`—that provide the main CLI interface, mTLS proxy server, and container shim respectively.**

The `gastownhall/gastown` project organizes its command-line tools under the `cmd` directory, following standard Go project layout conventions. This directory houses the entry points for the multi-agent workspace orchestrator, the optional mTLS proxy for secure container execution, and the client shim that forwards commands from inside containers. Understanding how to build, configure, and invoke these binaries is essential for operating Gas Town both natively and in containerized environments.

## Building the Binaries from the cmd Directory

The repository provides a `Makefile` that compiles all three entry points from the `cmd` directory:

```bash
make build           # Compiles gt, gt-proxy-server, and gt-proxy-client

```

After running `make install`, the compiled binaries reside in `./bin/` and are also packaged into the Docker image (see `Dockerfile`).

Alternatively, you can install individual binaries directly using Go's toolchain:

```bash
go install github.com/steveyegge/gastown/cmd/gt@latest               # → $GOPATH/bin/gt

go install github.com/steveyegge/gastown/cmd/gt-proxy-server@latest # → $GOPATH/bin/gt-proxy-server

go install github.com/steveyegge/gastown/cmd/gt-proxy-client@latest # → $GOPATH/bin/gt-proxy-client

```

## Running the Primary Gas Town CLI (gt)

The `gt` binary serves as the main entry point for user-facing operations. According to the source code in [`cmd/gt/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/main.go), this binary implements the full command tree defined in the `internal/cmd` package.

A typical workflow begins with installation:

```bash

# Initialize a Gas Town headquarters (HQ) at ~/gt

gt install ~/gt --shell --git

# Start background services (Dolt, Deacon, Mayor, etc.)

cd ~/gt
gt up

```

Common operations include:

```bash

# Create a new project rig (clones a Git repo into the HQ)

gt rig add myproj https://github.com/example/repo.git

# Add a personal crew workspace inside the rig

gt crew add alice --rig myproj

# Attach to the Mayor (the AI coordinator)

gt mayor attach

```

## Configuring the mTLS Proxy Server (gt-proxy-server)

The `gt-proxy-server` binary isolates containerized agents from the host system by validating and proxying allowed sub-commands. As implemented in [`cmd/gt-proxy-server/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/main.go), the server maintains a default allowlist of permitted commands.

Start the proxy with specific listen addresses:

```bash
gt-proxy-server \
  --listen 0.0.0.0:9876 \
  --admin-listen 127.0.0.1:9877 \
  --ca-dir $HOME/.gt/proxy/ca \
  --town-root $HOME/gt

```

**Configuration Schema** – The proxy reads JSON configuration from `~/.gt/.runtime/proxy/config.json`. The schema is defined in [`cmd/gt-proxy-server/config.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/config.go) and supports fields such as:

- `listen_addr` – The network address to bind
- `allowed_commands` – Array of permitted command strings
- `extra_san_ips` / `extra_san_hosts` – Additional Subject Alternative Names for TLS certificates

## Using the Container Client Shim (gt-proxy-client)

When running Gas Town inside containers, the `gt-proxy-client` binary (located at [`cmd/gt-proxy-client/main.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-client/main.go)) acts as a thin wrapper. It checks for four specific environment variables; if present, it forwards commands to the proxy over mTLS, otherwise it executes the real `gt` binary directly.

**Required Environment Variables:**

- `GT_PROXY_URL` – The proxy endpoint (e.g., `https://host:9876`)
- `GT_PROXY_CERT` – Path to the client certificate
- `GT_PROXY_KEY` – Path to the client key
- `GT_PROXY_CA` – Path to the CA certificate

Example Dockerfile configuration:

```dockerfile
COPY --from=builder /usr/local/bin/gt-proxy-client /usr/local/bin/gt
COPY --from=builder /usr/local/bin/gt.real /usr/local/bin/gt.real
ENV GT_PROXY_URL=https://host:9876 \
    GT_PROXY_CERT=/etc/gt/proxy/client.crt \
    GT_PROXY_KEY=/etc/gt/proxy/client.key \
    GT_PROXY_CA=/etc/gt/proxy/ca.crt

```

Inside the container, standard `gt` commands are automatically proxied:

```bash
gt sling gt-abc12 myproj   # Forwarded to the host proxy

```

## Cross-Platform Testing

The repository includes build tests in [`cmd/gt/build_test.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt/build_test.go) that verify compilation across Linux, macOS, Windows, and FreeBSD. Run these tests to ensure binary compatibility:

```bash
go test ./cmd/gt -run TestCrossPlatformBuild

```

## Summary

- **Three core binaries** reside in `cmd/`: `gt` (main CLI), `gt-proxy-server` (mTLS proxy), and `gt-proxy-client` (container shim).
- **Build commands** include `make build` or `go install` for each binary path.
- **Entry points** are defined in [`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).
- **Proxy configuration** uses JSON schema from [`cmd/gt-proxy-server/config.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/config.go) and reads from `~/.gt/.runtime/proxy/config.json`.
- **Container integration** requires setting four `GT_PROXY_*` environment variables to activate the forwarding behavior.

## Frequently Asked Questions

### How do I build just the gt binary without the proxy components?

Run `go build ./cmd/gt` from the repository root or execute `go install github.com/steveyegge/gastown/cmd/gt@latest` to fetch and compile only the main CLI binary. The `Makefile` target `make build` compiles all three binaries simultaneously, but you can target specific binaries by invoking `go build` directly on the subdirectory.

### What environment variables does gt-proxy-client require?

The client shim requires four environment variables: `GT_PROXY_URL` (the HTTPS endpoint), `GT_PROXY_CERT` (client certificate path), `GT_PROXY_KEY` (client key path), and `GT_PROXY_CA` (CA certificate path). When these are unset, the shim executes the local `gt.real` binary instead of forwarding to the proxy.

### Where does gt-proxy-server store its configuration?

The server reads JSON configuration from `~/.gt/.runtime/proxy/config.json` according to the schema defined in [`cmd/gt-proxy-server/config.go`](https://github.com/gastownhall/gastown/blob/main/cmd/gt-proxy-server/config.go). You can also pass configuration via command-line flags such as `--listen`, `--admin-listen`, and `--allowed-subcmds`.

### Can I run the Gas Town CLI inside Docker containers?

Yes, by installing the `gt-proxy-client` binary as `/usr/local/bin/gt` inside your container and setting the four `GT_PROXY_*` environment variables. This setup forwards all `gt` commands to the `gt-proxy-server` running on the host, enabling secure multi-agent workspace management from within sandboxed environments.