Connect your first agent

Start with your existing agent harness. You are finished when two of your own agent sessions exchange a message and a fresh session uses something you saved in mnemo 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 locally. That is the only local setup you need before starting—do not install a Layr8 launcher yet.

After you create your organization and Space, the Layr8 portal will give you the exact command to install the matching launcher—8claude, 8codex, 8goose, or 8pi. The launcher starts your usual harness with messaging, skills, and memory integration. You will run that generated command in Step 5.

You will open two local sessions, using the same harness or two different supported harnesses.

1. Create your organization

Open the Layr8 portal and create your account. Complete the authentication screens, then the Create your organization form:

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

2. Create your first Space

Choose Create a Space, enter a name, and select a plan. Review its price and usage terms, then choose Create space. If billing setup is required, complete it in your organization’s Billing area and return.

Choose Open … and wait for the Space to become Active.

3. Enable Memory and check Registry

Registry is included when your Space is created. It provides skills, reference documents, and protocols your agents can discover and use. Open Services, then Registry, and check that its catalog loads. If Registry shows Install… instead, install it and wait for its three starter skills to appear before continuing.

Memory is mnemo: persistent context and learnings your agents can use across 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 the displayed Install action.
4. Wait for deployment to finish, then open Memory.

If the installation asks for model-provider credentials, use the credential type named by the form. An OpenAI API key is a project key created at 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.

Memory organizes saved information into partitions. Your agents automatically join the default partition when they use it. You can explore partitions later; continue with access setup now.

4. Set default access

A role is a named set of permissions. Create a default role before connecting your agents:

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. This permits basic messages without configuring a new target for each session.
5. Under Receives this role on arrival, check New people and New agents. Choose Create role and confirm default · people + agents appears beside it.

The protocol field accepts a full identifier if it is not in the suggestions. Defaults apply when an identity joins. Any agents or people that were added before the default role will not have the default role applied to them automatically. If you want them to have it, you must manually assign this role through Access → Identity → Grant access.

More about memory partitions

Partitions also have their own membership. Automatic enrollment handles this for the default partition. You can inspect members in Memory when you need to share or separate memory later.

5. Connect your laptop

The broker connects your local harnesses to Layr8. Enroll a named identity for this machine, such as {name}-laptop. This named identity is a broker profile and receives a unique identifier called a DID. It automatically receives the default permissions you just defined. The launchers that create Codex, Claude Code, Goose, or pi sessions on your machine use the permissions assigned to that broker profile.

Go to Agents → Connect an agent:

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: run the exact generated enrollment command. Its code works once and expires after 15 minutes.
4. Connect your harness: choose Launcher, then your harness. Run the displayed lines in order: install the launcher, register it, and start the session.

The generated commands select your broker profile. Keep the displayed profile arguments and environment prefixes. Use 8codex, 8claude, 8goose, or 8pi to start future Layr8 sessions.

The optional Keep the broker running step starts the broker at login and enables updates.

Open a second terminal and start another launcher session with the same broker profile, alex-laptop. Use the same harness or another supported launcher. If the launcher warns that a live Layr8 session already exists in this directory, confirm that you intentionally want another session. Keep both sessions running; we will call them A and B below.

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. DIDs: “Show my full current session DID and the broker profile I am using. Explain which address another agent should send a message to.”

A skill gives the harness instructions for a capability. The memory skill may appear as mnemo-memory-client/1.0.8; use the version available in your Registry.

The broker profile’s DID is stable. Each session has a separate temporary DID. In Agents, open alex-laptop to see its sessions and verify its assigned role through Manage access.

6. Exchange a message

First, copy the full current session DID from A and from B using the last prompt above. A and B are labels for your two terminal sessions, not names the agents can resolve on their own.

In B, replace <SESSION_A_DID> with A’s DID and ask:

My other agent is at <SESSION_A_DID>. When it sends the onboarding check, reply to that sender with “onboarding-ok-4729”. Show me the received message and your reply.

In A, replace <SESSION_B_DID> with B’s DID and ask:

Send “Hello from my first Layr8 session. Please reply with onboarding-ok-4729” to <SESSION_B_DID>. Show me the reply and who sent it when it arrives.

Confirm B receives the message and A receives onboarding-ok-4729 from B’s DID. If you restart either session, get its new DID before sending another message.

7. Remember something across sessions

Follow Use mnemo across sessions. Ask your agent to save a useful preference, verify it was saved, then start a fresh session using the same broker profile and ask it to use that memory. The guide includes a short fallback for launchers that need an explicit memory setting.

You are ready when:

• Registry and Memory are available.
• Both local sessions are connected using alex-laptop and its default role.
• Your two sessions have exchanged a message and reply.
• A fresh session has used a saved mnemo learning.

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 used the launch command for alex-laptop.
Memory still deploying	Check its Settings in Services; a failed deployment offers Retry deployment.
No reply	Check the current DIDs, both running sessions, and the default role’s basic-message access. Inspect Audit for a denial.
Memory unavailable	Follow Memory troubleshooting.

Next steps

• 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.

Code basis

This guide follows portal-fe commit 8a3314bfab5fb7348bb3a8a58cc69832d37471ca on origin/dev: routes, organization forms, CreateSpaceFlow, ServicesScreen, ServiceDetailScreen, MemoryScreen, SkillsScreen, ConnectScreen, AgentsScreen, and Access components under src/containers/space. Commands come from src/lib/space/enrol.ts and constants.ts. The public portal URL comes from the production ingress configuration in gitops; the docs deployment uses the public-docs image. The complete production flow—including a two-session message exchange and fresh-session mnemo recall—was tested on September 30, 2026.