Private & VPC agents

Run the BuildAutomaton CLI bridge on the same host as your agent (on-prem, in a VPC, or on a private cloud) so ACP stays on localhost while the bridge connects out to your workspace.

Why use private or VPC-hosted agents?

Many teams want coding agents—and, if they choose, the LLMs those agents call—to run on infrastructure they own and operate, not only on a laptop behind NAT. The same-host bridge pattern keeps prompts, code, and tool traffic on machines and networks under your policy.

That setup helps you govern intellectual property, usage, and cost: you decide which models and endpoints are allowed, how data leaves the VPC, and how spend is attributed, instead of routing everything through environments you do not control end to end.

Headless auth

Use --headless when the bridge must not open a browser (servers and containers). Until your CLI lists that flag in --help, you can still pass --token and --workspace-id, or BUILDAUTOMATON_AUTH_TOKEN and BUILDAUTOMATON_WORKSPACE_ID, for non-interactive auth. Your host still needs outbound HTTPS and WebSocket access to the API (for example through a VPC NAT gateway). For a first-time browser sign-in, follow Getting started.

Dashboard token

In the app, open your workspace, go to Bridges, and create a bridge access token. You will use that token together with the workspace ID every time you start the CLI without a browser.

Environment variables and secrets

The CLI accepts the same values through flags or environment variables: BUILDAUTOMATON_AUTH_TOKEN and BUILDAUTOMATON_WORKSPACE_ID mirror --token and --workspace-id. Point at a non-default API with BUILDAUTOMATON_API_URL if your organization requires it.

Treat the token like any other long-lived secret. Load it from a secrets manager, Kubernetes Secret, or CI masked variable, or mount a Docker --env-file that is never committed to git, and avoid printing the environment in startup logs.

export BUILDAUTOMATON_AUTH_TOKEN="…"
export BUILDAUTOMATON_WORKSPACE_ID="…"
npx @buildautomaton/cli --headless

You can combine these options with others such as end-to-end certificate setup; see End-to-end encryption when you need --e2ee-certificates-dir as well.

Empty working directory

If the bridge starts in an empty working directory (for example a fresh /workspace in a container), it still connects to the workspace. The dev environment UI then walks you through initializing and cloning a Git repository so the agent has a real tree to work in. Mount a persistent volume if you want that checkout to survive restarts.

OpenCode (Docker)

The openeuler/opencode image on Docker Hub is a practical base for OpenCode. Extend it by copying a Node.js installation into the image so npx @buildautomaton/cli is available next to OpenCode, then start both processes in the same container (or network namespace) so the bridge reaches OpenCode on localhost.

FROM openeuler/opencode:1.1.48
USER root
COPY --from=docker.io/node:22-bookworm /usr/local /usr/local
ENV PATH="/usr/local/bin:${PATH}"
WORKDIR /workspace

Build a small image from that Dockerfile, then run it with secrets injected as environment variables and with the Hub quick start's config volume for OpenCode. The shell snippet below is only an outline; replace YOUR_OPENCODE_START with the start command documented for your tag on Docker Hub.

docker build -t ba-opencode .
docker run --rm -it \
  -e BUILDAUTOMATON_AUTH_TOKEN -e BUILDAUTOMATON_WORKSPACE_ID \
  -v ~/.config/opencode:/root/.config/opencode \
  -v "$(pwd)":/workspace ba-opencode \
  sh -c 'YOUR_OPENCODE_START & npx @buildautomaton/cli --headless'

On a laptop you can skip --headless for the first connection and let the browser complete sign-in. The usual command is:

npx @buildautomaton/cli@latest

Claude Code (VPC)

A typical Amazon VPC setup uses a private EC2 instance with outbound access through NAT, Claude Code running in Docker, and the BuildAutomaton bridge in the same container or on the same Docker network so the bridge can open ACP to localhost.

FROM node:22-bookworm
WORKDIR /workspace
# Install Claude Code CLI per your org; mount the repo at docker run time.
CMD ["sh", "-c", "npx @buildautomaton/cli --headless & exec claude"]

Replace claude with the command your image actually uses, pass token variables from a secret store, set BUILDAUTOMATON_API_URL if you are not on the default API host, and allow outbound WebSocket traffic in the instance security group.