Deploy

Pylon runs as a Rust binary (plus Bun, which runs your TypeScript and SSR) behind a TLS-terminating reverse proxy. This page covers the supported self-hosted deploy shapes and the experimental Workers path. To skip self-hosting, Pylon Cloud hosts the same binary.

Required environment

# Core
PYLON_PORT=4321
PYLON_DB_PATH=/var/lib/pylon/pylon.db
PYLON_FILES_DIR=/var/lib/pylon/uploads
PYLON_MANIFEST=/etc/pylon/pylon.manifest.json

# Auth (MUST be set in non-dev)
PYLON_ADMIN_TOKEN=<64+ random bytes, hex>
PYLON_SESSION_DB=/var/lib/pylon/sessions.db  # SQLite only; Postgres shares auth state

# Client-facing — declarative: prefer manifest.auth.trustedOrigins
# in app.ts (one source feeds CORS + CSRF + OAuth-redirect). These
# env vars exist as per-gate overrides when ops need to split.
# PYLON_CORS_ORIGIN=https://your-app.com
# PYLON_CSRF_ORIGINS=https://your-app.com

# Mode switch (default is false — only flip in dev)
# PYLON_DEV_MODE=false

Optional:

PYLON_JOBS_DB=/var/lib/pylon/jobs.db          # SQLite job sidecar only
PYLON_WORKFLOWS_DB=/var/lib/pylon/workflows.db # SQLite workflow sidecar only
PYLON_OAUTH_GOOGLE_CLIENT_ID=...              # enable Google OAuth
PYLON_OAUTH_GITHUB_CLIENT_ID=...              # enable GitHub OAuth
PYLON_EMAIL_PROVIDER=stack0                   # or sendgrid | resend | webhook
PYLON_EMAIL_API_KEY=sk_live_...               # provider API key
PYLON_EMAIL_FROM=[email protected]       # verified sender
PYLON_EMAIL_ENDPOINT=...                      # only when PYLON_EMAIL_PROVIDER=webhook

# File storage (defaults to local disk)
PYLON_FILES_PROVIDER=stack0                   # local (default) | stack0 | s3
PYLON_STACK0_API_KEY=sk_live_...              # required when provider=stack0
PYLON_STACK0_PROJECT_SLUG=your-project        # required when provider=stack0
PYLON_STACK0_FOLDER=uploads                   # optional folder/prefix
PYLON_FILES_DIR=/var/lib/pylon/uploads        # local provider only
# S3-compatible (AWS S3, R2, Tigris, MinIO). Boot-validated; never silently
# falls back to local disk. Credentials from env only (no IAM-role discovery).
PYLON_S3_BUCKET=my-bucket                     # required when provider=s3
PYLON_S3_ACCESS_KEY=AKIA...                   # required when provider=s3
PYLON_S3_SECRET_KEY=...                       # required when provider=s3
PYLON_S3_REGION=us-east-1                     # optional, default us-east-1
PYLON_S3_ENDPOINT=https://...                 # optional; R2/Tigris/MinIO (path-style)
PYLON_S3_PUBLIC_URL=https://cdn...            # optional; public bucket/CDN base
PYLON_S3_SESSION_TOKEN=...                    # optional; STS/temporary credentials
PYLON_FILES_URL_PREFIX=/api/files             # local provider only

# Cookie auth (browser apps)
PYLON_COOKIE_DOMAIN=.your-app.com
PYLON_COOKIE_SAME_SITE=lax
PYLON_COOKIE_SECURE=true

Hard requirements that fail to start:

PYLON_CORS_ORIGIN=* in non-dev mode is refused
In non-dev mode, the CORS gate refuses to start with no trusted origins. Declare them in manifest.auth.trustedOrigins, or set PYLON_CORS_ORIGIN
PYLON_DEV_MODE=true with PYLON_ADMIN_TOKEN unset is refused
/api/__test__/reset is disabled unless dev + in-memory + loopback

Ports

Pylon uses up to four adjacent ports, depending on which transports you enable:

Port	Purpose	When
`PYLON_PORT` (default `4321`)	HTTP	Always
`PYLON_PORT + 1`	WebSocket	When sync engine uses `transport: websocket` (default)
`PYLON_PORT + 2`	SSE (`/events`)	When clients use `transport: sse` fallback
`PYLON_PORT + 3`	Realtime shards	When apps use `useShard` / `PylonRealtime`

