How Barry works
Barry is a set of long-running services on your Mac, a store for each bag, and a policy that holds every session. This page follows the system from the files on disk to a running session. For the commands that act on each piece, see the command reference.
Resident services
Section titled “Resident services”Barry installs its services as launchd jobs, so they start at login and stay
running. barry up starts the enabled ones, barry down stops them, and
barry status shows what is running, its port, and its health.
Each bag that ships a service runs as its own process: the MCP server that
serves tools to a harness (mcp.server), the sessions API (sessions.api),
the identities service (identities.identities), the scheduler
(schedules.scheduler), the durable workflow runtime (workflows.runtime),
and more. barry service lists them and controls them one at a time.
The vault is the deliberate exception. It runs under its own operating-system
user, which is why you set it up separately with sudo barry setup --system.
That account protects the vault’s store and its code from tampering. It
doesn’t hide secrets from processes running as you: they can still reach the
vault’s API, and the vault’s credentials sit in your login Keychain.
Security model covers where that boundary
stops.
A store for each bag
Section titled “A store for each bag”State lives in SQLite. Each bag gets its own database, and barry store list
shows them with their size, write-ahead-log status, and migration version.
Stores carry a scope: some belong to the whole machine, and some belong to a
single identity, so one identity’s sessions and memories do not mix with
another’s.
Barry applies a store’s pending migrations when it opens the database, inside
a single transaction, so starting several services at once is safe. A store
stamped by a newer build than the one running refuses to open rather than risk
corrupting it; that is the signal to run barry upgrade. You can snapshot and
roll back the whole set with barry db.
Credentials, no address trust
Section titled “Credentials, no address trust”The services talk over local HTTP, and every call carries a credential. The
instance secret (BARRY_SECRET) carries full owner authority: a request
presents it as a bearer token or an x-barry-secret header, Barry compares it
in constant time, and a request without a valid credential gets a 401. The
command-line tool, the harness, Barry’s hooks, and a bag’s own code all reach
the services this way. Rotating the secret takes effect on the next request.
Narrower credentials open narrower paths. A paired device carries scopes, a
workflow session carries its own credential, and a linked worker’s credential
opens one route. No address earns trust on its own, not even 127.0.0.1. The
vault, again, runs under its own user with its own tokens.
From an identity file to a policy
Section titled “From an identity file to a policy”When a session starts, Barry resolves one effective policy and holds the session to it at four enforcement points.
Resolution comes first. The identity’s packed bags, the traits the session selected, and every bound in play (from the identity, the session, and any trait that carries one) merge into a single policy. Traits only add; bounds only remove; denials win. The enforcement points then hold the session to that policy:
- The MCP tool filter. The MCP server lists only the tools the policy grants. Barry never offers the model a tool no trait granted, so the model can’t call it.
- The call-time guards. When a granted tool runs, Barry checks it against the bounds: file patterns, the shell-command classifier, and network rules.
- The native ceiling and hook gate. For a harness’s own built-in tools, Barry requests the denials the harness can honor, and a per-call ruling or Barry hook gates calls where the mode supports one.
- The egress sandbox. Where the harness and mode support it, an optional proxy filters outbound traffic by hostname so the agent can’t lift it.
Bounds documents exactly what each enforcement point covers on each harness, including where a native tool stays reachable.
The session lifecycle
Section titled “The session lifecycle”A session is a persona running a harness under a policy. You start one with
<identity> session start, which resolves the policy, launches the harness
with Barry’s tools and hooks attached, and records the session. You can leave
and pick it up later with <identity> session resume or name it so you can
find it again. To run one without a terminal on any harness, start it with
<identity> session start --prompt "<prompt>" --no-ui.
<identity> session prompt also runs a prompt non-interactively, but always
through the Claude Agent SDK, whatever the identity’s harness. Barry can
also track a session you started in another tool, such as Cursor, through
<identity> track. Run sessions covers each of these.
Work that runs without you
Section titled “Work that runs without you”Not every job needs you watching. An action is a procedure with typed inputs and a model of its own. A schedule fires an action on a trigger, and the durable workflow runtime backs every run: it commits state, history, and timers together, so a run survives a restart and Barry retries a crashed step. When your own machine is busy, you link another as a worker and Barry runs eligible jobs there, retrying elsewhere if that worker dies.
Install it with Build a Barry.