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

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

The gt binary is the user-facing command-line interface that developers interact with directly. Located at 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)

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

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

go run ./cmd/gt --help

Starting the Proxy Server

Launch the mTLS proxy with custom listen addresses:

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:

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 – 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 produces the gt binary, the primary CLI entry point that loads the internal command dispatcher.
• 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 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 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 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 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.

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