Your reverse proxy must forward all relevant ports. For deployments with a single public port (Fly.io, Cloud Run), path-route the WebSocket, SSE, and shard upgrades through that one port at the proxy (see the Caddy and nginx examples below), then point the client’s sync wsUrl at the public origin. There is no server-side WS-URL environment variable; the client’s transport config tells it where to connect.

Shape 1: single VPS (SSH + systemd)

This is the simplest and cheapest shape: the pylon binary plus Bun, one systemd unit, and one reverse proxy. pylon deploy --target systemd generates this unit, plus step-by-step install commands, for your app. The shape looks like this:

# /etc/systemd/system/pylon.service
[Unit]
Description=pylon
After=network-online.target

[Service]
EnvironmentFile=/etc/pylon/env
# App source (app.ts, functions/, app/, node_modules) lives here.
# TypeScript functions + SSR need bun on the host:
#   curl -fsSL https://bun.sh/install | BUN_INSTALL=/usr/local bash
WorkingDirectory=/opt/my-app
ExecStart=/usr/local/bin/pylon start app.ts
Restart=on-failure
RestartSec=5s
User=pylon
Group=pylon
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/var/lib/pylon

[Install]
WantedBy=multi-user.target

Reverse proxy (Caddy or nginx) forwards :443 → :4321 plus WebSocket upgrades for /ws → :4322, /events (SSE) → :4323, and shard WS → :4324. pylon deploy --target systemd emits a matching nginx or Caddy reverse-proxy config alongside the unit file (generated by crates/runtime/src/tls.rs).

systemctl enable --now pylon

For backups, run pylon backup /var/backups/pylon/$(date +%F) nightly with cron. Test the restore quarterly, using the test at crates/runtime/tests/backup_restore.rs.

Caddy example

