Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

The full-stack app format

fleet init gives you a complete, working app in a handful of files. Keep this layout and let Fleet handle bundling, serving, HTTPS, and worker lifecycle for you.

Files in an app checkout

  • fleet.json — app ID, name, scheduled jobs, and optional HTML head settings (title, themeColor, icon, manifest).
  • client/index.tsx — Preact browser entry point.
  • client/style.css — stylesheet imported by the client.
  • server/index.ts — server queries, mutations, and jobs.
  • public/ — optional static files served from the app root (for example /icon.svg or /manifest.webmanifest).
  • fleet.d.ts — TypeScript definitions for fleet/client, FleetCtx, and FleetDb.
  • AGENTS.md — concise instructions so any coding agent understands how Fleet works.
  • .env.fleet.server — server-only environment variables, automatically ignored by Git.
Your app name becomes its private origin, like https://notes.fleet. Keep the generated id in fleet.json — Fleet uses it to locate the app's persistent SQLite database.

Server operations

Export a default object from server/index.ts with queries, mutations, and optional jobs:
export default { queries: { notes(ctx) { return ctx.db.get('notes') ?? []; }, }, mutations: { addNote(ctx, input) { if (typeof input?.text !== 'string' || !input.text.trim()) { throw new Error('Enter a note.'); } const note = { id: crypto.randomUUID(), text: input.text.trim(), }; const notes = ctx.db.get('notes') ?? []; ctx.db.set('notes', [note, ...notes]); return note; }, }, };
Here is how Fleet runs them:
  • Queries are read-only and can run concurrently while an async mutation is in flight, reading committed SQLite data.
  • Mutations and jobs run in SQLite transactions, serialized per app. If a handler throws, Fleet automatically rolls back every ctx.db write from that call.
  • Every handler receives ctx: ctx.user.id (the owner identity), ctx.db (get, set, delete, list), ctx.env (from .env.fleet.server), ctx.log(...), and ctx.runId (for scheduled jobs).
  • Keep handlers fast: browser queries and mutations time out after 15 seconds, and jobs time out after 30 seconds. Always validate input on the server.

Browser client

Fleet bundles Preact for you (and aliases react / react-dom to preact/compat), so you don't need to install Preact inside each app. Import useQuery, useMutation, and call from fleet/client:
import { render } from 'preact'; import { useQuery, useMutation } from 'fleet/client'; import './style.css'; function App() { const { data: notes, error } = useQuery('notes'); const addNote = useMutation('addNote'); if (error) return <p role="alert">{error.message}</p>; if (notes === undefined) return <p role="status">Loading…</p>; return ( <main> <h1>My notes</h1> <button onClick={async () => { try { await addNote({ text: 'Hello from my app' }); } catch (err) { alert(err.message); } }} > Add a note </button> {notes.map((note) => ( <p key={note.id}>{note.text}</p> ))} </main> ); } render(<App />, document.getElementById('app'));
Client helpers give you fine-grained control when you need it:
  • useQuery(name, input?, { pollMs? }) returns { data, error } and polls every 10 seconds while the tab is visible. Pass { pollMs: false } or { pollMs: 0 } to disable polling.
  • useMutation(name, { invalidate? }) refreshes all active queries by default. Pass { invalidate: ['notes'] } to refresh specific queries or { invalidate: false } to skip refreshing.
  • call(kind, name, input?, { keepalive? }) invokes an operation directly without refetching queries — handy with { keepalive: true } for small writes on page unload.
Uncaught browser errors and unhandled promise rejections are automatically reported back to Fleet and written to fleet logs APP, so your agent can spot frontend crashes without opening DevTools.

Static assets and HTML head

Drop icons, manifests, fonts, or images into public/. Fleet snapshots public/ alongside each build and serves those files from the site root (for example, public/icon.svg is served at /icon.svg).
You can customize the HTML <head> in fleet.json:
{ "title": "My Notes", "themeColor": "#101214", "icon": "/icon.svg", "manifest": "/manifest.webmanifest" }

Server-only secrets

Store API keys and tokens in .env.fleet.server and read them with ctx.env inside server handlers. Fleet automatically adds .env.fleet.server to .gitignore and never includes it in browser bundles. Just make sure your server handlers don't return or log secret values.

Builds and worker lifecycle

Fleet watches your checkout and bundles both the client and server with Bun whenever files change. A successful build reloads open browsers automatically (note that unsaved form input isn't preserved across reloads). A broken build leaves the previous working bundle online and writes the compiler error to fleet logs APP.
App workers wake on the first request and shut down after 30 seconds of inactivity while cached frontends stay ready. Put anything that needs to survive restarts in ctx.db, not module-level variables. See data and jobs.
App code runs with your normal operating-system user permissions, not inside an untrusted-code sandbox. Review agent-written code before giving an app sensitive credentials or access to private files.