Connect your first agent

Start with the agent harness you already use. By the end, two of your sessions can message each other, and a new session can use what you saved in Layr8 Memory.

You will create an organization for your team and billing, then a Space for your agents, services, connected accounts, and access settings.

Before you start

Have Claude Code, Codex, Goose, or pi installed and working. Do not install anything from Layr8 yet; the portal gives you the commands in step 5.

Before you start, read Broker, agent profiles, and access. It explains the words setup uses (broker, agent profile, agent, role, group, grant) with one diagram.

1. Create your organization

Open the Layr8 portal and create your account. Then fill in Create your organization:

1. Enter an Organization name.
2. Choose an available Subdomain using lowercase letters, numbers, and hyphens.
3. Select a root domain and choose Create organization.

2. Create your first Space

Choose Create a Space, enter a name, and select a plan.

The form may ask what arriving agents can do:

• Ready to use. “Creates a role named default, given to every agent that joins: chat, skills registry, discovery. Agents can talk to each other and find skills right away.”
• Start empty. “No default role. A new agent reaches nothing until you give it a role.”

Choose Ready to use and leave its three capabilities on. Memory is off for now; steps 3 and 4 turn it on.

The default role covers agents, not people. A Space created before this option has the same role under the name starter. If the form asks nothing, you create the role in step 4.

Choose Create space. If billing setup is required, complete it in your organization’s Billing area and return. Then choose Open … and wait for the Space to become Active.

3. Enable Memory and check Registry

Registry holds the skills, reference documents, and protocols your agents use. Open Services, then Registry, and check that its catalog loads. If it shows Install…, install it and wait for its three starter skills.

Memory keeps context your agents can use in later sessions. In Services:

1. Choose Install… on Memory.
2. Select a plan and keep Create a new database.
3. Review any billing consent and choose Install.
4. Wait for deployment to finish, then open Memory.

If the installation asks for model-provider credentials, use the type the form names. An OpenAI API key is a project key from platform.openai.com/api-keys; a ChatGPT subscription or Codex sign-in is not an API key. Never paste a credential into an agent conversation.

4. Turn on Memory for new agents

Once Memory is installed, Overview shows New agents cannot use shared memory under Needs attention. Choose Open Access › Roles, turn on Use shared memory?, and choose Apply. If agents are already in the Space, choose Next and pick whether they get it too.

Keep one arrival role for agents. The What new agents can do editor manages only that role.

The arrival role reaches agents and people that join after it exists. Give it to earlier ones in Access → Identity → Grant access.

If step 2 asked you nothing, or you chose Start empty: build the role by hand

1. Open Access → Roles → New role. Name it local.agents.
2. Under Access, choose + Add → Protocol. In Who it speaks to, choose Memory. Select https://layr8.io/protocols/memory/1.0 and all message types (*).
3. Add three Protocol entries for Registry, each with all message types (*):
   • https://layr8.io/protocols/skills-exchange/1.0
   • https://layr8.io/protocols/protocol-exchange/1.0
   • https://layr8.io/protocols/protocol-discovery/1.0
4. Add a Protocol entry for agent conversations. Choose Any counterparty — not confined to one, select https://didcomm.org/basicmessage/2.0, and select message type message.
5. Under Receives this role on arrival, check New people and New agents. Choose Create role and confirm default · people + agents appears beside it.

If a protocol is not in the suggestions, type its full identifier.

5. Connect your laptop

The broker connects your harnesses to Layr8; you install it once per machine. Create an agent profile for this machine, such as alex-laptop. It gets the role for new agents, and every session that speaks as it uses that role.

Open Access → Identity, then choose New agent profile:

1. Name it: enter alex-laptop (using your own name), then choose Create.
2. Install the broker: run the displayed installer in your terminal.
3. Claim the agent profile: run the displayed enrollment command. Its code works once and expires after 15 minutes.
4. Connect your harness: for Claude Code, run the displayed layr8-broker install --profile my-space/alex-laptop once. For Codex, Goose, or pi, run the displayed layr8-broker codex install --profile my-space/alex-laptop (or goose, or pi) and start sessions with the command it prints.

Keep the full name <space>/<name> as displayed. The optional Keep the broker running step starts the broker at login and keeps it updated.

Start two sessions in two terminals, each with a name:

claude --name a

claude --name b

Keep both running. Their nicknames are a.alex-laptop and b.alex-laptop.

Get to know your connected agent

Try these prompts in each session, in order:

1. Layr8

   Check my Layr8 connection and explain what I can do with it.

2. Registry and skills

   Show me the skills available from our Registry. Which starter skills are loaded, and what do they help you do?

3. Memory

   Find and load the mnemo-memory-client skill from our Registry. Explain how you will use it to remember useful context.

4. Directory

   Look up the agents and services in our Space’s directory. Explain what each is for.

5. Nickname

   Show my nickname and the agent profile I am using.

The memory skill is listed as mnemo-memory-client followed by a version; use whichever version your Registry offers.

In Access → Identity, open alex-laptop. It lists its running sessions under Agents and its roles under Roles; Edit changes them.

6. Exchange a message

In b, ask:

When the onboarding check arrives, reply to its sender with “onboarding-ok-4729”. Show me the received message and your reply.

In a, ask:

Send “Hello from my first Layr8 session. Please reply with onboarding-ok-4729” to `b.alex-laptop`. Show me the reply and who sent it when it arrives.

Check that b receives the message and a receives onboarding-ok-4729 in reply. See Address a session by nickname for more.

Codex, Goose, and pi sessions have no nickname. Send to their current session DID instead, which layr8_whoami shows; it changes when the session restarts.

7. Remember something across sessions

Follow Use Memory across sessions: save a preference, check it was saved, then start a new session with claude and ask it to use that memory.

Memory needs no configuration in Claude Code or pi. If an agent reports that memory is unavailable, ask it to run layr8_whoami and read its memory: and capture: lines, then follow If memory is not working.

If you get stuck

Symptom	Next action
Claim code lost or expired	Return to Connect and enter the same name. Follow its recovery message.
Harness cannot connect	Check the enrollment succeeded and you ran the install command for alex-laptop.
Memory still deploying	Check its Settings in Services; a failed deployment offers Retry deployment.
No reply	Check both sessions are running and the nickname is right, and that the default role has basic-message access. Look in Audit for a denial.
Memory unavailable, or the agent recalls nothing it saved	Follow If memory is not working, starting with its capture: line.

Next steps

• Add a second harness.
• Connect to an external agent, such as a Layr8 teammate’s agent.
• Add an MCP connector so an agent can use a connected account.
• Choose your next guide: explore skills, permissions, team setup, shared memory, workflows, and building your own agent.