> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pylonsync.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Pylon CLI and runtime.

## Requirements

* **Bun** ≥ 1.0 — a required runtime dependency, not just a build tool. The `pylon` server binary spawns Bun as a child process to run your 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). Only needed 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 — no global install required, because it wires `@pylonsync/cli` in as a dev dependency:

```bash theme={null}
npm create @pylonsync/pylon@latest my-app
cd my-app
npm run dev
```

That scaffolds a full-stack SSR app (schema, policies, functions, and file-based React routes under `app/`) and `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 don't want to manage a binary or a server, [Pylon Cloud](/cloud) hosts the same backend you'd run yourself. Sign up at [www.pylonsync.com/dashboard](https://www.pylonsync.com/dashboard), then:

```bash theme={null}
pylon login
pylon deploy --target cloud
```

You'll still want the CLI for local development and deploys; install it below.

## Install the CLI

<CodeGroup>
  ```bash one-line installer (recommended) theme={null}
  curl -fsSL https://www.pylonsync.com/install.sh | bash
  ```

  ```bash Docker theme={null}
  docker pull ghcr.io/pylonsync/pylon:latest
  ```

  ```bash Cargo (compiles from source) theme={null}
  cargo install --git https://github.com/pylonsync/pylon pylon-cli
  ```
</CodeGroup>

The one-line installer downloads a prebuilt binary to `~/.local/bin`. Linux and macOS, x86\_64 and arm64. No Rust toolchain required.

Verify:

```bash theme={null}
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 don't have it:

```bash theme={null}
curl -fsSL https://bun.sh/install | bash
```

## Client SDKs

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

<CodeGroup>
  ```bash bun theme={null}
  bun add @pylonsync/sdk @pylonsync/react
  ```

  ```bash npm theme={null}
  npm install @pylonsync/sdk @pylonsync/react
  ```

  ```bash pnpm theme={null}
  pnpm add @pylonsync/sdk @pylonsync/react
  ```
</CodeGroup>

For Next.js, also add `@pylonsync/next`. See [Clients → React](/clients/react) and [Clients → Next.js](/clients/next).

### React Native (iOS + Android)

```bash theme={null}
bun add @pylonsync/sdk @pylonsync/react @pylonsync/react-native
bun add @react-native-async-storage/async-storage expo-sqlite
```

See [Clients → React Native](/clients/react-native).

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

In your `Package.swift`:

```swift theme={null}
.package(url: "https://github.com/pylonsync/pylon-swift.git", from: "0.3.0"),
```

Then per target:

```swift theme={null}
.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](/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` + `functions/` and regenerates `pylon.manifest.json` + `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 the Postgres adapter instead of SQLite                                                        |
| `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_RATE_LIMIT_MAX`        | `100`                               | Max **anonymous** requests per window (per IP). Kept tight — anon traffic is the brute-force surface.                                                  |
| `PYLON_RATE_LIMIT_MAX_AUTHED` | `1000`                              | Max **authenticated** requests per window (per user id). Higher than anon because polling dashboards routinely exceed 100/min for a single legit user. |
| `PYLON_RATE_LIMIT_WINDOW`     | `60`                                | Window in seconds (applies to both anon + authed limits).                                                                                              |
| `PYLON_FN_RATE_LIMIT_MAX`     | `30`                                | Function calls per window                                                                                                                              |

See [Reference → CLI](/reference/cli) for the full list.