# ownbackend

> ownbackend gives an app a backend (database, REST API, auth, file storage, realtime) that runs on the owner's own device and is online at https://<name>.ownbackend.app. The backend is PocketBase 0.40: its API and JavaScript SDK work as PocketBase documents them.

Key facts for AI agents:

- Owners create a backend at https://app.ownbackend.com (sign-in by emailed code) and connect a device with `ownbackend connect --relay wss://app.ownbackend.com <code>`, then run `ownbackend serve` in the same folder.
- Install: `curl -fsSL https://ownbackend.com/install.sh | sh` (Linux, macOS; installs to ~/.local/bin).
- The app's API base URL is https://<name>.ownbackend.app (CORS allows any origin). The device also serves the app's frontend from `dist/` in the project folder (Vite's default build output); single-page apps work.
- The owner may not be technical and has no admin dashboard: you manage the backend's data and rules through ownbackend's MCP server on the device (`ownbackend mcp --dir <project>/.ownbackend/data`; tools: status, create_backend, check_pairing, connect, collections and records). Admin access works only on the device itself, never through the public URL. Explain things to the owner in plain words and leave PocketBase out unless they ask.
- Project layout: the backend's files are in the hidden `.ownbackend/` folder: `data/` (database, files, device link; git-ignored, never commit it), `migrations/` and `hooks/` (commit them).
- An agent can create the backend itself: MCP `create_backend` returns a link the owner opens to approve; then `check_pairing`, then `ownbackend serve` in the project folder.
- When the device is offline, API calls get HTTP 503 with JSON `{"error":"host_offline", "note": <owner's message>}`; handle it as a temporary outage.

## Docs

- [Quickstart](https://ownbackend.com/docs/quickstart.md): create a backend, install, connect, run
- [Using your backend from an app](https://ownbackend.com/docs/api.md): address, SDK, rules, sign-in, the relay's error answers
- [MCP server for AI agents](https://ownbackend.com/docs/mcp.md): setup for Claude Code, Cursor and others; the tools and the order to use them
- [Running on your device](https://ownbackend.com/docs/devices.md): background service, sleep, alerts, backups, restore, moving devices

## Optional

- [PocketBase documentation](https://pocketbase.io/docs/): the full API and SDK reference