Self-hosting

XOS is open source under AGPL-3.0. A deployment is one Supabase project and the apps that run on it. Atlas serves the workspace and the public API at /api/v1, Gateway serves external parties, and Compass is the field app. This guide takes you from an empty project to a verified deployment, in the order the pieces depend on each other.

What you run

Requirements

• Node.js 22.12 or later and pnpm 10.15.1 (the version in packageManager; Corepack installs it).
• Docker, for the local Supabase stack and ClamAV.
• The Supabase CLI 2.x.
• A clone of the repository at a release tag.

git clone https://github.com/ghxstship/atlas.git xos
cd xos
git checkout v4.0.0
corepack enable
pnpm install --frozen-lockfile

1. The database

Local development

supabase/config.toml defines the local stack. Start it, apply every migration from empty, and run the database tests:

supabase start
supabase db reset
supabase test db

supabase db reset also loads the demo tenant from supabase/seeds. supabase start prints the API URL and the anon key.

Production

Create a Supabase project on Postgres 17 in the region your customers' data must stay in. The Pro plan includes daily backups; point-in-time recovery is an add-on (see Backups below).

supabase link --project-ref <project-ref>
supabase db push

For a self-hosted Compose stack, pass its connection string instead: supabase db push --db-url "postgresql://postgres:<password>@<host>:5432/postgres".

The migrations hold everything a new deployment needs: the canon, the plans and capabilities, the scheduled database jobs (pg_cron) and the encryption keys in Vault. They create the keys themselves.

Migrations are forward-only. Apply them before you deploy apps that need them.

Auth settings

supabase/config.toml is for the local stack only; do not run supabase config push with it. Set these in the hosted project's dashboard:

The repository's infra/runbooks/hosted-security-settings.md lists every setting with the reason for it.

2. Environment variables

Atlas and Gateway validate their environment when they start and name every missing or malformed variable. Copy apps/atlas/.env.example and apps/gateway/.env.example for local development.

Neither app ever receives the service role key. Every Supabase call runs on the server with the signed-in person's session.

3. Edge Functions

Deploy every function in supabase/functions and set their secrets:

supabase functions deploy
supabase secrets set --env-file ./functions.env

For a self-hosted stack, mount supabase/functions into the Compose stack's functions service instead. stripe-webhook, inbound-email, email-unsubscribe, kiosk-punch, api-token, integration-inbound and file-download authenticate their callers themselves and are deployed without JWT verification, as supabase/config.toml declares.

Schedule the workers

webhook-dispatch, notification-dispatch, upload-scan, report-run, import-run, integration-worker, subprocessor-notices and automation-run do their work when called with the service role key. Call each one every minute. On hosted Supabase, pg_cron and pg_net can do it from the database, reading the key from Vault:

select vault.create_secret('<service role key>', 'xos_worker_key');

select cron.schedule('xos_worker_webhook_dispatch', '* * * * *', $$
  select net.http_post(
    url := 'https://<project-ref>.supabase.co/functions/v1/webhook-dispatch',
    headers := jsonb_build_object(
      'Authorization', 'Bearer ' || (select decrypted_secret from vault.decrypted_secrets where name = 'xos_worker_key')
    )
  );
$$);

Repeat for the other seven functions, or call them from any scheduler you already run. Until upload-scan runs, attachments cannot be downloaded and field and onboarding uploads reach only the person who uploaded them. Until import-run runs, imports are not read, until integration-worker runs, integrations do not sync and warehouse deliveries wait, and until automation-run runs, automations queue their runs and take no action. Provider apps and their webhook secrets are in infra/runbooks/integrations.md.

Upload scanning

Every upload is scanned by ClamAV that you run yourself, the clamav/clamav:1.5.4 image. Files stay quarantined until they scan clean, and an infected file is deleted while its uploader is told why.

