The full Avocado Studio stack — site templates, editor app, @ai-site-editor/site-sdk, and the orchestrator — is open source under Apache 2.0 and lives in avocadostudio-ai/avocado. The orchestrator (the brain that runs sessions, calls the LLMs, and serves draft state) is the only stateful service in the stack — Docker is the supported path for running it on your own infrastructure. If you need help self-hosting, open an issue. Where to host the orchestrator
The orchestrator is a small Node.js Fastify service. It’s stateful but not heavy — most production deployments fit comfortably on the smallest paid tier of any modern container host.
Tested hosts
| Host | Notes |
|---|
| Render | The reference deployment — what we run internally today. Free tier is too small for real use; the smallest paid tier is fine. Use a Render disk for persistent state. |
| Fly.io | Works well — the always-on machine model fits the orchestrator’s long-lived sessions. Use a Fly Volume for /app/.data. |
| Railway | Works. Make sure you provision a volume for state persistence; ephemeral filesystems will lose sessions on every redeploy. |
| DigitalOcean App Platform | Works as a Web Service with an attached volume. |
| AWS ECS / Fargate, GCP Cloud Run (with min instances ≥ 1), Azure Container Apps | All work. Cloud Run requires min instances = 1 so the container doesn’t cold-start mid-session. |
| Kubernetes | Works as a single-replica StatefulSet with a PersistentVolumeClaim mounted at /app/.data. Do not run multiple replicas — see the constraints below. |
| Self-managed VPS (Hetzner, Linode, etc.) | The simplest option. docker compose up -d and a reverse proxy (Caddy, nginx, Traefik) for HTTPS. |
Resource requirements
- Memory: ~300–500 MB at idle, ~600–800 MB under typical load. A 1 GB instance is comfortable; the smallest “$7/month-ish” tier on most hosts is enough for early use.
- CPU: Mostly I/O-bound — the orchestrator spends most of its time waiting on LLM API calls, not computing. 0.5 vCPU is fine for a handful of concurrent sessions; 1 vCPU is comfortable for a small team.
- Disk: A persistent volume for
/app/.data (session state, telemetry, generated images). 1–5 GB is plenty for early use; generated-image storage is what grows fastest if you use AI image generation heavily.
- Network: Outbound HTTPS to your chosen LLM providers (
api.anthropic.com, api.openai.com, generativelanguage.googleapis.com); inbound HTTPS from your editor and site origins. No inbound from end-users — only your editor and Next.js site need to reach it.
Critical hosting constraints
A few things matter regardless of which host you pick:
Single instance only. The orchestrator persists all session state — draft pages, undo history, chat threads, version log, site configs — to a local SQLite database via better-sqlite3. Do not run multiple replicas behind a load balancer: each replica would open its own SQLite file (or fight over a shared one), so requests round-robined between processes would see divergent state and sessions would appear to randomly lose work. Horizontal scaling is on the roadmap but not implemented today. Configure your host for exactly one instance and scale vertically (more memory / CPU on a single machine) if you need more capacity.
- Persistent volume is required. The orchestrator stores its SQLite database at
/app/.data/orchestrator.db (plus -wal / -shm sidecar files and rolling backups). If you mount that path on an ephemeral filesystem (Cloud Run without a volume, Heroku-style ephemeral dynos, default container hosts without disk attachment), every redeploy or container reschedule will wipe all sessions and undo history. Always attach a persistent volume — even 1 GB is enough.
- SSE-friendly reverse proxy. The chat endpoint streams server-sent events for live editor updates. Some reverse proxies and CDNs buffer responses by default, which makes the editor look frozen until the full response lands. If you put a reverse proxy in front of the orchestrator, disable response buffering on
/chat/* and /sites-agent/* (in nginx: proxy_buffering off; in Caddy: flush_interval -1 on reverse_proxy; in Cloudflare: bypass cache for these paths).
- Long timeouts. Sites-agent runs (full URL migration, repo integration) can take several minutes. If your host has a default request timeout of 30s or 60s, the agent will be killed mid-run. Bump request timeouts to at least 10 minutes on the orchestrator’s routes — most hosts let you configure this per service.
- CORS for the editor’s origin. Set
ORCHESTRATOR_CORS_ORIGINS to include both your site and editor origins (HTTPS, no trailing slash). See CORS configuration below.
- Public HTTPS reachable from your editor and site. Both the editor (browser) and your Next.js site (server-side draft fetches) need to call the orchestrator. If your editor is on
https://editor.example.com and your site is on https://www.example.com, the orchestrator needs to be on a URL both can reach — usually a public HTTPS endpoint like https://orchestrator.example.com.
Building the image
The orchestrator source lives at apps/orchestrator in the repo. Build the image from the repository root:
docker build -f apps/orchestrator/Dockerfile -t avocado-orchestrator:latest .
packages/shared, packages/migration-sdk).
Running standalone
docker run -d \
--name avocado-orchestrator \
-p 4200:4200 \
--env-file .env \
-v avocado-data:/app/.data \
avocado-orchestrator:latest
Required environment variables
At minimum you need one AI provider key:
| Variable | Description |
|---|
ANTHROPIC_API_KEY | Claude API key (recommended — most battle-tested) |
OPENAI_API_KEY | OpenAI API key |
GOOGLE_GENAI_API_KEY | Google Gemini API key |
CORS configuration
By default the container accepts requests from http://localhost:3000 and http://localhost:4100. For production, set the allowed origins explicitly.
ORCHESTRATOR_CORS_ORIGINS=https://your-site.example.com,https://editor.example.com
State persistence
The orchestrator writes session state, telemetry, and generated images to /app/.data inside the container. Mount a volume there to persist data across restarts.
The image pre-configures these paths:
ORCHESTRATOR_DB_FILE=/app/.data/orchestrator.dbCHAT_TELEMETRY_FILE=/app/.data/chat-telemetry.ndjsonORCHESTRATOR_GENERATED_IMAGE_DIR=/app/.data/generated-images
Using docker-compose
A docker-compose.yml at the repo root runs the orchestrator with sensible defaults:
docker compose up -d
docker compose logs -f orchestrator
docker compose down
orchestrator-data) and loads env vars from .env at the repo root.
Health check
The container includes a health check that polls http://127.0.0.1:4200/health every 30 seconds. Check status with:
docker inspect --format='{{.State.Health.Status}}' avocado-orchestrator
Environment reference
See .env.example at the repo root for the complete list of environment variables. Common Docker overrides:
| Variable | Purpose |
|---|
PORT | HTTP port (default: 4200) |
NODE_ENV | production by default in the image |
ORCHESTRATOR_CORS_ORIGINS | Comma-separated list of allowed origins |
ORCHESTRATOR_STATE_FILE | Path to session state JSON |
CHAT_TELEMETRY_FILE | Path to telemetry NDJSON |
ORCHESTRATOR_GENERATED_IMAGE_DIR | Directory for generated images |
PUBLISH_TOKEN | Required token for /publish/* endpoints |
ACCESS_PASSWORD_HASH | Optional password hash for /auth/verify |
Running locally without Docker
The whole stack is open source, so for local development you can clone the repo and run the orchestrator directly via pnpm from the repository root — that’s the faster dev loop. Docker is the supported path for production self-hosting; the source-based workflow is for contributors and anyone who wants to hack on the orchestrator itself.
pnpm install
pnpm dev:start # starts site + editor + orchestrator via tsx
# or run just the orchestrator:
pnpm --filter @ai-site-editor/orchestrator dev
Troubleshooting
Check logs: docker logs avocado-orchestrator. The most common cause is missing API keys or an invalid .env file.
CORS errors from editor or site
Set ORCHESTRATOR_CORS_ORIGINS to include both the site and editor origins (no trailing slashes).
State not persisting
Ensure the volume is mounted at /app/.data and that the container user has write permissions.
Health check failing
Wait for the 10-second start period. If it still fails, check that the orchestrator is listening on 0.0.0.0:4200 (it should be by default) and that no firewall is blocking the port.
