Install & deploy

One-command setup

The setup script scaffolds .env, generates the encryption secrets, applies database migrations and starts the stack.

./scripts/setup.sh --all

powershell -ExecutionPolicy Bypass -File scripts\setup.ps1 -All

--all brings up every service and is the right default for a full install. Without it you get the app alone: add --docgen for the server-side Office renderer, --notebooks for the Developer-workspace Python runtime, or --sandbox for custom code in deployed swarms. --dev runs a local dev server instead of containers.

It cannot create your Supabase project or guess its keys — it writes the .env, tells you which values to fill in, and you re-run it.

Manual setup

1. 1

   Create a Supabase project

   It provides Postgres, authentication and storage. Note the project URL, publishable key and service-role key.
2. 2

   Fill in .env

   Copy .env.example and set the required values below.
3. 3

   Apply migrations

   npx supabase link --project-ref <ref> then npx supabase db push. This creates every table, policy and storage bucket.
4. 4

   Start it

   docker compose up -d --build, or npm install && npm run dev. Open http://localhost:8080.

Environment reference

Every variable the app reads, grouped by what it does. Only the first group is required; everything else changes behaviour you may not need.

Required — Supabase and identity

Models and search

Data connections

None of these are required — the defaults are the recommended settings. They exist for tuning against a particular warehouse or network.

Email delivery

Carries welcome mail, budget alerts, BI alerts, scheduled reports, approval requests and the contact form. Use either Resend or SMTP. Auth emails (confirmation, password reset) are separate — Supabase sends those, configured in its own dashboard.

Resend needs a verified domain, not just a key. In Resend: create an API key for RESEND_API_KEY, then Domains → Add Domain, publish the SPF and DKIM records it gives you at your DNS host, and press Verify. Then set EMAIL_FROM to an address on that domain.

RESEND_API_KEY="re_..."
EMAIL_FROM="AgentSwarms <noreply@your-company.com>"
SITE_URL="https://your-domain.com"

Run limits and cost

Network egress

Observability and audit

Scheduling

Document renderer

Notebook runtime

Configuration by use case

The reference above lists every setting. These are the combinations that actually go together, as complete blocks you can paste into .env. Each one names the risk it is answering, because the defaults are chosen for a single trusted operator and stop being right as soon as anyone else can reach the instance.

Evaluating it on a laptop

Nothing is exposed, so nothing needs hardening. This is the default and you can ignore every other recipe until someone else can reach the app.

SUPABASE_URL="https://<project>.supabase.co"
SUPABASE_SERVICE_ROLE_KEY="..."
SUPABASE_PUBLISHABLE_KEY="..."
VITE_SUPABASE_URL="https://<project>.supabase.co"
VITE_SUPABASE_PUBLISHABLE_KEY="..."

# One key and you can use everything; per-user keys can come later.
OPENROUTER_API_KEY="sk-or-..."

ADMIN_EMAIL="you@example.com"
VITE_ADMIN_EMAIL="you@example.com"

An internal tool for one team

Reachable on your network or a private domain, no anonymous visitors. The work here is closing signup and making sure a runaway agent cannot bill you indefinitely.

SITE_URL="https://agents.internal.example.com"
PUBLIC_APP_URL="https://agents.internal.example.com"

# Encrypts stored warehouse/SaaS credentials. Set once — rotating it
# invalidates everything already saved.  openssl rand -hex 32
PROVIDER_CREDS_SECRET="..."

# Caps stop being advisory.
ENFORCE_BUDGET_CAP="true"

# One reverse proxy in front (Caddy/nginx).
TRUSTED_PROXY_HOPS="1"

# Self-hosted Ollama or an in-cluster MCP server lives on a private address,
# so leave private-network fetches allowed — cloud metadata stays blocked
# either way.

Public embeds on a marketing site

The hardest case, because anonymous visitors spend your credits and you cannot authenticate them. Every setting here bounds what a stranger — or a leaked embed key — can cost you.

SITE_URL="https://www.example.com"
PUBLIC_APP_URL="https://app.example.com"
PROVIDER_CREDS_SECRET="..."

# Refuse calls past the cap instead of emailing about them afterwards.
ENFORCE_BUDGET_CAP="true"
# If spend cannot be established, refuse rather than assume zero.
BUDGET_FAIL_CLOSED="true"

# A public embed has no reason to reach anything inside your network.
BLOCK_PRIVATE_NETWORK_FETCH="true"

TRUSTED_PROXY_HOPS="1"

# Tighten the public surface below the defaults (30/min chat, 10/min ask).
MCP_RATE_LIMIT_PER_MIN="30"
SWARM_RUN_RATE_LIMIT_PER_MIN="10"
SWARM_RUN_MAX_CONCURRENT="2"

