pylon

A self-hostable, single-binary backend for web, mobile, and real-time apps.

pylon gives you what Convex / Firebase / Supabase do — declarative schema, real-time sync, server functions, auth, file storage — but as a single Rust binary you can scp to a VPS or run with SQLite or Postgres.

# Install
cargo install --git https://github.com/ericc59/agentdb pylon-cli

# New project
pylon init my-app
cd my-app

# Dev server with live reload
pylon dev

Visit http://localhost:4321/studio for the inspector.

What you get

• Declarative schema in JSON or DSL → tables, types, OpenAPI, client types
• Real-time sync — clients see updates as they happen (WebSocket + SSE)
• TypeScript functions — mutation/query/action with typed ctx.db
  • Handler IS the transaction (atomic by default)
  • Streaming responses for AI chat / live data
• Auth — sessions, magic codes, OAuth (Google + GitHub), RBAC
• Real-time shards for multiplayer games & collab apps
  • Tick-driven simulations
  • Matchmaker, area-of-interest, replay
• Background jobs + cron scheduler
• Workflows — long-running, durable
• File storage, email, rate limiting, policies, plugins

How does it compare?

Quickstart

1. Install

# Curl-pipe-bash (Linux + macOS)
curl -fsSL https://raw.githubusercontent.com/ericc59/agentdb/main/install.sh | bash

# Homebrew
brew tap ericc59/agentdb https://github.com/ericc59/agentdb
brew install pylon

# From source
cargo install --git https://github.com/ericc59/agentdb pylon-cli

# Docker
docker pull ghcr.io/ericc59/agentdb:latest

2. Define your schema

pylon.manifest.json:

{
  "manifest_version": 1,
  "name": "todos",
  "version": "0.1.0",
  "entities": [
    { "name": "Todo", "fields": [
      { "name": "title", "type": "string", "optional": false, "unique": false },
      { "name": "done", "type": "bool", "optional": false, "unique": false }
    ], "indexes": [], "relations": [] }
  ],
  "routes": [], "queries": [], "actions": [], "policies": []
}

3. Run

pylon dev

4. Connect from React

import { init, db } from "@pylon/react";
init({ baseUrl: "http://localhost:4321" });

function TodoList() {
  const { data: todos } = db.useQuery("Todo");
  const { mutate: add } = db.useMutation("createTodo");

  return (
    <>
      {todos.map(t => <li key={t.id}>{t.title}</li>)}
      <button onClick={() => add({ title: "New todo" })}>Add</button>
    </>
  );
}

5. Add server-side logic

functions/createTodo.ts:

import { mutation, v } from "@pylon/functions";

export default mutation({
  args: { title: v.string() },
  async handler(ctx, args) {
    const id = await ctx.db.insert("Todo", {
      title: args.title,
      done: false,
      authorId: ctx.auth.userId,
    });
    return { id };
  },
});

6. Add a multiplayer shard (optional)

use pylon_realtime::{Shard, ShardConfig, SimState};

struct MyGame { /* state */ }
impl SimState for MyGame { /* tick, snapshot, apply_input */ }

let shard = Shard::new("match_1", MyGame::default(), ShardConfig {
    tick_rate_hz: 20,
    ..Default::default()
});

Then connect from the client:

import { useShard } from "@pylon/react";
const { snapshot, send } = useShard("match_1", { subscriberId: "player_42" });

Project layout

pylon/
├── crates/
│   ├── core/            Shared types, error codes, utilities
│   ├── http/            Platform-agnostic HTTP types + DataStore trait
│   ├── runtime/         SQLite-backed dev/prod server
│   ├── router/          HTTP routing logic, reused across platforms
│   ├── workers/         Cloudflare Workers adapter (experimental)
│   ├── functions/       Rust side of the TypeScript function runtime
│   ├── realtime/        Sharded game/collab server primitives
│   ├── auth/            Sessions, magic codes, OAuth, RBAC
│   ├── policy/          Access control rules engine
│   ├── sync/            Change log + push/pull
│   ├── storage/         SQLite + Postgres backends, file storage
│   ├── plugin/          Built-in plugins (cache, webhooks, soft delete, ...)
│   ├── migrate/         Schema migration diff engine
│   ├── cli/             The `pylon` binary
│   └── ...
└── packages/
    ├── sdk/             Schema DSL + manifest builder
    ├── react/           React hooks + typed client
    ├── react-native/    RN hooks + offline storage
    ├── next/            Next.js integration
    ├── functions/       Function definitions + Bun runtime
    ├── sync/            Sync engine (optimistic + offline-capable)
    ├── workflows/       Durable workflow runner
    └── create-pylon/  Project scaffolder

Configuration

All configuration is via environment variables. See crates/runtime/src/config.rs.

Common settings:

PYLON_PORT=4321
PYLON_DB_PATH=/var/lib/pylon/pylon.db
PYLON_FILES_DIR=/var/lib/pylon/uploads
PYLON_SESSION_DB=/var/lib/pylon/sessions.db
PYLON_ADMIN_TOKEN=<long random>
PYLON_CORS_ORIGIN=https://your-app.com
PYLON_DEV_MODE=false

Deployment

• Self-host: cargo install or docker run — see docs/ops/DEPLOY.md
• AWS ECS: see deploy/terraform/ and deploy/sst/
• Cloudflare Workers: see crates/workers/README.md (experimental)

Architecture docs:

• RUNTIME.md — how TypeScript functions execute, what JS engine, what we evaluated
• SYNC.md — sync semantics, what is and isn't local-first, conflict resolution
• ARCHITECTURE.md — crate-by-crate map of the system

Operational docs:

• DEPLOY.md — env vars, reverse proxy, health checks
• SIZING.md — measured throughput, capacity planning
• TOKEN_ROTATION.md — admin token rotation
• INCIDENT.md — incident response playbook
• WORKERS_COSTS.md — cost patterns on Cloudflare

Project status

Pre-1.0. API is stable enough to build with but may evolve. SQLite is the default backend and Postgres is supported for deployments that need an external database or horizontal database operations. Cloudflare Workers / D1 is experimental — see SECURITY.md for a list of pre-1.0 hardening gaps.

Contributing

See CONTRIBUTING.md. Bug reports and PRs welcome.

Security

See SECURITY.md for vulnerability reporting and hardening notes. Do not file security issues publicly. Email security@pylon.dev.

License

Dual-licensed under MIT or Apache-2.0 at your option.