Deploy on a VM

A Linux virtual machine or server (Hetzner, DigitalOcean, EC2, on-premises) runs every deployment mode except Kubernetes:

• Single node and managed Postgres: the golem binary as a systemd service, with Caddy for TLS.
• Single node and managed Postgres in Docker: the golemservices/golem image in Docker Compose, with Caddy for TLS and optionally Litestream.
• Fixed cluster: the per-service images in Docker Compose on one host, with Caddy for TLS.

All setups need DNS names that point at the machine: one for the management API, such as golem.example.com, and one for each HTTP API or MCP deployment, such as api.example.com. Open ports 80 and 443 in the firewall, and keep every other port closed. Go through the production checklist too.

All-in-one server with systemd and Caddy

This setup runs modes 1 and 2. All Golem listeners stay on 127.0.0.1, and Caddy, on the same machine, is the only public listener.

curl -L -o golem https://github.com/golemcloud/golem/releases/download/<version>/golem-x86_64-unknown-linux-gnu
sudo install -m 755 golem /usr/local/bin/golem
sudo useradd --system --home-dir /var/lib/golem --create-home --shell /usr/sbin/nologin golem
sudo install -d -m 755 /etc/golem

sudo sh -c 'umask 077; HMAC_KEY=$(openssl rand -base64 32); cat > /etc/golem/golem.env <<EOF
GOLEM__REGISTRY_SERVICE__INITIAL_ACCOUNTS__ROOT__TOKEN=$(openssl rand -hex 32)
GOLEM__WORKER_SERVICE__WEBHOOK_CALLBACK_HANDLER__HMAC_KEY=$HMAC_KEY
GOLEM__WORKER_EXECUTOR__AGENT_WEBHOOKS_SERVICE__HMAC_KEY=$HMAC_KEY
GOLEM__WORKER_SERVICE__INVOCATION_SESSION_TOKENS__ACTIVE_KEY__ID=key-1
GOLEM__WORKER_SERVICE__INVOCATION_SESSION_TOKENS__ACTIVE_KEY__KEY=$(openssl rand -base64 32)
AWS_ACCESS_KEY_ID=<access key>
AWS_SECRET_ACCESS_KEY=<secret key>
EOF'

[Unit]
Description=Golem server
After=network-online.target
Wants=network-online.target
 
[Service]
User=golem
Group=golem
EnvironmentFile=/etc/golem/golem.env
ExecStart=/usr/local/bin/golem server run --config /etc/golem/golem-server.toml
Restart=on-failure
LimitNOFILE=1048576
TimeoutStopSec=60
 
[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now golem
journalctl -u golem -f

# The management host and the domains of HTTP API and MCP deployments.
golem.example.com, api.example.com, mcp.example.com {
	reverse_proxy 127.0.0.1:9881
}

sudo systemctl reload caddy
curl https://golem.example.com/healthcheck

Upgrades and backups

To upgrade, replace /usr/local/bin/golem with the new release and run sudo systemctl restart golem.

In mode 2, the database provider backs up the state. In mode 1, the state is in the SQLite files under /var/lib/golem. A snapshot of the disk while the server runs is not guaranteed to be consistent; stop the service for the snapshot, or use mode 2 when you cannot accept the downtime.

All-in-one image with Docker Compose

This setup runs modes 1 and 2 from the golemservices/golem image, with Caddy in front. The single-node example contains the Compose file, the Caddyfile and the script that writes the environment file.

mkdir golem && cd golem
for f in compose.yaml Caddyfile .env.example generate-env.sh; do
  curl -fsSLO https://raw.githubusercontent.com/golemcloud/golem/main/docker-examples/single-node/$f
done
chmod +x generate-env.sh
cp .env.example .env

umask 077
GOLEM_S3_BUCKET=my-bucket GOLEM_S3_REGION=eu-central-1 ./generate-env.sh > golem.env
echo "AWS_ACCESS_KEY_ID=<access key>" >> golem.env
echo "AWS_SECRET_ACCESS_KEY=<secret key>" >> golem.env

docker compose up -d
docker compose logs -f golem
curl https://golem.example.com/healthcheck

The server runs as uid 65534. The golem_data named volume takes the owner of the data directory in the image; if you replace it with a bind mount, give the directory to that user with sudo chown -R 65534:65534 <dir>. See Volume ownership.

Caddy has a fixed address on the Compose network, 172.31.0.10, which the server trusts for X-Forwarded-Proto and X-Forwarded-Host. Only Caddy publishes ports. In mode 1, the SQLite databases are in the golem_data volume. To upgrade, change GOLEM_IMAGE_VERSION and run docker compose up -d: Compose stops the old container before it starts the new one.

Fixed cluster with Docker Compose

This setup runs the fixed cluster on one host: the per-service images, several worker executors and Caddy, with Postgres and S3 outside the host. One host is one failure domain, so this setup scales the executors, but it does not survive the loss of the host. It is the same configuration as a cluster on several machines, so it can move to AWS ECS or Kubernetes over the same database and bucket.

mkdir golem && cd golem
for f in compose.yaml Caddyfile .env.example; do
  curl -fsSLO https://raw.githubusercontent.com/golemcloud/golem/main/docker-examples/production-cluster/$f
done
cp .env.example .env

docker compose up -d
docker compose logs -f golem-shard-manager

What the example sets

• Caddy routes the management host by path to the registry service and the worker service, and the deployment domains to the worker service’s custom request port. It has a fixed address on the Compose network, 172.30.0.10, which the worker service trusts for X-Forwarded-Proto and X-Forwarded-Host.
• All services share one bucket with namespace_prefixes = true, and keep their state in their own schemas of one database. The worker service keeps its sessions in Postgres, so there is no Redis.
• The registry service keeps its built-in artifact cache in the builtin_artifacts volume at /app/builtin-artifacts.
• The shard manager runs as one replica in Postgres mode. docker compose up stops its old container before it starts the new one.
• WORKER_EXECUTOR_REPLICAS sets the number of executors. Change it and run docker compose up -d again to scale.
• The default plan has no per-agent disk limit, because the executors keep agent files in temporary directories. See Plans.

To upgrade, change GOLEM_IMAGES_VERSION and run docker compose up -d.