OpenLore team setup guide

Share one set of docs, skills and context across your team’s agents. A step-by-step guide for teams using Claude Code, Codex and ChatGPT.

By the end of this guide you will have:

• A shared OpenLore server your team’s agents connect to.
• Two agents reading and writing the same files.
• One skill shared across the team, maintained from a single source.
• Server-enforced permissions, conflict checks and file-size limits.

You don’t need to write application code. Your agent can help with the setup; you make the decisions about hosting and access.

1. The problem

Everyone on your team has an agent learning things the rest of the team’s agents never see. One person’s agent works out how the billing service handles retries. Tomorrow a teammate’s agent starts from nothing.

Cursor, Claude Code and Codex each have their own ways of loading instructions and skills. Some instructions are tied to the current repository, even when the knowledge would be useful across several projects. Skills get zipped up and posted in Slack. Someone keeps a docs repo and reminds people to pull it. Before long there are three versions of the same instructions and nobody knows which one is right.

A shared folder fixes the reading side. Writing is harder. Once several agents edit the same files, one agent’s changes can overwrite another’s, files grow past whatever limit you set in a prompt, and nobody can tell which agent changed what. Telling an agent “keep this under 200 lines” is advice, not enforcement.

When you don’t need OpenLore. If it’s just you, one agent and one repo, Markdown files in that repo are fine. OpenLore earns its place once a second person, agent or project needs the same knowledge.

2. How OpenLore works

OpenLore is an open-source server that holds your team’s docs, skills and notes as ordinary files in folders. Agents connect over MCP or SSH and work with it like a filesystem, using commands they already know: ls, cat, grep, find. There is no vector database and no new query language to learn.

The server sits between your agents and the files, so it can check every write before it lands. That’s where the permissions, size limits and conflict checks in this guide come from.

The MCP server exposes two tools: shell, to run commands against the virtual filesystem, and list_commands, to discover what the server supports. Agents don’t need a separate tool for every filesystem operation.

Security in plain English. The normal shell is an in-memory interpreter written in Go, not an operating-system shell. It does not give agents arbitrary access to host programs or the host filesystem. Each identity only sees the folders it is allowed to see. Optional plugins and operator-configured integrations have their own capabilities; enable only what your team needs.

3. Set up your team server

OpenLore is self-hosted. Start on your own machine so you can check the layout and permissions, then deploy it somewhere your team can reach.

Ask your agent to follow the SSH quick start and Auth concept. You can also fetch the public server’s interactive instructions:

ssh openlore.sh teach | claude

This passes the server’s instructions to Claude Code. Review remote instructions before giving an agent permission to act on them. For another CLI agent, fetch the instructions and provide them using that client’s supported input workflow. If the public SSH connection is unavailable, the linked documentation is the starting point.

Work through these stages with your agent:

1. Run locally. Create a team configuration repository and start OpenLore with a persistent directory for your team’s files.
2. Onboard the team. Add people, agent identities, roles and folders. Decide who can read and write each folder.
3. Deploy. Choose your hosting provider, configure persistent storage and backups, and expose SSH and HTTPS to the team. Keep credentials out of the configuration repository.

What to expect

Setup is a conversation with your agent, not a one-click install. It will ask questions and may hit an error and fix it as it goes. Stay with it until the checks below pass.

How to tell it worked

• After local setup: run ssh -p 2222 localhost "tree -L 2 /". You should see your folders.
• After onboarding: run lore docsets inside an authenticated OpenLore session. Check the folders and access levels for each role, not just the administrator.
• After deployment: run the same tree command against your server’s address from another machine, using its configured SSH port.

If a check fails, give your agent the exact error and ask it to fix that step. A folder listing confirms connectivity, not that every permission or deployment setting is correct.

Before anyone connects: lock it down

Configure authentication before exposing a server containing private information:

• Set allow_keyless: false in lore.json so SSH requires a recognised key.
• Set "unknown_identity": "deny" in lore.json so unknown keys are rejected.
• Enable MCP and set mcp.require_auth: true in openlore.yml. Configure the token/OAuth settings too; requiring authentication without a token configuration fails closed.
• Use HTTPS for remote MCP connections and test that an unauthenticated client cannot read private files.

