Installation

Requirements

Bun ≥ 1.0 is a runtime dependency. The pylon server binary spawns Bun as a child process to run TypeScript functions and render React SSR. Every install path below except Stack0 Cloud needs Bun on the host.
Rust: a recent stable toolchain (edition 2021). You need it only if you build the CLI from source. The prebuilt binary and Docker image need no Rust.
Node.js ≥ 18 (optional, for client tooling)

Fastest start: scaffold an app

The quickest path to a running full-stack app is the project scaffolder. It needs no global install, because it adds @pylonsync/cli as a dev dependency:

npm create @pylonsync/pylon@latest my-app
cd my-app
npm run dev

This scaffolds a full-stack SSR app (schema, policies, functions, and file-based React routes under app/). npm run dev runs the bundled CLI. Install the standalone CLI below if you want pylon on your PATH for other projects or CI.

Skip the install: use Stack0 Cloud

If you do not want to manage a binary or a server, Stack0 Cloud hosts the same backend you would run yourself. Sign up at www.pylonsync.com/dashboard, then:

pylon login
pylon deploy --target cloud

You will still want the CLI for local development and deploys. Install it below.

Install the CLI

curl -fsSL https://www.pylonsync.com/install.sh | bash

docker pull ghcr.io/pylonsync/pylon:latest

The one-line installer downloads a prebuilt binary to ~/.local/bin. It supports Linux and macOS, on x86_64 and arm64. It needs no Rust toolchain. Verify:

pylon --version
pylon doctor

pylon doctor checks that bun, node, and the supporting tooling are available.

Install Bun

Pylon uses Bun to run TypeScript server functions and to bundle the client code generator. If you do not have it:

curl -fsSL https://bun.sh/install | bash

Client SDKs

Web (React, Next.js, Vite, vanilla JS)

bun add @pylonsync/sdk @pylonsync/react

npm install @pylonsync/sdk @pylonsync/react

pnpm add @pylonsync/sdk @pylonsync/react

For Next.js, also add @pylonsync/next. See Clients → React and Clients → Next.js.

React Native (iOS + Android)

bun add @pylonsync/sdk @pylonsync/react @pylonsync/react-native
bun add @react-native-async-storage/async-storage expo-sqlite

See Clients → React Native.

Swift (iOS, macOS, tvOS, watchOS, Linux)

In your Package.swift:

.package(url: "https://github.com/pylonsync/pylon-swift.git", from: "0.3.0"),

Then per target:

.target(name: "MyApp", dependencies: [
    .product(name: "PylonClient",   package: "pylon-swift"),
    .product(name: "PylonSync",     package: "pylon-swift"),
    .product(name: "PylonSwiftUI",  package: "pylon-swift"),  // optional
])

Linux: apt-get install libsqlite3-dev for the SQLite-backed offline replica. See Clients → Swift.

Directory conventions

A Pylon app usually looks like this:

my-app/
  app.ts                 # schema + policies + manifest
  functions/             # server functions (*.ts)
  client/                # your React components
  web/                   # Vite app (or Next.js, etc.)
    package.json
    vite.config.ts
    src/main.tsx
  package.json
  pylon.manifest.json    # generated
  pylon.client.ts        # generated

pylon dev app.ts watches app.ts and functions/, and regenerates pylon.manifest.json and pylon.client.ts on every change.

Environment variables

