Deploy with SST

SST is a TypeScript framework for defining AWS (and other cloud) infrastructure. It is the cleanest way to deploy Pylon to AWS without writing Terraform. One sst.config.ts provisions Aurora Postgres, an S3 bucket for uploads, an ECS Fargate cluster, and a CloudFront CDN. The load balancer forwards WebSocket, SSE, and shard ports. The default shape is stateless. Postgres holds app data and sessions, and S3 holds files. The container can scale horizontally without losing state. A working reference config ships in deploy/sst/sst.config.ts.

What you get

Aurora Serverless v2 Postgres for app data and sessions (auto-scaling 0.5–2 ACU, ~$15/mo minimum)
S3 bucket for file uploads (linked to the service for IAM)
ECS Fargate running the Pylon container (0.25 vCPU / 512 MB ~ $9/mo, horizontally scalable)
Application Load Balancer with WebSocket, SSE, and shard port forwarding, and sticky sessions
AWS Secrets Manager for the admin token and OAuth credentials
CloudFront CDN in front of the ALB
Route 53 and ACM for custom domains and TLS

Total minimum bill: ~$25/mo for a production deployment.

Prerequisites

# 1. SST CLI (v3 / Ion)
curl -fsSL https://ion.sst.dev/install | bash

# 2. AWS CLI configured
aws configure  # or AWS_PROFILE / SSO

# 3. Pylon CLI for local dev
curl -fsSL https://www.pylonsync.com/install.sh | bash

# 4. Docker (for local Postgres in dev)
# Already installed if you've used Docker Desktop / OrbStack

You will need an AWS account with permissions to create VPCs, ECS services, RDS, ALB, ACM, Route 53, S3, and Secrets Manager. SST’s default IAM role assumes broad permissions. Lock it down to match your organization’s standards.

Project layout

my-pylon-app/
├── app.ts                     # Pylon schema + manifest entry
├── pylon.manifest.json        # generated
├── functions/                 # server functions
├── Dockerfile                 # Pylon's published Dockerfile or your own
├── docker-compose.dev.yml     # local Postgres for dev
├── sst.config.ts              # SST infrastructure definition
└── package.json

