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 Pylon 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 Pylon Cloud

If you do not want to manage a binary or a server, Pylon 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

cargo install --git https://github.com/pylonsync/pylon pylon-cli

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. Pylon 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). `*` only in dev. Loopback always auto-trusted.
`PYLON_DEV_MODE`	`true`	Dev-only behavior (generous rate limits, CORS `*` fallback when neither manifest nor env is set)
`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 leaves the file API open 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

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 Pylon 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

​Requirements

​Fastest start: scaffold an app

​Skip the install: use Pylon 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

Requirements

Fastest start: scaffold an app

Skip the install: use Pylon 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