your-app.com {
    reverse_proxy localhost:4321

    handle /ws {
        reverse_proxy localhost:4322
    }
    handle /events {
        reverse_proxy localhost:4323
    }
    handle /shard/* {
        reverse_proxy localhost:4324
    }
}

Shape 2: AWS ECS + Aurora (Terraform)

deploy/terraform/modules/pylon/ provisions:

ECS Fargate service (0.25 vCPU, 512 MB) ~$9/mo
Aurora Serverless v2 (0.5–2 ACU) ~$15/mo minimum
ALB with TLS + WebSocket routing
CloudFront CDN + Route53 DNS

Minimum bill: ~$25/mo for a production deployment. Compile Pylon with --features postgres-live and set DATABASE_URL=postgres://....

Shape 3: AWS via SST (TypeScript IaC)

For TypeScript-first infrastructure, SST v3 provisions the same AWS shape from a single sst.config.ts. It uses the same components (Aurora, Fargate, ALB, EFS, CloudFront) and one CLI for deploys, secrets, and per-PR preview environments.

sst deploy --stage production

See Deploy with SST for the full walkthrough:

secrets
custom domains
multi-port load balancer config
EFS vs S3 storage
horizontal scaling

Shape 4: Cloudflare Workers (edge, experimental)

crates/workers/ builds a WASM bundle (worker-build --release) that runs on Workers with a D1 binding. See crates/workers/README.md for current limitations. Idle apps cost $0, because Workers scales to zero. Cost rises with request volume. See Workers costs. Workers does not yet support realtime shards (tick-based sims). They need persistent state that Workers alone cannot hold efficiently. Use shape 1 or 2 for game shards.

Shape 5: Pylon Cloud

pylon login
pylon deploy --target cloud

Done. See Cloud for full details.

Shape 6: local dev

pylon dev

This starts on port 4321 with PYLON_DEV_MODE=true defaults: Studio at /studio, hot-reload, and permissive CORS. Do not use this mode in production.

Health checks

GET /health returns 200 with {"status":"ok","uptime_seconds":N}
GET /metrics returns Prometheus text when Accept: text/plain
GET /readyz checks DB connectivity

Hook these into your load balancer so it drains unhealthy instances.

Shutdown and rolling deploys

SIGTERM terminates the process. The runtime does not yet install a signal handler, so SIGTERM does not run an in-process drain. The drain path exists in the runtime, but it is not wired to a signal yet. Two things make an abrupt stop safe in practice:

SQLite (WAL mode) is crash-consistent. An abrupt stop does not corrupt the database. The next start recovers the WAL, so there is no unflushed data to lose.
Drain at the load balancer, not in the process. For a rolling deploy with zero dropped requests, stop routing new traffic to the old instance. Wait out your load balancer’s connection-drain (deregistration) delay so in-flight requests finish. Then stop the process.

For a rolling deploy: start the new instance, let the load balancer health check promote it, stop routing traffic to the old one, wait for the drain window, then send SIGTERM. PYLON_DRAIN_SECS (default 10s) bounds the drain loop for paths that do invoke the runtime’s shutdown, such as a programmatic shutdown. It is not a SIGTERM grace period.

Native clients (iOS, macOS, Android)

Native clients hit the same HTTP and WebSocket endpoints as browsers. Keep these points in mind:

CORS does not apply. Native HTTP clients skip CORS entirely. PYLON_CORS_ORIGIN does not affect them.
TLS is required on iOS. App Transport Security rejects ws:// and http:// to non-localhost hosts. Always use wss:// and https:// in production. Self-signed certificates work in dev with an ATS exception in Info.plist.
Background sessions. For large file uploads or downloads that should continue when the app is backgrounded, configure URLSessionConfiguration.background(...) in your transport. See Swift SDK.

Scale-out

Pylon supports multiple processes behind a load balancer. Use Postgres for shared entities, auth state, jobs, workflows, and sync state. Configure PYLON_CLUSTER_BUS for live change, presence, and CRDT fanout between self-hosted processes. Pylon Cloud configures its managed relay for you. Jobs and workflow steps use at-least-once execution. Make their handlers idempotent. SQLite remains a single-machine backend. See Horizontal scaling for the full setup and failure model. For multi-region on Pylon Cloud, set the workspace region during signup. Self-hosted multi-region is a manual setup: one Pylon process per region, with app-level routing.

What about Docker?

The runtime image bundles the pylon binary plus Bun (which runs your TypeScript functions and SSR). It expects your app source mounted (or baked) at /app and keeps data on the /data volume:

docker run -d \
  --name pylon \
  -p 4321:4321 -p 4322:4322 -p 4323:4323 -p 4324:4324 \
  -v $(pwd):/app \
  -v /var/lib/pylon:/data \
  --env-file /etc/pylon/env \
  ghcr.io/pylonsync/pylon:latest

Same env vars apply. Mount the data volume so it survives container restarts. For a self-contained image (no runtime mount) or a docker-compose setup with a Postgres sidecar, run pylon deploy --target docker or pylon deploy --target compose in your project. Both commands generate a Dockerfile that copies your app onto the runtime image and serves it with pylon start.

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Migrate

Required environment

Ports

Shape 1: single VPS (SSH + systemd)

Caddy example

Shape 2: AWS ECS + Aurora (Terraform)

Shape 3: AWS via SST (TypeScript IaC)

Shape 4: Cloudflare Workers (edge, experimental)

Shape 5: Pylon Cloud

Shape 6: local dev

Health checks

Shutdown and rolling deploys

Native clients (iOS, macOS, Android)

Scale-out

What about Docker?

​Required environment

​Ports

​Shape 1: single VPS (SSH + systemd)

​Caddy example

​Shape 2: AWS ECS + Aurora (Terraform)

​Shape 3: AWS via SST (TypeScript IaC)

​Shape 4: Cloudflare Workers (edge, experimental)

​Shape 5: Pylon Cloud

​Shape 6: local dev

​Health checks

​Shutdown and rolling deploys

​Native clients (iOS, macOS, Android)

​Scale-out

​What about Docker?

Required environment

Ports

Shape 1: single VPS (SSH + systemd)

Caddy example

Shape 2: AWS ECS + Aurora (Terraform)

Shape 3: AWS via SST (TypeScript IaC)

Shape 4: Cloudflare Workers (edge, experimental)

Shape 5: Pylon Cloud

Shape 6: local dev

Health checks

Shutdown and rolling deploys

Native clients (iOS, macOS, Android)

Scale-out

What about Docker?