Writes are off by default. Set readonly: false in openlore.yml when you’re ready for the writing exercises, and grant write access only to the intended identities. See Auth and MCP authentication.

4. Lay out your folders and permissions

Folders do most of the organising for you. Agents understand that /team/marketing holds marketing material without being told, and folders are the natural place to attach permissions.

/team/shared/          everyone reads and writes
/team/engineering/     engineering writes, marketing reads
/team/marketing/       marketing writes, engineering reads
/home/<name>/          each person's private workspace

Permissions live in lore.json. Each collection of paths (a docset) grants roles one of three access levels: ro to read, publish to add files to an inbox, or rw to read and write. Here’s a trimmed example; replace the example SSH key and configure the backing directories before using it:

{
  "allow_keyless": false,
  "unknown_identity": "deny",
  "roles": {
    "engineering": {},
    "marketing": {},
    "lead": {}
  },
  "docsets": {
    "shared": {
      "paths": ["/team/shared"],
      "access": { "allow": { "engineering": "rw", "marketing": "rw", "lead": "rw" } },
      "config": { "edit": ["lead"] }
    },
    "engineering": {
      "paths": ["/team/engineering"],
      "access": { "allow": { "engineering": "rw", "marketing": "ro", "lead": "rw" } },
      "config": { "edit": ["lead"] }
    },
    "marketing": {
      "paths": ["/team/marketing"],
      "access": { "allow": { "marketing": "rw", "engineering": "ro", "lead": "rw" } },
      "config": { "edit": ["lead"] }
    },
    "sam-home": { "paths": ["/home/sam"] }
  },
  "identities": [
    {
      "name": "sam",
      "public_key": "ssh-ed25519 AAAA...",
      "roles": ["engineering", "lead"],
      "home": "sam-home"
    }
  ]
}

You don’t have to write this by hand. Ask your agent to generate the configuration from your team list, then review it. Test a non-lead engineering identity, a marketing identity and an unknown identity before moving on. Keep rule-editing rights with trusted leads, not every writing agent.

5. Connect two agents

The point of this guide is two agents working from the same files, so connect two now. Use whichever pair your team runs.

Terminal agents over SSH

Fetch your server’s connection instructions and add them to the instruction file your agent actually reads:

ssh your-lore-server agents >> AGENTS.md

Replace your-lore-server with your SSH hostname or alias; add -p 2222 if your server uses the default OpenLore SSH port rather than port 22. Review the generated snippet. For clients that don’t automatically read AGENTS.md, put or reference those instructions in their supported project or user-level configuration.

The snippet tells the agent how to connect and which commands to use. User-level instructions are useful when you want the same knowledge across repositories.

MCP clients

Point the client at https://your-lore-server/mcp and complete its authentication flow. For CLI clients that support these commands:

claude mcp add --transport http openlore https://your-lore-server/mcp
codex mcp add openlore --url https://your-lore-server/mcp

For Claude Desktop, add a custom connector with the same URL. ChatGPT custom MCP connections require developer mode and an account or workspace that permits them. Availability and authentication steps depend on the client; see connecting Claude Code and usage.

Authenticated MCP clients can have a separate identity acting for the person who logged in. Keep distinct identities instead of sharing one SSH key or credential across the team.

Checkpoint. Ask each of your two agents: “List the folders you can see on OpenLore.” Then ask each to read a file. If either can’t, fix that before moving on. Everything after this depends on it.

6. Share knowledge between agents

In your first agent, ask:

Write up what you know about how our billing service handles retries and save it to /team/engineering/billing-retries.md on OpenLore. Use the code and documentation as evidence; don’t invent a retry policy.

In your second agent, ask:

What does OpenLore say about billing retries? Read the shared file and cite it in your answer.

The second agent searches the server, finds the file and answers from it. Nobody copied or pasted anything. Any teammate’s agent with read access to /team/engineering can do the same tomorrow.

Make this a habit: when an agent works something out that the team will need again, tell it to save it to the right folder.

Share a skill across the team

Skills are where copy-paste hurts most, so move them next. With the skills plugin installed and plugins.skills.enabled: true in openlore.yml, run these commands in an authenticated OpenLore session with write access:

mkdir -p /team/shared/skills
skills enable /team/shared/skills
skills import https://github.com/owner/repo /team/shared/skills
lore meta --filter skills