1. Run clamd on a host the Edge Functions can reach privately. The image is published for linux/amd64 only. Give it at least 2 vCPU and 4 GiB of memory and a persistent volume at /var/lib/clamav. Use the settings in infra/scanning/docker-compose.yaml, which also works as is with Docker Compose.
2. clamd has no authentication, so never expose port 3310 to the internet. Reach it over a private network or a tunnel.
3. Set the function secrets XOS_CLAMAV_HOST and XOS_CLAMAV_PORT, and XOS_ENVIRONMENT=production.
4. Call upload-scan once with the service role key. A response with "scanner": "clamav" means it is connected.

Without XOS_CLAMAV_HOST, upload-scan answers 503 and scans nothing, so uploads stay quarantined. On a local development stack only, it marks files clean without scanning and logs a warning for each one. The image updates its own signatures, so allow outbound HTTPS to database.clamav.net. infra/runbooks/production.md has sizing, alerts and upgrades.

Know the IP allow-list's limit

An organization's IP allow-list is enforced where Atlas and the API check a session or an API key. It is not enforced on direct calls to your Supabase endpoint (REST, Storage and Realtime) made with a valid session token, because only Atlas and the API see the caller's address. If you rely on the allow-list, restrict who can reach the Supabase endpoint at your network edge as well. Routing all data access through the API is the planned fix.

4. Atlas, Gateway and docs

On Vercel

Create one Vercel project per app with these settings, then add the variables above to each project's Production and Preview environments:

Add each custom Gateway domain to the Gateway project; organizations verify their domain in Atlas settings.

To serve the API on its own host, add that host to the Atlas project too and set XOS_API_HOST to it. Atlas then answers https://<that host>/v1/... as the API at /api/v1/..., with the same credentials and limits, and serves no page or cookie there.

On your own Node host

pnpm turbo run build --filter=@xos/atlas --filter=@xos/gateway
pnpm --filter @xos/atlas exec next start --port 3000
pnpm --filter @xos/gateway exec next start --port 3001

Run each app under a process manager, behind a TLS-terminating reverse proxy that passes the Host header through, so Gateway can recognize custom domains.

The proxy must append the client address to X-Forwarded-For (in nginx, proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;). Atlas reads the last entry, the one your proxy added, because the client writes the entries before it; the IP allow-list depends on that. If another trusted proxy, such as a CDN, sits in front of yours, set XOS_TRUSTED_PROXY_HOPS=1. Never expose the apps without a proxy: then every forwarding header is the client's own text.

5. Compass

Compass reads its configuration at build time:

Change the bundle identifier and Android package in apps/compass/app.json to your own, then build with EAS Build (add an eas.json with a production profile and run eas build --platform all --profile production) or locally with expo prebuild followed by an Xcode archive and a Gradle release build. Distribute through TestFlight and Google Play internal testing first.

6. Verify the deployment

curl -s "$ATLAS_SITE_URL/api/v1/openapi.json" | head -c 200
XOS_BASE_URL="$ATLAS_SITE_URL/api/v1" XOS_API_KEY="xos_live_..." xos auth status

Then sign up, create an organization and a project, invite a member and open the project in Compass.

7. Backups and restores

A backup counts only once a restore of it has been verified. The repository's restore drill restores a dump into a throwaway local database and checks the migration version, the row count of every table, checksums of the key tables and the database test suites:

infra/drills/release-drill.sh

Restore an incident into a new project, never over the live one, then switch the apps' SUPABASE_URL and keys. infra/runbooks/backup-and-restore.md has the full procedure.

8. Upgrades

1. Read the release notes for the tag, then check out the tag and run pnpm install --frozen-lockfile.
2. Take a backup, or confirm point-in-time recovery is on.
3. Apply new migrations: supabase db push.
4. Deploy the Edge Functions: supabase functions deploy.
5. Deploy Atlas, Gateway and docs.
6. Build Compass when the release notes say it changed.

Database changes follow expand and contract: no migration in a release breaks the build before it. To roll back an app, redeploy its previous build; the database is never rolled back. /v1 changes only additively, so existing API integrations keep working across upgrades.