The container image must bundle the Pylon binary and Bun. The binary spawns Bun to run your TypeScript functions and SSR. Pylon’s published image (ghcr.io/pylonsync/pylon, which pylon deploy --target docker builds on) already includes both. If you write your own Dockerfile, install Bun (curl -fsSL https://bun.sh/install | bash), or your app’s functions and SSR will fail at runtime.

The default config: Aurora and S3

/// <reference path="./.sst/platform/config.d.ts" />

export default $config({
  app(input) {
    return {
      name: "my-pylon-app",
      removal: input?.stage === "production" ? "retain" : "remove",
      home: "aws",
      providers: { aws: { region: "us-east-1" } },
    };
  },
  async run() {
    // ── Secrets ──────────────────────────────────────────────────
    const adminToken = new sst.Secret("PylonAdminToken");
    const oauthGoogle = new sst.Secret("OAuthGoogleClientSecret");
    const oauthGithub = new sst.Secret("OAuthGithubClientSecret");

    // ── Database ─────────────────────────────────────────────────
    // Aurora Serverless v2 — auto-scales 0.5 → 2 ACU. Holds app data
    // AND sessions; the container is stateless.
    const db = new sst.aws.Postgres("PylonDb", {
      scaling: { min: "0.5 ACU", max: "2 ACU" },
    });

    // ── File storage ─────────────────────────────────────────────
    // Pylon's S3 backend signs requests with static credentials read
    // from env — it does NOT auto-discover the ECS task role — so
    // provision a bucket-scoped IAM user and hand the service its key.
    const uploads = new sst.aws.Bucket("PylonUploads");
    const s3User = new aws.iam.User("PylonS3User");
    new aws.iam.UserPolicy("PylonS3UserPolicy", {
      user: s3User.name,
      policy: uploads.arn.apply((arn) =>
        JSON.stringify({
          Version: "2012-10-17",
          Statement: [
            {
              Effect: "Allow",
              Action: ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
              Resource: `${arn}/*`,
            },
          ],
        }),
      ),
    });
    const s3Key = new aws.iam.AccessKey("PylonS3Key", { user: s3User.name });

    // ── Cluster + service ────────────────────────────────────────
    const cluster = new sst.aws.Cluster("PylonCluster", {
      vpc: { id: db.nodes.vpc.id },
    });

    new sst.aws.Service("PylonService", {
      cluster,
      cpu: "0.25 vCPU",
      memory: "512 MB",
      image: { dockerfile: "./Dockerfile" },
      health: { command: ["CMD-SHELL", "curl -fsS http://localhost:4321/health || exit 1"], interval: "30 seconds" },
      // Stateless container — safe to scale horizontally.
      scaling: { min: 1, max: 4, cpuUtilization: 70 },
      link: [uploads],
      environment: {
        // Core
        DATABASE_URL: db.url,
        PYLON_PORT: "4321",
        PYLON_DEV_MODE: "false",
        // File storage — pylon's built-in S3 backend (SigV4 presigned URLs).
        PYLON_FILES_PROVIDER: "s3",
        PYLON_S3_BUCKET: uploads.name,
        PYLON_S3_REGION: "us-east-1",
        PYLON_S3_ACCESS_KEY: s3Key.id,
        PYLON_S3_SECRET_KEY: s3Key.secret,
        // Auth (secrets)
        PYLON_ADMIN_TOKEN: adminToken.value,
        // Client-facing
        PYLON_CORS_ORIGIN: "https://your-app.com",
        PYLON_CSRF_ORIGINS: "https://your-app.com",
        // OAuth (optional)
        PYLON_OAUTH_GOOGLE_CLIENT_ID: "your-google-client-id",
        PYLON_OAUTH_GOOGLE_CLIENT_SECRET: oauthGoogle.value,
        PYLON_OAUTH_GITHUB_CLIENT_ID: "your-github-client-id",
        PYLON_OAUTH_GITHUB_CLIENT_SECRET: oauthGithub.value,
      },
      loadBalancer: {
        // ALB rules forward all four Pylon ports:
        //   4321 → HTTP API
        //   4322 → WebSocket sync
        //   4323 → SSE fallback (/events)
        //   4324 → realtime shards
        rules: [
          { listen: "443/https", forward: "4321/http" },
          { listen: "4322/tcp",  forward: "4322/tcp" },
          { listen: "4323/tcp",  forward: "4323/tcp" },
          { listen: "4324/tcp",  forward: "4324/tcp" },
        ],
        // ACM cert provisioned automatically when domain is set:
        domain: { name: "api.your-app.com", dns: sst.aws.dns() },
        idleTimeout: "3600 seconds",
        // Required when scaling.max > 1: keep WebSockets pinned to one
        // replica so reconnects don't lose presence state.
        stickySessions: true,
      },
    });
  },
});

Credentials are read from environment variables only. Pylon’s S3 backend signs requests with PYLON_S3_ACCESS_KEY and PYLON_S3_SECRET_KEY (plus an optional PYLON_S3_SESSION_TOKEN for temporary or STS credentials). It does not auto-discover the ECS task role from the container credentials endpoint or EC2 IMDS, so link: [uploads] alone is not enough. Provision a bucket-scoped IAM user’s static key as shown above, or inject the task role’s temporary credentials (access key, secret, and session token) into the environment through your entrypoint.The server validates the S3 environment at boot and fails fast if PYLON_FILES_PROVIDER=s3 but a required variable is missing. It never silently falls back to local disk, which on a stateless Fargate container would lose uploads on every redeploy.

Local development

Mirror the production stack locally so SQL queries, indexes, and policies behave the same way. The cheapest setup is Postgres in Docker plus local-disk file storage. You do not need MinIO for dev unless your code exercises S3-specific behavior. docker-compose.dev.yml:

services:
  db:
    image: postgres:16-alpine
    ports: ["5432:5432"]
    environment:
      POSTGRES_USER: pylon
      POSTGRES_PASSWORD: pylon
      POSTGRES_DB: pylon
    volumes:
      - pylon-db:/var/lib/postgresql/data

volumes:
  pylon-db:

Boot it once:

docker compose -f docker-compose.dev.yml up -d

Run Pylon against it:

DATABASE_URL=postgres://pylon:pylon@localhost:5432/pylon pylon dev

A .env file at the project root keeps this out of your shell history:

DATABASE_URL=postgres://pylon:pylon@localhost:5432/pylon
PYLON_FILES_DIR=./.pylon/uploads

pylon dev reads .env automatically. Restart the dev server when you change it. To also test against S3 locally, point PYLON_FILES_PROVIDER=s3 at MinIO running in the same docker-compose:

services:
  # ...db service above...
  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    ports: ["9000:9000", "9001:9001"]
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin

PYLON_FILES_PROVIDER=s3
PYLON_S3_BUCKET=pylon-uploads
PYLON_S3_ENDPOINT=http://localhost:9000
PYLON_S3_ACCESS_KEY=minioadmin
PYLON_S3_SECRET_KEY=minioadmin

The file_storage plugin treats MinIO as a drop-in S3 replacement. It uses the same wire protocol.

Set secrets

Before the first deploy, set the secret values with the SST CLI:

# Generate a random admin token (256 bits)
openssl rand -hex 32 | xargs sst secret set PylonAdminToken

# OAuth secrets from Google Cloud Console / GitHub OAuth Apps
sst secret set OAuthGoogleClientSecret
sst secret set OAuthGithubClientSecret

Secrets are stored in AWS Parameter Store, encrypted with a KMS key SST creates per-app.

Deploy

# First time — provisions everything (~10 minutes for Aurora cold start)
sst deploy --stage production

# Subsequent deploys (only the container changes) — `<2 min`
sst deploy --stage production

Once the deploy finishes, SST prints the ALB URL. Test it:

curl https://api.your-app.com/health
# → {"status":"ok","uptime_seconds":42}

Custom domain

The domain block under loadBalancer provisions an ACM certificate and points Route 53 at the ALB. If you use a different DNS provider, swap the dns provider:

domain: {
  name: "api.your-app.com",
  dns: sst.cloudflare.dns(),  // or sst.vercel.dns()
}

Multiple environments

sst deploy --stage staging       # → staging.your-app.com
sst deploy --stage production    # → api.your-app.com
sst deploy --stage pr-42         # → pr-42.preview.your-app.com (per-PR previews)

Each stage gets its own Aurora cluster, S3 bucket, and ALB. Use the removal config so non-production environments tear down cleanly:

app(input) {
  return {
    removal: input?.stage === "production" ? "retain" : "remove",
    // ...
  };
}

Alternative: single-replica with local state (EFS and SQLite)

If you want to run Pylon as a single replica with SQLite and local files (for example, an internal tool, a hobby app, or a hard requirement to avoid Postgres and S3), mount EFS instead of using Aurora and S3:

const efs = new sst.aws.Efs("PylonEfs", { vpc: { id: cluster.nodes.vpc.id } });

new sst.aws.Service("PylonService", {
  cluster,
  cpu: "0.25 vCPU",
  memory: "512 MB",
  image: { dockerfile: "./Dockerfile" },
  scaling: { min: 1, max: 1 },   // single replica only
  volumes: [{ efs, path: "/var/lib/pylon" }],
  environment: {
    PYLON_DB_PATH: "/var/lib/pylon/pylon.db",
    PYLON_SESSION_DB: "/var/lib/pylon/sessions.db",
    PYLON_FILES_DIR: "/var/lib/pylon/uploads",
    // no DATABASE_URL → uses SQLite at PYLON_DB_PATH
  },
});

Trade-offs:

✅ About $10/mo cheaper (no Aurora minimum)
✅ One backing service to think about
❌ Cannot scale horizontally: SQLite is single-writer, and mounting EFS into multiple containers corrupts the database
❌ EFS latency (about 5ms) is noticeably slower than Aurora (about 1ms in-VPC)
❌ Backups are your responsibility (Aurora has them built in)

Use the default Aurora and S3 shape unless you have a specific reason not to.

CDN in front of the ALB

For static-asset caching and global edge presence:

const cdn = new sst.aws.Cdn("PylonCdn", {
  origins: [{ domainName: service.url }],
  domain: { name: "your-app.com", dns: sst.aws.dns() },
});

CloudFront caches GET responses with appropriate Cache-Control headers. WebSocket and SSE traffic should bypass the CDN. Point your sync engine’s wsUrl directly at the ALB:

createSyncEngine("https://your-app.com", {
  wsUrl: "wss://api.your-app.com:4322",
});

Horizontal scale

The default config already scales horizontally (scaling: { min: 1, max: 4 }). Increase it for read-heavy apps:

scaling: {
  min: 2,
  max: 20,
  cpuUtilization: 70,
}

Requirements for a correct multi-replica deploy:

Postgres backend ✅: DATABASE_URL is set, with no SQLite. The default config satisfies this requirement.
Externalized file storage ⚠️: the default config points at S3, which is not wired yet (see the warning under The default config). Use PYLON_FILES_PROVIDER=stack0 for externalized files, or keep a single replica on the EFS and SQLite shape.
Sticky WebSocket sessions ✅: stickySessions: true on the load balancer. The default config satisfies this requirement.
Cross-replica live fanout ❌: WebSocket broadcasts are in-process by default, so a mutation handled by replica A never reaches clients on replica B until their next reconcile(). The default config does not address this. Set the cluster bus before scaling past one replica.

Jobs and workflows need no Redis. They use the shared Aurora database and can fail over between replicas. Their handlers must be idempotent because execution is at least once. For cross-replica fanout, run ElastiCache Redis and point every replica at it with PYLON_CLUSTER_BUS. Pylon refuses to boot if the bus is set but unreachable (loud failure beats silent split-brain). See Horizontal scaling.

const redis = new sst.aws.Redis("PylonBus", { vpc: { id: db.nodes.vpc.id } });

new sst.aws.Service("PylonService", {
  // ...
  link: [uploads, redis],
  environment: {
    // ...
    PYLON_CLUSTER_BUS: redis.url,      // redis://… — cross-machine change/presence/CRDT fanout
    PYLON_CLUSTER_NAMESPACE: "my-pylon-app",
  },
});

For shard-based multiplayer, prefer dedicated single-replica services per region. Shards do not scale horizontally within a region.

Observability

new sst.aws.Service("PylonService", {
  // ...
  logging: {
    retention: "30 days",
  },
});

Logs ship to CloudWatch automatically. For richer observability:

Metrics: Pylon exposes /metrics in Prometheus format. Scrape with AWS Managed Prometheus or Grafana Cloud.
Traces: add OpenTelemetry exporter environment variables, and SST injects the right IAM permissions for X-Ray.

Compared to Pylon Cloud

If you are not committed to AWS, Pylon Cloud gives you the same managed Postgres, S3, TLS, and WebSocket-aware load balancing with one CLI command (pylon deploy --target cloud) and per-use pricing. SST is the right choice when:

You must run in AWS (compliance, existing infrastructure, reserved instance commitments)
You want to compose Pylon with other AWS services (Bedrock, SageMaker, IoT Core, Kinesis)
You want full infrastructure-as-code control over networking, IAM, and secrets

Both are valid. Pylon’s wire protocol is identical regardless of how you host it.

Troubleshooting

WebSocket connections fail with 504. The ALB idle timeout defaults to 60s. The default config bumps it to 1 hour with idleTimeout: "3600 seconds". Cold start takes 10+ minutes the first time. Aurora Serverless v2’s first cold start provisions storage. Subsequent deploys take under 2 minutes. Uploads do not land in S3. This is expected: the runtime’s storage selector does not wire the S3 backend yet (see the warning under The default config), so PYLON_FILES_PROVIDER=s3 writes to local container disk. Use PYLON_FILES_PROVIDER=stack0 for externalized storage, or use the single-replica EFS and SQLite shape instead. (The link: [uploads] IAM grant is still correct for when S3 support lands.) Local dev errors with connection refused. Postgres is not running. docker compose -f docker-compose.dev.yml ps should show the db service as Up. If it does not, run docker compose up -d db. Local dev sessions disappear on restart. Sessions are stored in Postgres now (the same DATABASE_URL), so they persist as long as the Postgres volume does. If you run docker compose down -v (note the -v flag), the volume is destroyed and sessions clear. Secrets are not visible in the container. Make sure you ran sst secret set in the same stage you are deploying to. Secrets are set per stage.

Cost optimization

Component	Default cost	Optimization
Aurora Serverless v2 (0.5 ACU min)	~$15/mo	Drop `min` to `0.5 ACU` and let it scale up only on load
Fargate (0.25 vCPU / 512 MB)	~$9/mo	Use Fargate Spot for non-prod
ALB	~$16/mo	Single ALB for all stages via shared listeners
S3 (bucket + traffic)	~$0–5/mo	Lifecycle policies for old uploads; CloudFront in front to cache
NAT Gateway	~$32/mo	Skip the NAT (single AZ) for non-prod; use VPC endpoints in prod
CloudWatch logs	~$0.50/GB	Set `retention: "7 days"` for non-prod
Secrets Manager	$0.40/secret/mo	Few secrets; minor cost

A bare-bones non-production stack runs about

30/mo. Production with NAT and multi-AZ runs about

80 to $150/mo, depending on traffic. For low-traffic apps, Pylon Cloud is often cheaper than the AWS minimums.

Reference config

The full working config is at deploy/sst/sst.config.ts. Clone it as a starting point:

cp deploy/sst/sst.config.ts your-app/sst.config.ts
cd your-app
sst secret set PylonAdminToken
sst deploy --stage production

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Migrate

Deploy with SST

What you get

Prerequisites

Project layout

The default config: Aurora and S3

Local development

Set secrets

Deploy

Custom domain

Multiple environments

Alternative: single-replica with local state (EFS and SQLite)

CDN in front of the ALB

Horizontal scale

Observability

Compared to Pylon Cloud

Troubleshooting

Cost optimization

Reference config

​What you get

​Prerequisites

​Project layout

​The default config: Aurora and S3

​Local development

​Set secrets

​Deploy

​Custom domain

​Multiple environments

​Alternative: single-replica with local state (EFS and SQLite)

​CDN in front of the ALB

​Horizontal scale

​Observability

​Compared to Pylon Cloud

​Troubleshooting

​Cost optimization

​Reference config

What you get

Prerequisites

Project layout

The default config: Aurora and S3

Local development

Set secrets

Deploy

Custom domain

Multiple environments

Alternative: single-replica with local state (EFS and SQLite)

CDN in front of the ALB

Horizontal scale

Observability

Compared to Pylon Cloud

Troubleshooting

Cost optimization

Reference config