Replace the example repository with a public skills repository you trust. If it contains several skills, import returns candidates; select one and rerun with that skill’s path. Ask both agents to find and read the same SKILL.md before using it.

Branch imports track upstream and check for updates when SKILL.md is read, subject to the configured refresh interval. Tags and commits are pinned. Use skills status to inspect tracking and skills update to request an update. Agents see the updated shared file on subsequent reads; copies already loaded into a conversation don’t change automatically.

Remote imports require public repositories. GitHub is supported, along with other supported HTTPS Git providers; see the skills plugin documentation.

7. Make it safe to write

These checks run on the server. An agent prompt cannot bypass the permissions or rules attached to its identity.

Edits don’t overwrite each other

Keep write_conflict_policy: hash, the default. If a file has changed since an agent read it in the same session, its stale write is rejected and it must re-read before trying again. Appends and patches use conflict checks too. Don’t switch to last_write_wins if you need these overwrite protections.

Try it with a disposable file and two terminals. First create the example file:

ssh your-lore-server "echo 'Use Slack for onboarding' > /team/shared/conflict-demo.md"

In terminal 1, keep an interactive session open after reading:

ssh your-lore-server
cat /team/shared/conflict-demo.md

In terminal 2, change the file:

ssh your-lore-server "sed -i 's/Slack/Teams/' /team/shared/conflict-demo.md"

Back in the still-open terminal 1, attempt a stale write:

echo 'Use Slack for onboarding' > /team/shared/conflict-demo.md

The write should be rejected. Re-read the file before making your next edit. Separate SSH invocations don’t share the earlier session’s read history; blind overwrites have a narrower conflict-check window. See write-system internals for the exact guarantees.

Agents can read what they can’t change

With the layout in section 4, ask a marketing identity to edit /team/engineering/billing-retries.md. It can read the file, but the write should be refused. Test with an identity that does not also have the lead or engineering role.

Files stay the size you set

Context files grow because agents append and never delete. Set a limit once and the server enforces it. Have an authorised lead add /team/shared/.lore/config.yaml:

version: 1
rules:
  keep-it-short:
    match: ["**/*.md"]
    use: size/lines
    with: { max: 200 }

Now a write that would take a matching Markdown file past 200 lines is rejected. The agent has to trim, split or link out instead. Limits can also be set in estimated tokens (size/tokens) or kilobytes. Only roles listed in the docset’s config.edit can change these rules, so ordinary writing agents cannot lift their own limit.

For relative limits, use max: initial with a growth factor such as 1.1. This allows 10% growth over the recorded baseline; see folder rules for when that baseline is captured.

Run lore validate /team/shared to check existing files against the rules, then test an over-budget write to a disposable Markdown file and confirm it is rejected.

See who changed what

Open your server’s web view and select a file. Its Timeline shows recorded changes and actor information, including delegated identity where available. SSH attribution depends on the identity behind the key; shared keys lose that distinction. This is provenance, not a full version history. Use your own backup or version-control workflow to preserve previous file contents.

8. What OpenLore doesn’t do (yet)

• Managed hosting: this guide uses a self-hosted server. Your team owns deployment, upgrades and backups.
• Runtime plugin installation: plugins need to be compiled into your build. Enabling a plugin in configuration does not install it.
• Private remote skill imports: remote imports need publicly accessible repositories.
• Full version history: the timeline records provenance, not a recoverable copy of every old file.
• Automatic agent instruction loading: connect each client and tell it when to discover and read shared skills. OpenLore doesn’t replace the client’s own instruction-loading rules.

If one of these blocks you, open an issue with your use case.

9. Cheat sheet

Run these inside your OpenLore session:

tree -L 2 /team                  # see the layout
grep -ri "retries" /team         # search files you can read
lore docsets                     # what you can access, and how
lore meta --filter skills        # list available skills
lore validate /team/shared       # check files against folder rules
skills status                    # inspect tracked skills

Common problems

10. Next steps

Pick one shared skill and one piece of team knowledge to maintain in OpenLore. Connect a teammate’s agent, have it read both, and test a denied write and an over-budget write. That’s a small, useful rollout you can build on.

• Read the full documentation for transport, identity and rule configuration.
• Star the repository if it’s useful.
• Share feedback or find an issue to work on.