Deployment
Self-host Zelaxy — the architecture, the four processes you run, environment configuration, and database setup.
Zelaxy is self-hostable end to end. Nothing about the platform requires a hosted service — you run the same code that powers the cloud, on your own infrastructure, with your data staying inside it.
Architecture
A running Zelaxy deployment is four cooperating processes plus a database:
| Process | Role |
|---|---|
| Web app | The Next.js 15 app — the visual editor, the APIs, and the workflow executor. |
| Socket server | A Socket.IO server for realtime multiplayer editing of the canvas. |
| Worker | Background jobs (scheduled triggers, long-running executions) via Trigger.dev. |
| Postgres | Data + vector store. Requires the pgvector extension for Knowledge/RAG. |
The web app is stateless — scale it horizontally behind a load balancer. State lives in Postgres and (for realtime) the socket server.
Prerequisites
- Node (or Bun, which the repo uses) and a package manager
- PostgreSQL 15+ with the
pgvectorextension available - At least one LLM provider API key (OpenAI, Anthropic, Google, etc. — see AI Models)
Configure the environment
Copy the example env file and fill in your values:
cp apps/zelaxy/.env.example apps/zelaxy/.envThe essential variables:
| Variable | Purpose |
|---|---|
DATABASE_URL | Postgres connection string (with pgvector). |
BETTER_AUTH_SECRET | Secret that signs auth sessions — generate a long random value. |
BETTER_AUTH_URL | The public URL users reach the app at. |
ALLOWED_ORIGINS | Comma-separated origins permitted to call the API / sockets. |
CRON_SECRET | Shared secret protecting the schedule/cron endpoints. |
OPENAI_API_KEY, ANTHROPIC_API_KEY, … | Provider keys for the models you enable. |
Secrets belong in the environment, never in the repo or in a workflow definition. Inside workflows, reference them as {{ENV_VAR}} — Zelaxy injects the value at execution time and never persists it into the saved graph.
Integration OAuth apps (Slack, Google, GitHub, …) each add a *_CLIENT_ID / *_CLIENT_SECRET pair — set only the ones you use. The full annotated list lives in .env.example.
Set up the database
cd apps/zelaxy
bun run db:push # apply the Drizzle schema (creates tables + pgvector)For production, prefer versioned migrations:
bun run db:migrateRun it
bun install # from the repo root
cd apps/zelaxy
bun run dev:full # app + socket server + worker (development)For production, build once and run each process:
bun run build
bun run start # web app
# run the socket server and worker as separate long-lived processesPut the web app behind TLS (a reverse proxy like Nginx or Caddy), point BETTER_AUTH_URL and ALLOWED_ORIGINS at the public HTTPS origin, and make sure the socket server is reachable from browsers for realtime editing.
Scaling notes
- Web app scales horizontally — it's stateless.
- Worker handles scheduled and background executions; run enough replicas for your job volume.
- Postgres is the source of truth — size it for your workflow history and vector index, and back it up.
Related
Single Sign-On
Connect Zelaxy to your identity provider so your team signs in with their existing corporate credentials over OIDC or SAML 2.0.
Security Model
How Zelaxy isolates teams with workspaces, enforces per-workspace roles on every API route, and stores credentials so secrets are referenced but never exposed.