Implementing Human-in-the-Loop Workflows with Busabase

Busabase is an open-source database and workspace designed specifically for AI agents. It provides a structured environment where agents can store data, access knowledge, and execute skills. Crucially, it introduces a trust layer that allows humans to review agent-proposed changes before they are committed to the canonical workspace. By providing these as first-class nodes, it allows agents to interact with a consistent, addressable system of record, moving beyond the limitations of scattered chat logs and unstructured files.

Core Building Blocks

Busabase organizes information into building blocks that serve as the foundation for agent operations. These include Bases for structured records, field schemas, and relations; Docs for durable Markdown knowledge; Files and Drives for project artifacts; Skills for reusable instructions; and AirApps for purpose-built interfaces. Each building block is addressable by humans, agents, MCP, and OpenAPI, ensuring that agents operate within a defined, queryable context rather than a black box. Current node types include Folder, Base, Doc, File, Drive, Skill, AirApp, Form, HTML, Whiteboard, and Workflow.

The Trust Loop and Human-in-the-Loop Validation

The primary mechanism for validating agent work is the Change Request system. Agents are granted write access to the workspace, but their modifications do not immediately become canonical. Instead, the workflow follows a specific trust loop designed to separate working from becoming trusted:

• Contextual Reading: The agent reads the current workspace state to understand the task.
• Proposal: The agent proposes data, document, or skill changes based on its instructions.
• Review: These proposals arrive as Change Requests, which display the exact diff, source, and impact of the proposed change.
• Human Intervention: A human user inspects the request and chooses to approve, reject, or request further changes.
• Commit: Only upon approval does the work become part of the canonical workspace knowledge.

This process ensures that agent-generated output is subject to audit trails and human oversight, mitigating the risk of hallucinations or unintended data modifications. This review layer applies across the workspace, covering record updates, Doc edits, Skill files, schema changes, and AirApp packages.

Prerequisites and Setup

Busabase is designed to be local-first and self-hostable. To begin, users can run the server locally using the following command:

npx busabase server

This command initializes an embedded PGlite database and local file storage at ~/.busabase/data/. No external database or account is required for the local edition. For containerized environments, the following Docker command is supported:

docker run --rm -p 15419:15419 -v ~/.busabase/data:/data busabase/busabase

Users can also download the native desktop application for macOS, Windows, or Linux. The CLI server and Desktop share one default data root, and users can set BUSABASE_DATA_DIR, PG_DATABASE_URL, or STORAGE_URL to use alternative storage locations. Only one process can hold the same PGlite database at a time.

Connecting Agents

Busabase does not include a built-in AI model. Instead, it acts as a platform for existing agents such as Claude Code, Codex, Cursor, or custom processes. Agents can connect via several methods: Agent Skills for coding agents, MCP for tool-aware IDEs, OpenAPI/CLI for custom automations, and the Agents view for conversational sessions. To onboard an agent, users should provide the agent with the local onboarding prompt found in the workspace, which points to the SETUP_SKILL.md file at http://localhost:15419/SETUP_SKILL.md.

Limitations and Security

The open-source server is intended for use on a trusted local machine or within a private network. The documentation explicitly warns against exposing write endpoints directly to the public internet without authentication and a properly configured reverse proxy. Users should use scoped credentials and Cloud Connect when remote access is required.

Who Should Use Busabase

Busabase is suitable for developers and teams who require a structured, auditable environment for AI agents. It is particularly useful for maintaining team memory, managing CRM and research data, operating headless CMS content systems, and building dataset pipelines where human-reviewed evidence is required. By separating the act of working from the act of becoming trusted, Busabase provides a dependable framework for integrating AI agents into production-grade operational workflows.