How to Use Busabase: The Beginner's Guide

How to Use Busabase: The Beginner's Guide

If you use AI coding agents every day, you already know the frustration: every session starts from zero. Your Claude Code beginner guide knows how to start one conversation, but it cannot stop the next conversation from forgetting everything. Your project conventions live in one repo, your best research dies in a chat window, and switching from one agent to another means explaining the whole project all over again. Learning how to use Busabase fixes exactly that problem.

Busabase (pronounced "boo-sah-bayss") is an open-source database and workspace that acts as the system of record for AI agents. Agents and people share the same typed records, documents, skills, and apps, and every write an agent makes travels as a change request with a field-level diff, an author, and a history. Connect any agent, and it reads the same workspace your team and your other agents already left behind — then writes its own work back, so nothing valuable ever dies in a chat again. One naming note before we start: Busabase is not Budibase, a different product with a similar name. Everything here is about Busabase, the agent system of record.

What Is Busabase, Exactly?

Busabase is an open-source database and workspace where AI agents and people keep the records, documents, skills, and apps that the next task builds on. Its core idea is simple: agents should be stateless, and the work should be durable. Instead of asking an agent to remember your project from a chat history, you keep the project itself in a shared base that every agent can read and write.

In practice, the workspace holds eight node types as first-class citizens: Bases (typed, related, queryable records with views and forms), Docs (durable documents with version history), Files and Drives, Skills (reusable instructions and supporting files), AirApps (small interfaces built on workspace data), Whiteboards, and Workflows. An agent does not memorize any of this. It looks it up when it needs it, acts, and writes its output back with a diff that a human can review.

That design makes it different from the tools you already have. Airtable, Notion, Baserow, and NocoDB are built for people editing directly, and they lack agent-native access, shared skills, and a proposal boundary for agent writes. Postgres stores data for applications but gives you no workspace UI, no knowledge model, no review loop, and no provenance. Agent memory and vector databases help one agent recall context but give you no structured facts that a person can open, cite, and correct. Busabase is the workspace layer on top of all of that — people and agents building one shared base together.

How Do You Set Up Your First Busabase Workspace?

You can have a working workspace in under two minutes, with no database to install, no account to create, and no configuration to write. Follow these steps in order.

1. Start the server. Run npx -y busabase@latest server in your terminal. It boots with an embedded PGlite database, local file storage, and a demo workspace already inside.
2. Open the dashboard. Visit http://localhost:15419/dashboard/local in your browser. This is your workspace home: the review queue, recently visited knowledge, and agent activity.
3. Connect your first agent. Paste this prompt into Claude Code, Codex, Cursor, Gemini CLI, or any agent that can read a URL: "Read and follow the Busabase Agent Skill — it is the single source of truth: http://localhost:15419/SETUP_SKILL.md. Follow its onboarding to connect to this workspace. Don't choose a merge policy yourself unless I ask for one — submit the change and let Busabase apply my permissions to decide whether it merges now or waits for review."
4. Let the agent finish onboarding. The skill is a guided first-run document. It walks the agent through connecting to the workspace, initializing starter data if the space is brand new, and verifying that starter records read back correctly. Stay out of its way.
5. Verify with the "what changed" test. Ask one agent to record a project's updates and conventions in the workspace. Then open a completely different agent and ask, "What changed on this project this week?" It answers from the workspace, not from your clipboard. When that works, your system of record is live.

The demo workspace is there to be explored, not worshipped. Open a Base, look at a record's history tab, open the Inbox, and let one agent propose a change so you can see what a change request looks like before your real data depends on it.

How Do Agents Connect to Busabase?

Agents connect to Busabase through five paths, and each one fits a different kind of agent. Pick the row that matches how you work.

There is no built-in model and no lock-in: the workspace does not care which agent wrote the data. A record written by Claude Code can be read by Cursor tomorrow and edited by your own script next week, and the history will show exactly who did what. Workflow builders get the same treatment — our n8n beginner guide pairs well here if your agents also need scheduled and triggered automations.

How Do Busabase Change Requests Work?

