Quickstart

Install Flux and debug your first production failure in 5 minutes.

1. Install

$ curl -fsSL https://fluxbase.co/install | bash

This installs three binaries: flux (CLI), flux-server, and flux-runtime.

2. Start the server

The server stores execution records in Postgres. Point it at any Postgres database:

$ flux server start --database-url postgres://user:pass@localhost:5432/flux

3. Write your app

Flux works with standard TypeScript using Hono as the HTTP framework and flux:pg for Postgres. Create index.ts:

import { Hono } from "npm:hono"
import pg from "flux:pg"

const app = new Hono()
const pool = new pg.Pool({
  connectionString: Deno.env.get("DATABASE_URL")
})

app.post("/orders", async (c) => {
  const body = await c.req.json()
  console.log("Incoming:", body)

  const result = await pool.query(
    "INSERT INTO orders (email, product_id) VALUES ($1, $2) RETURNING *",
    [body.email, body.productId]
  )
  return c.json(result.rows[0])
})

export default app

4. Serve

$ flux serve index.ts

  [ready] listening on http://localhost:8000

5. Watch live traffic

In a second terminal:

$ flux tail

  streaming live requests — ctrl+c to stop

  ✓  ok     POST /orders   88ms  a1b2c3d4
  ✗  error  POST /orders   21ms  e9f66586
     └─ HTTP Internal Server Error (500)

6. Understand the failure

$ flux why e9f66586

  POST /orders  ✗ error  21ms  e9f66586

  function threw before any IO
  error   Internal Server Error

  console
    › Incoming: {"email":"test@example.com","productId":"101"}
    ✗ Error: productId must be a number

  check input validation and early-exit logic

7. Fix & replay (safe — no real IO)

Edit your code. Then replay the original request against your fix:

$ flux replay e9f66586

  replaying e9f66586
  ✓ using updated code

  STEP 0 — POST /orders

  execution
    ✗ original execution failed before reaching external IO
    ✓ replay progressed beyond original failure point

  ⏸ stopped at external boundary: POSTGRES

  reason
    no recorded checkpoint available for this postgres call
    replay never touches the real world

  ✓ your code fix is working — replay progressed further than the original

  next
    → run flux resume e9f66586 to continue with real IO
Why did replay stop at POSTGRES?

Replay is deterministic and safe — it never makes live external calls. When the original request had no recorded DB checkpoint (it failed before reaching the DB), replay stops cleanly at the boundary. This confirms your code fix works without touching your database.

8. Resume with real IO

$ flux resume e9f66586

  resuming e9f66586…

  ✓ database write applied (43ms)

  ✓ request succeeded (200)

  output
    id:     9b887ab1
    email:  test@example.com

  ✓ original failure recovered

Next steps