Self-hosting

A customer-hosted installation runs the console, the Agent Gateway, PostgreSQL and NATS on one Linux server with Docker Compose, from the same images as the hosted service. The delivery team supplies the release bundle, the image tags that belong together and a licence. These are the steps the bundle’s own guide runs.

Customer-hosted deployments use packaged deployment configuration. An offline deployment requires an accepted bundle, local model and disconnected installation tests.

What you need

• Linux with Docker Engine 24+ and the Compose plugin (docker compose version).
• 4 CPU, 8 GB RAM and 40 GB of disk.
• Ports 443 and 80 free on the server; the hosts you manage reach it on 443.
• A DNS name or IP address for ACT_HOSTNAME that people and hosts can reach.

Install

In the bundle’s compose folder, copy the example settings, set ACT_HOSTNAME, and start the stack:

cd compose
cp .env.example .env        # set ACT_HOSTNAME
docker compose up -d --wait
docker compose logs control-plane | grep -A4 "FIRST-BOOT ADMIN"

The secrets (session key, database password, Gateway token, encryption key) are generated on first start onto the secrets volume, never into .env. The last command prints the first administrator’s password once. Open https://<ACT_HOSTNAME>, sign in with ACT_ADMIN_EMAIL and that password, and change it.

Without registry access

The images are in a private registry. The release comes either with a read token for it or with an image archive and its SHA-256 checksum. With the archive:

sha256sum -c actree-selfhost-<version>-images.tar.sha256
docker load -i actree-selfhost-<version>-images.tar
docker compose up -d --wait

Settings in .env

• ACT_HOSTNAME: the DNS name or IP address people and hosts use.
• ACT_TLS_MODE: internal (the default; Caddy’s own certificate authority, which browsers warn about until you trust it), byo (your tls.crt and tls.key in compose/certs/; from a private authority, also its ca.crt with ACT_CONTROL_CA_FILE=/certs/ca.crt) or acme (a public Let’s Encrypt certificate; needs a public DNS name and ports 80 and 443 reachable).
• ACT_LICENCE_KEY: the key from the portal’s Licences page. A site with no internet leaves it empty and installs a signed licence file instead (below).
• ACT_NEW_HOST_EXEC_MODE: auto (the default; new hosts start in automatic review under a read-only policy) or deny (every command is refused until someone picks a mode on the Hosts page).
• ACT_HTTPS_PORT: a port other than 443, with ACT_PUBLIC_URL and ACT_GATEWAY_PUBLIC_URL set to match.

Enrol hosts

In the console, Hosts then Add a host gives the same one-line install command as the hosted service, pointed at your server. With the default internal certificate, give the host your server’s certificate authority for the first download; the agent installs it from then on:

# on the server
docker compose exec -T caddy cat /data/caddy/pki/authorities/local/root.crt > actree-ca.crt
# on the host, with actree-ca.crt copied over and the token from Hosts > Add a host
curl -fsSL --cacert actree-ca.crt https://<ACT_HOSTNAME>/api/v1/fleet/agent/install.sh \
  | sudo ACT_CA_FILE="$PWD/actree-ca.crt" bash -s -- --token <token>

Models

Add a model under Models in the console’s settings: a local Ollama or vLLM, or any OpenAI-compatible endpoint your network reaches.

Bring your own model — OpenAI-compatible endpoints, Ollama, Anthropic, or Cloudflare AI Gateway / Workers AI — with keys envelope-encrypted at rest.

Without internet

A site with no internet exchanges signed files with AcTree, carried by a person:

• Licence: download the Air-gap licence file from the portal’s Licences page. In the console, open Settings, Licence, choose This deployment has no internet and install it.
• Releases and agent builds: download the Offline bundle from the same portal page, then use Apply a bundle under Offline updates and reports in the console’s Licence settings.
• Usage: Make the usage report in the same place and upload it on the portal when you can.

The site also needs a local model.

Upgrade and back up

# Upgrade: set the new image tags in .env, then
docker compose pull && docker compose up -d --wait
# Backup: the database (keep the pgdata, secrets and state volumes with it)
docker compose exec postgres pg_dumpall -U actree > actree-backup.sql

The console migrates its database when it starts. Back up the pgdata, secrets and state volumes together; the secrets volume holds the encryption keys, so protect backups as credentials.