Variable	Default	Purpose
`PYLON_DB_PATH`	`.pylon/dev.db`	SQLite file location (ignored if `DATABASE_URL` is set)
`DATABASE_URL`	(unset)	`postgres://...` connection string. When set, Pylon uses Postgres for application data, auth state, jobs, and workflows.
`PYLON_SESSION_DB`	next to the app database	SQLite auth-state sidecar. Postgres ignores this setting.
`PYLON_JOBS_DB`	next to the app database	SQLite job-queue sidecar. Postgres ignores this setting.
`PYLON_WORKFLOWS_DB`	next to the app database	SQLite workflow sidecar. Postgres ignores this setting.
`PYLON_JOB_WORKERS`	`2`	Number of local job workers. Shared Postgres claims prevent duplicate concurrent ownership.
`PYLON_CLUSTER_BUS`	(unset)	Redis URL for realtime fanout between self-hosted replicas. Stack0 Cloud supplies a managed relay.
`PYLON_CLUSTER_REQUIRED`	`false`	Refuse to start without the shared Postgres runtime stores and a cluster bus.
`PYLON_FILES_DIR`	`.pylon/uploads`	File upload storage
`PYLON_CORS_ORIGIN`	from `manifest.auth.trustedOrigins`	CORS allowlist override (comma-separated). Loopback origins are always allowed. `` is accepted only in dev, and answers with a literal `` and no credentials.
`PYLON_DEV_MODE`	`false` (`pylon dev` sets `1`)	Dev-only behavior: generous rate limits, and the dev shortcuts below. Only `1` or `true` turn it on.
`PYLON_HOST`	every interface (`pylon dev`: `localhost`)	Interfaces to listen on: `localhost` (127.0.0.1 and ::1), `0.0.0.0` (all), or one IP address. `pylon dev --host` sets it.
`PYLON_DEV_TRUST_REMOTE`	(unset)	`1` gives the dev shortcuts to callers on other machines. Without it they answer only requests from this machine.
`PYLON_PORT`	`4321`	HTTP port
`PYLON_DESIGN_MODE`	(unset)	With `pylon dev`: stamp SSR output with `data-pylon-src` and enable the `X-Pylon-Design` render, `/_pylon/dev/render`, and `X-Pylon-Design-Viewer`. See Design mode. Dev only.
`PYLON_DEV_FILE_API_TOKEN`	(unset)	Bearer token for the dev file API (`/_pylon/dev/files/*`), `/_pylon/dev/render`, and viewer impersonation. Unset limits the file API and render to callers on this machine whose page, if any, is on localhost, and disables impersonation.
`PYLON_RATE_LIMIT_MAX`	`100`	Max anonymous requests per window (per IP). Kept low, because anonymous traffic is the main target for repeated login attempts.
`PYLON_RATE_LIMIT_MAX_AUTHED`	`1000`	Max authenticated requests per window (per user id). Higher than the anonymous limit, because polling dashboards routinely exceed 100 requests/min for one legitimate user.
`PYLON_RATE_LIMIT_WINDOW`	`60`	Window in seconds. Applies to both the anonymous and authenticated limits.
`PYLON_FN_RATE_LIMIT_MAX`	`30`	Function calls per window

Dev shortcuts

Dev mode turns on shortcuts that give full control of the app:

dev_code / dev_token in magic-code, email-verification, phone, and magic-link responses
POST /api/auth/session and /api/auth/upgrade for any user id
the OAuth callback’s email parameter in place of a provider code
/admin/* and /metrics without a token (when no PYLON_ADMIN_TOKEN is set)
the dev file API and /_pylon/dev/render

They answer only requests from this machine: the connection comes from a loopback address, the Host header is localhost, *.localhost, 127.x.x.x, [::1], or the Android emulator’s 10.0.2.2, and the Origin header, if sent, is a localhost page. A request from another device, through a tunnel such as ngrok, from a page that re-pointed its own domain at 127.0.0.1, or from another website open in your browser is served as production. A local proxy that rewrites Host to localhost (ngrok --host-header=rewrite, a Vite proxy with changeOrigin, editor port forwarding) makes remote callers look local, so don’t run one on an untrusted network. pylon dev --host 0.0.0.0 lets your phone reach the dev server, and the phone signs in the normal way: email codes print to the pylon dev terminal when no email provider is set. See the CLI reference for the full list.

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Migrate

Installation

Requirements

Fastest start: scaffold an app

Skip the install: use Stack0 Cloud

Install the CLI

Install Bun

Client SDKs

Web (React, Next.js, Vite, vanilla JS)

React Native (iOS + Android)

Swift (iOS, macOS, tvOS, watchOS, Linux)

Directory conventions

Environment variables

Dev shortcuts

​Requirements

​Fastest start: scaffold an app

​Skip the install: use Stack0 Cloud

​Install the CLI

​Install Bun

​Client SDKs

​Web (React, Next.js, Vite, vanilla JS)

​React Native (iOS + Android)

​Swift (iOS, macOS, tvOS, watchOS, Linux)

​Directory conventions

​Environment variables

​Dev shortcuts

Requirements

Fastest start: scaffold an app

Skip the install: use Stack0 Cloud

Install the CLI

Install Bun

Client SDKs

Web (React, Next.js, Vite, vanilla JS)

React Native (iOS + Android)

Swift (iOS, macOS, tvOS, watchOS, Linux)

Directory conventions

Environment variables

Dev shortcuts