Every write an agent makes travels as a change request — a small package with a message, a field-level diff, an author, and a full history. Nothing lands silently, and nothing is a mystery later.

Here is the lifecycle. The agent reads the workspace context, then writes data, documents, skills, or app changes — always as a change request. Your permissions then decide what happens next: if the agent's credential has write access, the change merges on the spot and you get the materialized object back; if not, the change waits in the Inbox for a person to review. Either way, the change stays inspectable, attributable, and reversible. Review it from the workspace or from the mobile app, which has its own inbox for change requests.

Three details matter for beginners. First, a credential capped at the change-request level can only propose — it can never merge its own writes, which is how you safely connect an experimental agent. Second, a single call can opt in with autoMerge: false, so the server never decides for you. Third, busabase-cli install … --require-review holds a whole package's content back for approval, which is the safe way to try community templates.

Over time, the history tab on every record becomes the real product: the source, the reviewer, the commit, and the timeline of everything that changed, in one place. If your team already thinks in terms of Git beginner guide concepts, change requests will feel familiar — proposals, diffs, review, merge — just applied to your agents' output instead of your code.

What Goes Into the Shared Skills Catalog?

Skills are the reusable instructions and supporting files that teach your agents how your world works, and Playbooks collects them into one catalog that every connected agent can look up before it acts. This is the piece most beginners underestimate.

Think of a skill as a SKILL.md playbook: "how we write release notes," "how we triage a support ticket," "the checks to run before touching the payments table." Without a shared catalog, each agent session invents its own conventions or drags them from a scattered set of chat logs. With Busabase, the playbook lives in the workspace, versioned and reviewable, and every connected agent — no matter which one — looks it up before it acts. That is the "busabase tutorial" moment that turns a toy workspace into infrastructure: your agents stop being brilliant amnesiacs and start being reliable colleagues with a shared memory.

Seed the catalog with three skills on day one: your project's conventions, your review policy for agent writes, and your definition of "done" for the work your agents do most. Three is enough to feel the difference; you will add more the first time an agent does something the way you would have done it.

How Do You Self-Host Busabase?

Self-hosting Busabase is one of its headline features: the engine is MIT-licensed and free forever when you run it yourself, with no seat count and no expiry, and your data never leaves your machine. You have four install paths, from lightest to heaviest.

• Local server (easiest): npx -y busabase@latest server — the same command from the quickstart, good for one person on one machine.
• Desktop app: download the Busabase Desktop from busabase.com/download for macOS, Windows, or Linux. It keeps data local and works fully offline.
• Docker: docker run --rm -p 15419:15419 -v ~/.busabase/data:/data busabase/busabase — images on Docker Hub (busabase/busabase) and GHCR (ghcr.io/busabase/busabase). If this syntax is new, our Docker beginner guide covers containers from zero.
• From source: pnpm install, then cp apps/busabase/.env.example apps/busabase/.env, then pnpm --filter busabase dev — for contributors who want to read or change the engine itself.

Local data lives in ~/.busabase/data/ — pgdata/ for the embedded PGlite database and storage/ for files. Point BUSABASE_DATA_DIR, PG_DATABASE_URL, or STORAGE_URL at another location, an external Postgres, or S3-compatible storage when you outgrow the defaults. One warning from the vendor: only one process can hold the same PGlite database at a time, so do not run two servers against the same data directory.

The open-source server is designed for a trusted local machine or a private network. Do not expose the write endpoints to the public internet without authentication and a reverse proxy; use scoped credentials and the Cloud Connect tunnel for remote access instead. Treat the local server like you would treat any database with no password on it: convenient at home, dangerous on the open web.

Busabase vs Notion for AI Agents: Which One Fits?

If your team already keeps everything in Notion, this is the comparison that matters. Notion is a fine place for people to write; Busabase is built for agents to read and write with guardrails. Here is how to decide.

The honest answer is that they overlap least where it matters most. Notion remains a good home for long-form human writing. Busabase is for the structured, agent-produced work — records, datasets, skills, change-tracked decisions — that dies when it lives only in a chat. Many teams will end up with both: Notion for the prose, Busabase for the machine-readable memory.

