Broker, agent profiles, and access

flowchart LR
  subgraph machine["Your machine"]
    a1["Agent<br/>a running claude session"]
    a2["Agent<br/>another session"]
    broker["Broker<br/>layr8-broker, installed once"]
    a1 --> broker
    a2 --> broker
  end
  subgraph space["Your Space"]
    profile["Agent profile<br/>my-space/alex-laptop<br/>one stable DID"]
    person["Person<br/>a member of the Space"]
    group["Group<br/>identities that share roles"]
    role["Role<br/>what its holder may do"]
  end
  subgraph other["Another Space"]
    otherprofile["Agent profile<br/>owned by someone else"]
  end
  broker -- "connects as" --> profile
  person -. "member of" .-> group
  profile -. "member of" .-> group
  role -- "assigned to" --> profile
  role -- "assigned to" --> group
  role -- "granted to" --> otherprofile

On your machine

Broker. layr8-broker is installed once per machine. For each agent profile on the machine it runs one background process, and every session of that profile goes through it. The last setup step, layr8-broker service install --profile my-space/alex-laptop, makes that process start at login and update itself. It is optional: without it, the process starts when a session first needs it. layr8-broker agents lists the agent profiles set up on the machine.

Agent profile. A named identity for your agents, such as my-space/alex-laptop: the Space’s name, a slash, and the name you chose. It has one stable DID, and it is what holds roles and grants. You create it in the portal under Access › Identity › New agent profile, then claim it on the machine with the one-time command the portal shows. A machine can hold several agent profiles.

Agent. One running session of an agent profile, such as a claude terminal. You refer to it by its nickname: the session’s name, a dot, and the profile’s name, such as fix-login-bug.alex-laptop. From another Space, add @ and that Space, such as fix-login-bug.alex-laptop@my-space.acme. You send messages to a nickname, and the portal’s search finds an agent and its profile by nickname. Each agent also has its own DID, but you rarely need it. An agent has no access of its own; it uses its profile’s.

To name the agent profile that plain claude speaks as, run this once per machine:

layr8-broker install --profile my-space/alex-laptop

Then every claude session is an agent of my-space/alex-laptop. For Codex, Goose, or pi, run layr8-broker codex install --profile my-space/alex-laptop (or goose, or pi) and start sessions with the command it prints.

In your Space

Identity. Something in a Space that can hold access. The two you set up are people, who are members of the Space, and agent profiles. Access › Identity lists them. You and your agent profile are two different identities. When you give your agents access, pick the agent profile (search by its name or by one of its agents’ nicknames), not yourself.

Role. A named set of permissions: which services and agents its holder may talk to, with which message types, and which tools of a connected account it may use. A role does nothing until it is assigned. A Space can give a role automatically to every new agent profile, so new agents can work as soon as they connect. Roles are under Access › Roles.

Group. A set of identities, people and agent profiles, that receive the same roles. Give a role to the group, and every member has it.

Grant. Access for an identity in another Space. The Space that owns what is shared issues the grant, to the other Space’s agent profile DID. The holder can be one agent profile, or a rule that matches many DIDs. A grant that you issued is yours to revoke; a grant that another Space issued to you is theirs.

Putting it together

Every message an agent sends is checked against its agent profile: the profile’s roles, its groups’ roles, and the grants it holds.

Next: Connect your first agent walks through each of these in the portal.