What is an instance
One running voidbase. Every guide in this section produces the same thing, and they differ only in where it runs and how much of it you keep in version control.
An instance is these four things and an address:
- The database. One SQLite database holding your collections and their records.
- The files. Whatever has been uploaded to those records.
- The definition. The collections, the API rules, the hooks, the configuration and the installed plugins. This is the part that can live in a repository.
- The superuser. One account that can open the admin panel.
The API is PocketBase's, so the same request works against every one of them. An instance on your laptop and an instance on Cloudflare answer identically, which is what makes moving between the shapes below a change of address rather than a rewrite.
curl https://your-instance.example.com/api/collections/posts/recordsWhat it carries
More than the API. voidbase composes its server from plugins, and these ship inside every instance: auth, realtime, hardening, backups, installer, openapi, mcp, seo, mail, ai, translations, stripe, polar, lemonsqueezy, previews and domains. Several do nothing until a knob names them (a provider's key, a mail domain, the translatable fields), and any of them can be turned off for a project or replaced by one with the same name from a marketplace.
What every instance answers, whichever way it runs:
/api/: PocketBase's REST API, records, auth, files, realtime, batch/_/: the admin panel, PocketBase's own build, unmodified/api/docs: the instance's own API reference, over/api/openapi.json, scoped to the token it is opened with and to what its rules let that token reach/api/mcp: a stateless MCP server whose tools are the routes your token may call/robots.txt,/sitemap.xml,/llms.txt: generated from the public collections, unless a real file wins/api/plugins: what this instance loaded and where each plugin came from, for a superuser
Where it can run
Three ways, and the same instance in each. Which one decides how you install voidbase, and nothing else.
The standalone executable. One file on a machine you own: a laptop, a server, a container. The server, the panel and the migrations are inside it, so nothing else is installed. It serves, it takes plugins, it moves data, and it cannot reach Cloudflare, because that toolchain is not in it.
The npm package. The same server on Bun, plus the toolchain. voidbase serve runs it here; voidbase serve --tunnel puts it on the internet through a Cloudflare quick tunnel for as long as it runs; voidbase serve --workers runs it on workerd, Cloudflare's own runtime, with a local D1, R2, queue and realtime hub, so what you exercise is the Workers code without a token or an account.
Your Cloudflare account. One Worker with a D1 database, an R2 bucket, a jobs queue and the Durable Object that fans out realtime, created in your account and owned by you. voidbase deploy from the npm package puts it there, and voidbase cloud does the same from a page, in your account rather than ours. With --database durable the data lives in its own SQLite-backed Durable Object instead of D1, and a batched write is a real transaction.
Choosing is never final. voidbase migrate moves an instance's data from any running instance to any other, in either direction, as a backup taken on one side and restored on the other, and it works from the executable as well as the package:
voidbase migrate http://127.0.0.1:8090 https://blog-api.example.workers.dev \
--from-email you@example.com --from-password ... --to-email you@example.com --to-password ...What decides the shape
Two questions, and the six guides are their answers. Where should it run, and is its definition in a repository yet.
Nothing tracked yet
You want a backend to exist so you can point something at it. The definition lives in the instance, you change it in the admin panel, and there is no repository. This is the right start for finding out whether voidbase suits you, and it is not a dead end: everything you build here moves.
The repository first
The hooks, the schema and the configuration are files you commit, and the instance is built out of them. A colleague can check the repository out and get the same backend, and a push can be the deploy.
Already running, and you want it tracked
The common case, because the first thing most people do is click around the admin panel. The collections you made there come out as a file, the file goes in a repository, and the instance carries on running while you do it.
What an instance is not
It is not your application. Your site, your app and your scripts are separate things that talk to it over the API, and the SDK is how. The one shape where that line moves is the stack, which puts a Void application and an instance in the same Worker on purpose.
It is also not shared. Every instance has its own database, its own files and its own address, and nothing is pooled between them. Two instances on the same Cloudflare account are named apart down to the rate-limit counters, and know nothing about each other.
Still deciding? Which one do I want? asks three questions and names the page.
Fix it yourself. The link below opens this file in GitHub's editor and forks the repository for you if you need one, and your change becomes a pull request without leaving the browser.