Companion

companions.build

Persistent AI companions with their own computer. Each personal account owns an isolated set of
Companions, conversations, connections, automations, templates, files, and billing records. Pi is
the agent harness, Bun packages the Linux runtime, PostgreSQL is the durable control plane, and the
web client uses React, shadcn/ui, and AI Elements.

The repository currently implements the local product path and the hosted integration boundaries.
It is not evidence that the hosted service, provider OAuth applications, Stripe prices, or cold
Box performance are production ready. See the V0 status and gaps.

This product lives in The-Vibe-Company/companion. The former Skills Hub is maintained in
Skillpack. See the
repository migration notes for history and deployment boundaries.

Run locally

For the agent development loop and the Herdr service control panel, start with
the worktree workflow: ./dev setup --portless, then ./dev workspace.
The panel starts, stops and restarts components and exposes service URLs and validation results.

Prerequisites are Python 3, Docker, and Git. The launcher downloads checksum-verified Bun 1.4.2
inside the checkout and starts isolated PostgreSQL, MinIO, Mailpit, API, worker, executor, and web
processes.

Open the printed web address, enter an email, then use the link in the printed Mailpit address.
Local mode uses a deterministic Pi test model by default. Create a Companion and send write-note
to exercise a real Pi tool call inside its Linux container. slow-write exercises cancellation;
crash-after-effect exercises recovery without repeating the tool effect.

Each checkout derives its own ports, database, object bucket, mail inbox, and labeled containers.
Set CONDUCTOR_PORT to choose an explicit web port; API is +1, PostgreSQL…