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

Persistent data and scheduled work

Every app's database and job schedule live under ~/.fleet/v2, outside your source checkout. Rebuilding an app, unloading an idle worker, or restarting Fleet never wipes your data.

Persistent JSON storage

Server handlers store JSON documents through ctx.db:
  • ctx.db.get(key) — returns the stored value, or null if the key doesn't exist.
  • ctx.db.set(key, value) — saves a JSON value up to 2 MB (mutations and jobs only).
  • ctx.db.delete(key) — deletes a key and returns true if it existed (mutations and jobs only).
  • ctx.db.list(prefix?) — returns up to 1,000 { key, value } entries matching a key prefix.
// Inside a mutation or job handler: const settings = ctx.db.get('settings') ?? { theme: 'system' }; ctx.db.set('settings', { ...settings, theme: 'dark' });
Mutations and jobs run inside implicit SQLite transactions: if your handler throws, all ctx.db changes from that call roll back automatically. Keep in-memory module state disposable because workers unload after 30 seconds of inactivity.

Scheduled jobs

To run work in the background, add a jobs entry to fleet.json (keeping the existing version, id, and name fields):
{ "jobs": [ { "name": "dailyCheck", "everySeconds": 86400 } ] }
Then export a matching handler under jobs in server/index.ts:
export default { queries: {}, mutations: {}, jobs: { dailyCheck(ctx) { ctx.db.set('lastCheck', new Date().toISOString()); ctx.log('Daily check completed', ctx.runId); }, }, };
A few important details about jobs:
  • Jobs run without a browser open, as long as the computer hosting the app is awake.
  • If the computer was asleep or off when a job was due, Fleet runs one catch-up execution after restart (not every missed tick).
  • If a job is interrupted mid-run, Fleet retries it with the same ctx.runId — pass ctx.runId as an idempotency key when calling external APIs.
  • Each job run has a 30-second timeout. You can trigger a job manually with fleet call APP jobs NAME and check its history with fleet inspect APP and fleet logs APP.

Back up and restore

Take a consistent SQLite snapshot at any time while the app is running (from the computer with the app checkout):
fleet backup notes --output notes.sqlite
The destination file must not already exist, and the app must have written data at least once. Keep a copy off that machine alongside your source backups.
To restore a snapshot, stop the Fleet service using your OS service controls first (so nothing writes while restoring), then run:
fleet restore notes notes.sqlite
Fleet validates the backup, keeps a copy of the database it replaces, and swaps the restored file in cleanly. Restart Fleet afterward.
A failed build preserves the last working app bundle, not a previous database state. A change that compiles can still write bad data, so back up before schema migrations or big edits.
Running fleet unregister notes or fleet uninstall leaves both your source checkout and stored SQLite data untouched. Treat backups carefully — they contain your private app data.