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

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:

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:

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, this binary implements the full command tree defined in the internal/cmd package.

A typical workflow begins with installation:

# 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:

# 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, the server maintains a default allowlist of permitted commands.

Start the proxy with specific listen addresses:

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 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) 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:

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:

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

Cross-Platform Testing

The repository includes build tests in cmd/gt/build_test.go that verify compilation across Linux, macOS, Windows, and FreeBSD. Run these tests to ensure binary compatibility:

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, cmd/gt-proxy-server/main.go, and cmd/gt-proxy-client/main.go.
• Proxy configuration uses JSON schema from 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. 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.

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