What Does Busabase Cost?

Busabase is free to start and stays free for a single person's real use. The engine is MIT-licensed and free forever, whether you run it yourself or the vendor runs it for you. Paid plans start where teams do.

Busabase Cloud's free tier covers one space you own, 3 seats per space, 5,000 records per space, 20 nodes per space, 1 GB of attachment storage (files up to 10 MB each), one self-hosted connection online, all node types including skills, workflows, and AirApps, and the OpenAPI, webhooks, and MCP interfaces — flat per seat, with no metered usage. Plus is $10 per seat per month ($120 billed annually) for 3 owned spaces, 10 seats, 50,000 records, 200 nodes, and 20 GB of storage; Pro is $20 per seat per month with unlimited spaces, seats, records, and nodes plus 100 GB of storage and priority support; Enterprise is custom with SSO/SAML, audit log export, multi-stage review workflows, and an SLA.

One pricing detail is worth knowing: there is no metered overage billing. When a quota is reached, the action that would exceed it is paused and you see an upgrade prompt — your existing data stays readable, and you are never charged automatically. For a tool built around agent automation, that cap is a feature, not a limitation.

7 Beginner Mistakes to Avoid With Busabase

Every beginner hits at least one of these. Read the table first and skip the debugging.

Sources

1. Busabase package documentation, npm.io (package published 2026-06-27; page updated 2026-10-30) — quickstart, install paths, change-request lifecycle, node types, and the vendor comparison table.
2. Busabase pricing page, busabase.com/pricing (fetched 2026-11-03) — free-tier limits (5,000 records, 20 nodes, 1 GB storage), Plus $10/seat/mo, Pro $20/seat/mo, and the no-metered-overage policy.
3. Busabase launch thread on Product Hunt (updated 2026-11-02) — the maker's "agents should be stateless" thesis, the mid-October 2026 launch (341 upvotes per the Oct-15 intelligenttools roundup), and the Cloud/Desktop/self-host options.
4. Busabase Python SDK page, PyPI (crawled 2026-10-28) — the official Python client for the REST API: change-request writes, typed models, and Cloud vs self-hosted endpoints.
5. Busabase community Q&A, community.busabase.com (crawled 2026-11-03) — day-to-day modeling patterns, e.g. exception logging and pricing-tier records.

Frequently Asked Questions

Is Busabase really free?

Yes for the ways most beginners use it. The engine is MIT-licensed and free forever when you self-host it — no seat count, no expiry. Busabase Cloud also has a free tier: one owned space, 3 seats, 5,000 records, 20 nodes, and 1 GB of attachment storage, with all node types and the OpenAPI, webhook, and MCP interfaces included. Paid plans start at $10 per seat per month.

How is Busabase different from Budibase?

They are different products that happen to have similar names. Busabase is the open-source system of record for AI agents — typed records, change requests, and a shared skills catalog. Budibase is a separate low-code app builder. If you are following this guide, you want Busabase (busabase.com), pronounced "boo-sah-bayss."

Which agents can I connect to Busabase?

Any agent that can follow an Agent Skill, speak MCP, or call a REST API. The vendor lists Claude Code, Codex, Cursor, Gemini CLI, OpenCode, OpenClaw, Hermes, Buda AI, and n8n among the compatible agents, plus your own custom processes through the CLI, SDKs, or an ACP chat session.

Do I need to know databases to use Busabase?

No. The quickstart — npx -y busabase@latest server, then open the local dashboard — needs no database, no account, and no configuration, because the server ships with an embedded PGlite database. You design Bases (tables) visually like a spreadsheet, and agents handle the querying. Knowing what a record and a field are is enough to start.

What happens when an agent writes something wrong?

It lands as a change request, not a direct edit — a message with a field-level diff, an author, and a history. Your permissions decide whether it merges immediately or waits in the Inbox for your review. You can approve, reject, or comment from the dashboard or the mobile app, and the full audit trail stays on the record either way.