Skip to content

Connection Sharing

Jump to bottom
Jon edited this page Sep 1, 2026 · 2 revisions

Purpose

Opening a connection to an AI provider can add noticeable overhead to a short-lived ash invocation. On macOS and Linux, an unprivileged broker keeps a bounded HTTPS connection pool open so separate ash processes from the same interactive shell can reuse provider connections. The broker accepts requests only over a private Unix socket; it does not store prompts, responses, or credentials.

The broker is a separate binary, ash-broker, installed alongside ash. It has no dependency on any AI provider SDK — it only proxies already-built HTTP requests over its shared connection pool — so it stays small and its dependency surface doesn't grow as new provider adapters are added to the main ash binary. Older shell integrations that still reference ash broker will see a one-line deprecation message directing them to reinstall (ash install --overwrite) to pick up the ash-broker wrapper.

Each interactive Bash or zsh shell gets at most one broker. Subshells inherit and reuse their parent shell's broker, while independent shells get their own.

Lifecycle (Bash)

  1. Launch

Bash reads ~/.bashrc, which sources ~/.ash/.ash_bashrc after ash install. The wrapper lazily starts a broker only when AI_ENDPOINT and AI_MODEL are configured and a routed prompt needs it. It creates a per-shell runtime directory under $HOME/.ash/runtime, a Unix socket and lease file named from SESSION_ID, and a random, in-memory capability token. The broker is started in the background with standard input, output, and error disconnected from the shell. The PID of the parent shell is passed to the broker which checks periodically if the process is running, and exits if it is not.

The wrapper starts the broker via command ash-broker --socket <path> --parent-pid <pid> --lease <path>, not ash broker.

  1. Configuration

The wrapper sources $HOME/.ash/.ash_env before starting the broker. The broker validates the same AI environment used by ash, including AI_ENDPOINT, AI_MODEL, provider selection, and cloud authentication requirements. It refuses to start without complete valid configuration.

  1. Requests and connection reuse

Before ash sends a chat request, it connects to the private Unix socket and sends the request URL, approved headers, and body together with the capability token. The broker validates the token, peer, URL, headers, and size limits, then makes the HTTPS request using its shared connection pool. The pool has bounded per-host connections. Keep-alive connections are reused across separate ash commands.

  1. Fallback

Broker use is transparent. If the socket cannot be reached or the broker rejects a request, ash retries the request directly with its own HTTPS client. Scheduled jobs do not receive broker state and therefore use direct HTTPS unless they explicitly inherit a live interactive-shell environment.

  1. Shutdown and cleanup

Routed prompts refresh the lease file. The broker stops on interrupt, termination, or hangup signals. Closing a shell does not immediately kill the detached broker; instead, it monitors the PID of the shell and exists when it notices the parent has exited.

The socket is mode 0600, and the capability token, socket, lease, and process ID are ephemeral shell state. Do not persist or copy ASH_BROKER_SOCKET, ASH_BROKER_TOKEN, or ASH_BROKER_LEASE into shell profiles, cron, launchd, or other scheduler configuration.

Clone this wiki locally