Install on Linux

Linux is the reference platform: it runs the server and workers.

Requirements

Git, Node.js 22+, Docker Engine with the Compose plugin, and openssl (the installer uses it to generate secrets). See the hardware table.

Install the server

1. Clone and install dependencies.

   git clone https://github.com/surr-jc/azhi-flow && cd azhi-flow
   npm ci

2. Run the installer.

   deploy/install.sh

   It checks for Docker, Compose and openssl, writes deploy/.env once with a random server secret and database password (mode 0600, git-ignored), pulls the PostgreSQL and Temporal images, builds the server image, starts everything, waits until all three containers are healthy, and prints the owner token. Re-running it upgrades in place and keeps deploy/.env.

3. Add model access. Store a provider key and set a model, then re-run the installer.

   npx azhi secret set anthropic-api-key --value sk-ant-...   # or openai-api-key
   # put AZHI_ANTHROPIC_MODEL (or AZHI_OPENAI_MODEL) in deploy/.env
   deploy/install.sh

Caution

Do not delete deploy/.env while the database volume exists. The database keeps the password it was created with.

Add a worker

Workers run scripts and harnesses. Run one on this host or on another Linux machine.

1. On the worker host, clone and install (omit dev dependencies if you like; this includes the pinned OpenCode binary).

   git clone https://github.com/surr-jc/azhi-flow && cd azhi-flow
   npm ci --omit=dev

2. Point it at the server and sign in.

   export AZHI_URL=http://<server>:7400
   export AZHI_TEMPORAL_ADDRESS=<server>:7233     # localhost:7233 on the same machine
   npx azhi login --url "$AZHI_URL" --token <owner token>

3. Start the worker.

   npx azhi worker start --trust workspace-publishers

4. Check the tools OpenCode steps need, then verify.

   npx azhi setup     # git, OpenCode, ripgrep; prints the install command for your distro
   npx azhi doctor    # database, Temporal, interpreter builds, workers online

Script nodes also need uv (Python 3.12) and/or Bun on the worker. Details for ripgrep and token saving are on Workers and OpenCode tools.

Installer options

All are environment variables.

Variable	Default	Use
AZHI_PORT	7400	API and web run page port
AZHI_PG_PORT, AZHI_TEMPORAL_PORT	5432, 7233	Published ports, for workers and the CLI
AZHI_TEMPORAL_VERSION	1.29.1	Temporal server image tag
AZHI_NODE_IMAGE	node:22-bookworm-slim	Base image, for example a mirror when Docker Hub rate-limits
AZHI_SKIP_BUILD	unset	1 uses an azhi-flow/server image that is already loaded
AZHI_COMPOSE_PROJECT	azhi	Run a second, isolated stack on one host

More in the environment variable reference.

Verify

npx azhi doctor
npx azhi open     # prints a link to Mission Control that signs the browser tab in

Next: First run.