Connect External Agents

BuildOS exposes a JSON-RPC gateway so external agents — Claude Code, OpenClaw, or anything you build yourself — can read and write in your projects the same way the in-app agent does. This replaces the old copy-and-paste-your-context workflow with a live, scoped connection.

Why you’d want this

The in-app agent is where BuildOS does most of its work. But a lot of serious work happens outside BuildOS — in Claude Code when you’re coding, in Claude Desktop when you’re drafting, in your own tooling when you’re automating. The gateway gives those tools the same view of your projects and the same ability to act on them, with permissions you actually control.

The difference is a snapshot versus an account. With the gateway, your external agent can read the current state of a project, write a new task, update a document, and see the result reflected back in BuildOS on the next view.

Generate an agent key

1. Go to /profile and open the Agent Keys tab.
2. Click Generate.
3. Pick a scope:
   • read_only — reads only, no writes.
   • read_write — reads plus the writes you whitelist.
4. Choose which projects the key can see — all of them or an explicit list.
5. If you picked read_write, whitelist the specific write ops.
6. Copy the connection prompt. The one-time secret shows only once; BuildOS stores a prefix for identification and never the full key.
7. Paste into Claude Code or OpenClaw. Done.

/integrations has the same flow plus per-agent setup notes.

What you can scope

Control	What it does
Mode	read_only blocks every write op. read_write allows the ones you whitelist.
Project scope	All projects or an explicit allowlist. Keys can’t reach projects outside the list.
Write op whitelist	Per-op toggle for every mutation the gateway exposes.
Audit trail	Every call is logged with the key prefix, the op, and the entity touched.

Permission bundles

The Agent Keys UI leads with preset bundles. Pick one and you’re done — the per-op matrix sits behind an Advanced permissions disclosure if you need finer control.

Bundle	What it grants
Read only	Every read op. No writes.
Author docs + tasks (OpenClaw default)	Reads plus onto.document.create/update and onto.task.create/update.
Full read/write	Reads plus every write op the gateway currently exposes.
Custom	Any per-op combination you pick in Advanced.

Existing OpenClaw keys that still carry the old narrow default (task writes only) auto-upgrade to Author docs + tasks on the next call — no action needed.

What’s exposed

Reads (available on every key)

• onto.project.list, onto.project.search, onto.project.get
• onto.task.list, onto.task.search, onto.task.get
• onto.document.list, onto.document.search, onto.document.get
• onto.search

Writes (require read_write)

• onto.task.create, onto.task.update
• onto.document.create, onto.document.update
• onto.project.create, onto.project.update (coming soon — registered but not yet wired)
• onto.goal.create, onto.goal.update (coming soon)
• onto.plan.create, onto.plan.update (coming soon)
• onto.milestone.create, onto.milestone.update (coming soon)
• onto.risk.create, onto.risk.update (coming soon)

Discovery

• skill_load, tool_search, tool_schema

Session methods

• call.dial, tools/list, tools/call, call.hangup

Saving a markdown document from an external agent

The headline v1 write op is onto.document.create. An external agent (Claude Code, OpenClaw, custom) can save a markdown artifact into a specific project in a single call.

{
	"method": "tools/call",
	"params": {
		"call_id": "<your call id>",
		"name": "onto.document.create",
		"arguments": {
			"project_id": "<project uuid>",
			"title": "Research: creator distribution loops",
			"content": "# Research\n\nFull markdown body here...",
			"description": "Initial pass on distribution tactics",
			"state_key": "draft",
			"idempotency_key": "openclaw:<project>:research-creator-distribution-loops:2026-04-18"
		}
	}
}

Notes:

• Content is stored as-is. No H1/H2 tree parsing; the markdown you send is the markdown we save.
• Content cap is 200 KB per document. Larger bodies return VALIDATION_ERROR.
• body_markdown is accepted as a legacy alias for content on create and update.
• onto.document.update defaults to replace. It also accepts update_strategy: "append" and update_strategy: "merge_llm"; on the external gateway, merge_llm gracefully falls back to append when no merge worker is available.
• parent_document_id is optional; omit it to land at the project root.
• parent_id is also accepted as a legacy alias on the external gateway when a model uses the internal create_onto_document naming.
• position is optional on create for sibling ordering within the project document tree.
• Documents created through the gateway are tagged with props.origin = "external_agent" for auditability.

One-click bootstrap

When you generate a key in the UI, BuildOS also produces a bootstrap URL:

GET /api/agent-call/bootstrap/<setupToken>

That endpoint returns the environment variables and a ready-to-paste prompt for Claude Code or OpenClaw, so you don’t have to wire up the JSON-RPC client by hand.

Custom agents

If you’re building your own client, point it at:

POST https://build-os.com/api/agent-call/buildos
Authorization: Bearer <your agent key>
Content-Type: application/json

Payload is JSON-RPC. Start with call.dial, list your tools with tools/list, call them via tools/call, and close with call.hangup. Types live in packages/shared-types/src/agent-call.types.ts.

Roadmap

• onto.document.create / onto.document.update — shipped. External agents can author markdown documents directly into projects.
• onto.project.create / onto.project.update — registered, wiring in progress. Will let agents spin up projects before writing docs/tasks.
• Goals, plans, milestones, risks — registered, wiring in progress. Rounds out the write surface so anything the internal agent can do is also available through the gateway.

Design doc: apps/web/docs/features/agent-call/MULTI_SURFACE_CONTENT_IDEA_WORKFLOW.md.

Next

• Reference & Help
• Integrations — per-agent setup walk-throughs.