Deian Isac
Back to the archive

Takibi Base on Orgo.ai: one library, one box, a CLI between them

Takibi holds the knowledge, one Orgo box does the work, and the takibi CLI is the only bridge between them. The exact setup, as it runs today.

Deian Isac

My agents needed a computer they could share. Takibi already held the knowledge, and I did not want the box keeping its own copy of the truth.

So the split is plain: Takibi Base is the agent-first knowledge base, where I curate projects, folders, and uploads, and every agent reads through scoped keys. They get verbatim spans with citations plus a support score, never generated prose.

Orgo.ai provides the one always-on box they all work on, with workspaces organizing computers and controlling access. Knowledge lives in Takibi, hands live on the Orgo box, and the takibi CLI is the only bridge between them.

This is the exact setup, as it runs today.

The shape

The Takibi API serves /v1/* plus the web app, backed by managed Postgres and private object storage. Agents never touch it directly. No hand-rolled curl.

The box holds the takibi CLI (takibibase on npm, currently 1.11.0), a key file, and the takibi-use skill where the agent harness looks. It also runs the rest of the crew’s plumbing: takibi-dispatcher under supervisor, the Herdr server and client, and Tailscale.

Brand files and fixtures the crew needs on disk get pushed from my checkout to one exact folder on the box with a small local helper, then verified by checksum.

From zero to verified

In Orgo I create a workspace, then a computer inside it. I need two IDs: the workspace ID and the computer ID. The API calls that one desktopId.

GET /workspaces lists them. Each workspace embeds its computers under desktops. I copy both IDs and use them for every upload. Workspaces can hold similarly named computers, so I pin IDs in automation. Not names. I do the same for reviewer routing in the dispatcher. It pins the profile UUID. A display-name mismatch (gobofu-os vs goBOFU OS) once silently misrouted every finished card.

Secrets stay out of the repo. The root has a gitignored .env.local. Mine looks like this, values redacted:

ORGO_API_KEY=sk_live_...
ORGO_WORKSPACE_ID=<workspace uuid>
ORGO_COMPUTER_ID=<computer uuid>

Three rules I do not bend. The Orgo key is never printed, never pasted in chat, never committed. Same for Takibi keys.

The CLI is a single zero-dependency file, Node 22+. On the Orgo computer:

npm i -g takibibase

That lands takibi on PATH. Mine lives at /usr/bin/takibi. For a quick test, npx takibibase … runs the latest release with zero install.

Then three one-time steps on the box, in this order.

First, mint a scoped key. In the Takibi app I go to Settings, Profiles, and make a new Profile with exactly the capabilities the crew needs. That is search, ask, tasks, plus task:create for authors, task:assign for orchestrators, notes caps for observers, and Uploads for pipelines that file documents. It stays scoped to its projects. Task boards need a whole-collection grant. Folder-only seats cannot use them. I copy the <publicId>.<secret> shown once.

Then I save it on the box:

mkdir -p ~/.takibi \
  && printf '%s\n' '<publicId>.<secret>' > ~/.takibi/key \
  && chmod 600 ~/.takibi/key

A symlink works too: mine points at the dispatcher’s key file.

Base URL needs no config in production. The default is already Takibi’s servers (https://app.takibibase.com). Only local setups write one URL line to ~/.takibi/config or set $TAKIBI_BASE_URL.

Then the skill, so any harness on the box knows the contract:

takibi skill --install

That drops takibi-use into the detected skills dirs (.agents, .claude, .codex). --force overwrites on refresh. --dir overrides the target. Zero-install alternative: takibi skill prints the skill text, and I paste it into the agent’s first prompt.

Then I verify. Thirty seconds, from the box:

takibi version    # needs no key; shows API version + Jev status
takibi projects   # lists what this key can reach, straight from the API

version proves the API is reachable. projects proves the key works and shows its grants. If a command says the key is missing, I stop. I do not improvise. I fix the key file.

A fresh agent follows the same discovery flow: projects, then folders (names to UUIDs for --folder), then scoped ask, search, doc list.

Sync that verifies

The helper lives at tools/orgo-upload/upload.mjs. Local only, gitignored. My wiring, not the product. It pushes a local folder to the Orgo computer and preserves relative paths. It calls POST /files/upload with workspaceId, desktopId, and destPath to target the folder. Files land in one exact folder on one computer. Then it verifies with remote md5s.

# Upload + verify
node tools/orgo-upload/upload.mjs \
  --src /path/to/local-folder \
  --dest /root/takibi-assets/some-folder

# Check what's in sync without uploading
node tools/orgo-upload/upload.mjs \
  --src /path/to/local-folder \
  --dest /root/takibi-assets/some-folder \
  --verify-only

Auth and IDs resolve from the environment first, then root .env.local. --workspace and --computer override per run. I pass them explicitly in scripts.

Behavior worth knowing. Destination folders are created with mkdir -p first, because the API does not promise to create destPath. --dest must be absolute. The helper enforces it.

There is a 10 MB per-file cap. Orgo API limit. Larger files are reported, not sent. .DS_Store files are skipped.

Verification shells out over POST /computers/:id/bash and runs md5sum remotely, then compares against local hashes. Mismatches and missing files fail the run. Files that exist on the computer but not locally are left alone. Sync is additive. Never destructive.

The daily loop

Always the CLI, never curl against /v1/*. The CLI already bakes in the auth shape, the q param, project resolution, and error hints. The daily loop:

takibi ask -q "…"        # verbatim spans + citations + support line
takibi search -q "…"     # ranked chunks, snippets + metadata
takibi tasks list        # claim a card before moving it
takibi doc list          # metadata, then `doc text` for converted text
takibi notes append --problem "…" --tried "…" --worked "…" --failed "…" --next-time "…"
takibi notes search -q "…"   # top-2 agent notes before retrying something odd

Reads are free. Task writes, notes export/keep/remove, and doc uploads need my approval in conversation. Account-only routes stay with me: delete, retry, download originals, project edits. The CLI says so and the server 401s.

Two semantics saved me debugging time.

abstained: true is exit 0, not an error. No answer in the evidence means I broaden q, fall back to search, try doc text on the hits. Then I either answer from evidence or say it is not there. Gaps never get filled with generated prose presented as sourced.

Jev-down is not app-down. If the retrieval brain is unreachable, /ask still answers with degraded fields (answerability: unknown) and search is unaffected. I check takibi version before assuming the app is down.

Upgrades need no restart. When a new takibibase drops, the CLI nudges on stderr once a day when behind. Never on --json.

npm i -g takibibase
takibi skill --install --force
takibi projects   # sanity: grants still resolve

My last bump, 1.8.0 to 1.11.0, needed no dispatcher restart. The CLI is shelled per call, so the new version is live the moment npm finishes. That no-restart rule covers the CLI only. Dispatcher code changes still need supervisorctl restart takibi-dispatcher. Only its JSON config reloads per job.

Gotchas and why this holds

Boards need whole-collection grants. A folder-only key 403s on every task route. If tasks fail but ask works, I check the grant, not the network.

Notes are opt-in per profile. Appends and exports can 403 with missing-capability on keys without the notes caps. I enable them in the Profile editor.

The secret filter bites. 422 SECRET_BLOCKED on notes or task bodies means I strip keys, tokens, and credentials and retry. The filter covers task title, body, blocked reason, and artifact text too.

Support is not confidence. I report the support number as-is. I never upgrade it into certainty. I honor answerability and surface both sides on conflict: yes.

One Takibi replica holds the knowledge, and every agent works on the one shared Orgo box. Every answer carries its evidence.

Setup cost is a key file and a skill install on the box. After setup, I run additive syncs, compare checksums, and upgrade the CLI without restarting it.

If you are building the same thing, start with takibi version and takibi projects on the box. Everything after that is just scope.

Links: takibibase.com · agent docs · takibibase on npm · orgo.ai