Getting started

Quick start

Install the binary, create the first admin, and you have a running backend.

# One-line installer — downloads the signed binary, creates a service
curl -fsSL https://get.cogworks.dev | sh

# Create the first admin (CLI — never exposes a public web wizard)
cogworks setup-admin --email you@example.com --password '<strong-password>'

# Or just run it locally from the binary
./cogworks                 # serves on :8091, admin UI at /_/

Open the admin UI at http://localhost:8091/_/, create a collection, and you can immediately read and write records over the REST API:

# List records (public collections need no auth)
curl http://localhost:8091/api/v1/posts

# Create a record
curl -X POST http://localhost:8091/api/v1/posts \
  -H 'content-type: application/json' \
  -d '{"title":"Hello","body":"First post"}'
# → {"data":{"id":"…","title":"Hello","created":1751,"updated":1751}}

From an app, it’s plain fetch — log in, keep the token, send it as a bearer header:

const base = "http://localhost:8091/api/v1";

// sign in
const { data } = await fetch(`${base}/auth/users/login`, {
  method: "POST", headers: { "content-type": "application/json" },
  body: JSON.stringify({ email, password }),
}).then(r => r.json());
const token = data.token;

// authenticated write
await fetch(`${base}/posts`, {
  method: "POST",
  headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
  body: JSON.stringify({ title: "Hello", status: "published" }),
});

Architecture

Cogworks is one process. It bundles the HTTP server, the admin single-page app, and the database driver into a single compiled executable. There is nothing else to deploy.

Layer	Choice	Why
Runtime	Bun	Fast startup, native SQLite & S3 clients, single-file `--compile`
HTTP	Hono	Small, fast router; the whole request pipeline is one middleware chain
Database	`bun:sqlite` (WAL)	Embedded, transactional, concurrent readers; no separate DB server
Admin UI	React SPA	Embedded into the binary at build time — served from `/_/`

User collections are stored in tables prefixed cw_<name>; internal state lives in cogworks_* tables. The data directory (default ./cogworks_data) holds data.db, uploads/, logs/, and the generated JWT secret.