Regulated or air-gapped

No outbound anything, evidence retained, and the audit trail shipped somewhere the app cannot rewrite.

BLOCK_PRIVATE_NETWORK_FETCH="true"
ENFORCE_BUDGET_CAP="true"
BUDGET_FAIL_CLOSED="true"

# Traces to your own collector; nothing leaves for a vendor.
OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector.internal:4318"
OTEL_SERVICE_NAME="agentswarms-prod"

# Expiring audit rows are printed as NDJSON before deletion, so a log
# shipper keeps them past the database's own retention.
AUDIT_ARCHIVE_ON_PURGE="1"

# No model prices are fetched at runtime; the table is vendored in the repo
# and refreshed deliberately with:  npm run prices:refresh

Autoscaled behind a load balancer

Several app instances against one Supabase project. Rate limits and concurrency slots are counted in Postgres, so the numbers you set are the numbers you get — but two settings need to match the topology.

# MUST be set: instances resolve their own origin from this, never from the
# request's Host header.
PUBLIC_APP_URL="https://app.example.com"

# A dedicated secret for server-to-server calls, so the database master key
# stays out of outbound headers.  openssl rand -hex 32
INTERNAL_RUN_SECRET="..."

# CDN in front of the load balancer? Then two hops, not one.
TRUSTED_PROXY_HOPS="2"

# Alerts, refreshes and purges run in-process. A cross-instance lease stops
# them double-firing, but the tidier arrangement on a fleet is to disable
# them on the web tier and drive /api/bi/cron from one external scheduler.
DISABLE_INPROCESS_SCHEDULER="true"
BI_CRON_TOKEN="..."

Optional services

docker compose --profile docgen --profile notebooks --profile sandbox up -d --build

Or let the setup script start everything: bash scripts/setup.sh --all (powershell -File scripts\setup.ps1 -All on Windows).

All three are optional, and each degrades to something rather than breaking. Without the renderer, documents are generated in the browser and Deep mode is greyed out with the reason. Without the notebook runtime, notebooks fall back to the in-browser Python runtime. Without the sandbox, custom code still runs on the canvas and the Deploy dialog says plainly that it will fail in headless runs.

Observability → Monitoring (superadmin) shows which of these are actually up on this deployment, with the address that answered and live CPU, memory and disk. A profile you chose not to start reads “Not running” rather than as a failure.

Deployment targets

Docker Compose

The default. One app container plus whichever optional profiles you enable. Good to a substantial team on one host.

Node behind a reverse proxy

Build and run the server directly. Terminate TLS at your proxy.

Autoscaled VMs behind a load balancer

The app tier is stateless, so run as many identical containers as you need. Set DISABLE_INPROCESS_SCHEDULER=1 and drive background work from one external cron.

Kubernetes

Manifests are provided for the app and the notebook runtime, including the egress policy that keeps kernels off the open internet.

Scaling

The app tier is stateless — no sticky sessions needed, so put as many instances behind a load balancer as you like. Two things need attention when you do:

• The scheduler. Alerts, refreshes and purges run in-process. A cross-instance lease prevents double-firing, but the tidier arrangement is DISABLE_INPROCESS_SCHEDULER on the web tier and one external cron hitting the cron endpoint.
• Limits hold across the fleet. Rate limits and concurrency slots are counted in Postgres, so the number you configure is the number you get however many instances are running. If the database is briefly unreachable an instance falls back to counting locally and logs that it has — the limit weakens rather than vanishing. Budget caps are the other ceiling, and they are counted the same way; see Budgets.
• Set the proxy depth. TRUSTED_PROXY_HOPS must match how many proxies of yours sit in front — 1 for a load balancer alone, 2 with a CDN in front of it. MCP key IP allow-lists are checked against the address it selects.

The notebook Docker runtime is single-host by design — it launches containers on the host it runs on. Use the Kubernetes orchestrator to spread it.

Operations

Health

A health endpoint reports process liveness — point your load balancer at it.

Backups

Supabase holds all durable state. Use its backups, and store PROVIDER_CREDS_SECRET separately — a database backup without it is unreadable for credentials.

Upgrades

Pull, rebuild, then push migrations. Migrations are additive; check the release notes before skipping several versions.

Logs

Container logs for the platform; in-app Traces for what agents did. They answer different questions — reach for Traces first when an agent misbehaves.

Before you expose it

• Turn off public signup, or enforce SSO — Access control.
• Set ENFORCE_BUDGET_CAP and give every embed and API key a cap.
• Serve over TLS; the service-role key must never reach a browser.
• Restrict embed keys to your own domains.
• Review retention windows for chats, transcripts and audit.
• Back up PROVIDER_CREDS_SECRET somewhere you can actually retrieve it.