Self-hosting with Docker Compose

cloudscode is designed to be self-hosted. The reference deployment is a single docker-compose.yml that you can drop on any Linux host with Docker installed.

Stack overview

The compose file launches:

Service	Image	Ports	Purpose
api	cloudscode/api:latest	8787 (HTTP)	Hono control plane.
dash	cloudscode/dash:latest	5173 (HTTP)	Web dashboard.
runtime-host	cloudscode/runtime-host:latest	(Docker socket)	Spawns per-instance runtime containers.
postgres	postgres:17	5432	Primary database.
redis	redis:7	6379	Queues, rate-limits, presence.
caddy	caddy:2	80, 443	TLS termination + reverse proxy.

Prerequisites

• Linux host (Ubuntu 24.04, Debian 12, or any modern distro).
• Docker 24+ and Docker Compose v2.
• A domain pointed at the host (api.example.com, app.example.com).
• 4 GB RAM minimum; 8 GB recommended.

Quick start

git clone https://github.com/cloudscode/cloudscode
cd cloudscode/deploy
cp .env.example .env
$EDITOR .env             # set DOMAIN, ADMIN_EMAIL, secrets
docker compose up -d

Caddy will provision Let’s Encrypt certs automatically on first boot. Watch the logs:

docker compose logs -f caddy

Once you see certificate obtained, hit https://api.<your-domain>/healthz.

Configuration (.env)

Var	Required	Notes
DOMAIN	yes	Apex domain; used to derive api. and app..
ADMIN_EMAIL	yes	First admin user; ACME contact.
POSTGRES_PASSWORD	yes	Generated by .env.example template.
SESSION_SECRET	yes	32-byte hex; rotate annually.
BYOK_KEK	yes	32-byte hex; key-encryption-key for BYOK store.
OPENCLAW_IMAGE	no	Override default runtime image.
WEBHOOK_TIMEOUT_MS	no	Default 5000.

Backups

The compose file ships with a backup-cron.timer systemd unit that snapshots postgres and redis to /var/backups/cloudscode/ daily. Forward those off-box to S3 / R2 / your storage of choice.

sudo systemctl enable --now backup-cron.timer
sudo systemctl status backup-cron.timer

Upgrades

cd /opt/cloudscode
docker compose pull
docker compose up -d

Database migrations run automatically on api boot. Roll back by docker compose down && git checkout <previous-tag> && docker compose up -d.

Going further

• Concepts → Tenants for the isolation model.
• API reference for the surface you’ll be exposing.
• Webhooks for outbound integrations.