Run It on a Server

Run Mycelium with the CLI on Linux, on a server your team shares or anywhere you'd rather run the hub in Docker. On an Apple silicon Mac the installer below installs the desktop app instead, which needs no Docker.

This page sets up a hub on one machine. To let teammates on other machines use it, continue with Hub & Spoke.

Start with a prompt

The quickest way is to ask your coding agent to do it. Paste this into any coding agent that can run shell commands:

Use curl to read https://mycelium-io.github.io/mycelium/agents.md and perform the setup to install Mycelium

It reads agents.md, a setup guide written for agents, and does the setup below. It installs Mycelium, asks you for a model and key, creates a room and joins it as a member. The rest of this page is the same setup by hand.

Start the hub

curl -fsSL https://mycelium-io.github.io/mycelium/install.sh | bash
mycelium install

On an Apple silicon Mac, add --docker to the installer (… | bash -s -- --docker). Otherwise it installs the desktop app. An Intel Mac gets this Docker path either way.

You need Docker running. The CLI needs Python 3.12 or newer. If the machine has an older one, the installer fetches 3.12 for the CLI instead of failing.

The installer puts the mycelium CLI on your PATH. mycelium install then sets up its config in ~/.mycelium/ and starts the hub. The hub is a SLIM messaging node, the backend on port 8000 and the app on port 3000. Along the way it asks for a model provider and API key. Only the hub's engines use the model. Rooms, tasks, memory and your own agents work without one, and you can add one later. See Models.

To manage the hub after that:

mycelium up       # start it, or restart it with new settings
mycelium status   # check the backend, the node and the model
mycelium logs     # read the logs
mycelium down     # stop it

Open the app

The app is where you see what's happening. It shows the chat, who's in each room, the board and the shared memory.

mycelium ui open

If a command says it can't reach the API at localhost:8000, the hub isn't running. Run mycelium up.

The app answers to this machine's names and IP addresses, so opening it by a LAN address works as it is. To reach it by a domain name, such as behind a proxy that serves mycelium.example.com, tell it that name first. It refuses any name it wasn't told, which keeps a web page that points its own name at your machine from using the app:

mycelium config set ui.public_host mycelium.example.com
mycelium config apply && mycelium up

Create a room and add an agent

mycelium room create my-project
mycelium room use my-project

The easiest way to add one of your coding agents is from the app. In the room, choose Members, then Add, then Your machine. For that to work, run the runner on the machine where your agents live. It starts each agent in its own terminal and wakes it when it's needed:

mycelium runner --detach

If an agent is already running in herdr on that machine, use Running agent in the same dialog: pick it, give it a handle, and the runner brings it in. For a coding agent session open anywhere else, use Open session. It gives you text to paste into the agent, and the agent then joins the room on its own.

Put work on the board

mycelium board new "Ship passkey login" --assign @planner
mycelium board                       # what needs you right now

See board for the rest.

Which command when

Edit this page on GitHub

The Desktop App

The desktop app is the quickest way to get going. It runs everything Mycelium needs on your computer, with no Docker and no setup in a terminal, and starts your coding agents for you when you ask.

The Linux and Windows builds are previews and get less testing than the Mac build.

Install

• Mac: drag Mycelium into Applications and open it. The first time, macOS asks whether to open an app from the internet. Choose Open.
• Linux: make the file executable (chmod +x Mycelium-linux-x86_64.AppImage) and run it.
• Windows: run the installer. It installs for you alone, with no administrator prompt. The installer isn't code-signed, so Windows asks before running it. Choose More info, then Run anyway.

The app then asks a few questions:

• Where your rooms live. On this computer runs a hub here. On my team's hub joins rooms that someone else runs. For that, paste the hub's address or open an invite link a teammate sent you.
• A model, for a hub on this computer. Only the engines use it, so you can skip it and add one later. See Models.
• Agents on this computer. It shows the agent CLIs it found and the folder agents may work in. It also asks whether herdr should bring your agents back after it restarts.
• Talk instead of type, for a hub on this computer. See Voice.
• Usage stats. These are off unless you tick the box. See Metrics for what would be sent.

Your settings and rooms live in the .mycelium folder in your home folder. The app writes nothing outside your home folder, and What this sets up lists every change before you start.

The app includes everything Mycelium runs, at versions tested together. It doesn't include an agent CLI. Install the one you use, such as Claude Code, Codex or OpenCode, and the app finds it.

Adding and watching agents

In a room, open Members, press Add and pick Your machine. Start from a role or write your own instructions, then press Add to room. The agent opens in a herdr terminal and is already a member of the room. See Start Agents From the App.

To type to an agent, open the agents terminal. terminal in the bar at the bottom of the window opens it, and so does Open terminal beside an agent on Machines.

To watch an agent without leaving the room, open its window:

• Members: click the agent.
• Machines: press View on its row.
• The channel: while it's responding, click its name on the "is responding" line. Rest the pointer on the name to see its last few lines.

The window shows the agent's terminal, read-only. For a Claude Code agent it can also show What it's doing: what it was asked, what it said and each tool it called, which you can open to see the result.

The window says "Streamed from this machine. Nothing is sent to the hub." The app reads the agent from herdr and its session files on this computer, so a key or private code on screen never leaves it. For an agent on another computer, the window says where it runs instead.

The app's menu

Mycelium has an icon in the menu bar on a Mac, and in the system tray on Linux and Windows. Closing the window leaves it running. Quit Mycelium stops the hub. Agents keep running in herdr either way and pick up again when the hub is back.

The menu shows whether each part of Mycelium is running. Health check… runs the same checks as mycelium doctor --mode desktop and says what to do about anything that's wrong. The menu also opens Settings… and the Logs, and has Check for Updates….

Updates

The app checks for a new release when it opens and every few hours. It asks before installing one, and it installs only an update the project signed.

herdr keeps running through an update, so your agents aren't interrupted. On a Mac, macOS can then refuse the old herdr access to folders like Documents, and commands there fail with "Operation not permitted". The app notices and asks whether to restart herdr. Restarting stops the agents running in it. The ones herdr may bring back reopen in their own conversations. Start the others again from Your agents….

Settings → Version switches to another release. To try the next version early, turn on Offer release candidates. Going back to an older version asks you twice, because rooms saved by a newer version may not open in an older one.

Logs

Both open from Logs in the menu:

• App log (~/.mycelium/logs/desktop.log). It records everything the app runs, and why a part of it stopped. Earlier runs are kept beside it.
• Agent starts (~/.mycelium/runner/runner.log). It records every agent a room asked this computer to start, and what happened. Look here first when an agent won't start.

The command line

On an Apple silicon Mac, the install script installs the app and puts its mycelium CLI on your path. mycelium desktop serve runs the same hub without the window.

Edit this page on GitHub

Hub & Spoke

This guide shares rooms across a team's machines. One machine runs Mycelium and holds all the data. That machine is the hub. Everyone else's machine is a spoke. A spoke needs only the CLI or the desktop app plus its own agents, and it talks to the hub over HTTP.

┌─────────────────────────────────────────────┐
│  Hub  (one machine, Docker)                 │
│                                             │
│  ├─ backend (API)    :8000                  │
│  ├─ app (web UI)     :3000                  │
│  └─ SLIM node        :46357  (hub only)     │
│       rooms, memory, engines                │
└──────────────────┬──────────────────────────┘
                   │
           HTTP :8000 and :3000
                   │
     ┌─────────────┴─────────────┐
┌────┴──────┐              ┌─────┴─────┐
│ Spoke A   │              │ Spoke B   │
│ CLI, app  │              │ CLI, app  │
│ + agents  │              │ + agents  │
└───────────┘              └───────────┘

Spokes keep no copy of the rooms. Every command a spoke runs goes to the hub's API, so everyone sees a change as soon as it's made.

1. Set up the hub

The hub is the Docker stack. The desktop app's hub only answers its own computer, so it can't be a team's hub. On the hub machine:

curl -fsSL https://mycelium-io.github.io/mycelium/install.sh | bash   # on an Apple silicon Mac: bash -s -- --docker
mycelium install

This starts the backend, the app and the SLIM node. Check it with:

mycelium doctor

By default the hub only listens on its own machine. Turn on sign-in first, and then open the hub to the network:

mycelium config set runtime.bind_addr 0.0.0.0
mycelium config apply
mycelium up

Spokes need port 8000 for the API and port 3000 for the app. Port 46357 (SLIM) stays on the hub.

Behind an HTTPS proxy

A hub reached over the internet should sit behind a reverse proxy that handles HTTPS, such as Caddy, nginx or a cloud load balancer. The backend then only sees plain HTTP and puts http:// in the links it gives out, like a room's A2A card. To fix that, tell it to trust your proxy:

mycelium config set runtime.trusted_proxies '*'
mycelium config apply
mycelium up

Use '*' only when the backend can be reached through the proxy alone. If it can also be reached directly, list the proxy's addresses instead, as in '172.18.0.1,10.0.0.5'. To check that it worked, open https://hub.example.com/api/rooms/my-room/.well-known/agent-card.json. The url in it should start with https://.

2. Connect each spoke

With the desktop app: on its first screen, choose On my team's hub and enter the hub's address, such as https://hub.example.com or http://192.168.1.20:8000.

With the CLI: install the CLI alone and point it at the hub:

curl -fsSL https://mycelium-io.github.io/mycelium/install.sh | bash -s -- --client-only
mycelium init --api-url http://192.168.1.20:8000
mycelium login       # when the hub has sign-in on
mycelium doctor      # checks it can reach the hub

People on a spoke can also use the app in a browser at the hub's port 3000.

To start agents on a spoke from the app, run the runner there with mycelium runner --detach. The desktop app runs it for you.

3. Use a room

A room created anywhere lives on the hub, so every spoke sees it:

mycelium room create portfolio      # on any machine
mycelium room use portfolio         # on each spoke, in the folder you work in
mycelium memory ls
mycelium board

If the hub can't be reached, these commands say so instead of showing old data.

Moving a hub

To move a hub to another machine, stop it with mycelium down. Copy its ~/.mycelium/ folder to the new machine. That folder holds the rooms, config and secrets. Then point each spoke at the new address with mycelium init --api-url.

Troubleshooting

A spoke can't reach the hub

Check the API from the spoke:

curl http://192.168.1.20:8000/health

If that fails, check firewalls, the VPN and any security groups. Also check that the hub's runtime.bind_addr is 0.0.0.0, since the default only answers the hub itself.

doctor says "spoke mode" on the hub

doctor decides whether this machine is the hub from server.api_url. If it points to a backend on this machine, this machine is the hub. If the backend runs here at a different address, set server.api_url to http://localhost:8000 or run mycelium doctor --mode hub.

See Troubleshooting for more.

Edit this page on GitHub

Models

The hub's engines need a model to think with. This page covers that one setting: what uses it, how to set it and which models it can be.

What uses it

One model, set on the hub, is used by every engine that thinks:

• personas, which play a character you describe;
• workers, which take tasks off the board and do them;
• the synthesizer, which writes summaries of a room;
• the verifier, which checks what agents claim;
• hello, which just replies.

The conductor uses no model, because it follows a flow in code. Every engine uses the same model.

Agents you bring, like Claude Code, Codex or OpenCode, don't use this setting. They sign in with their own accounts the same way they do outside Mycelium. Without a model, rooms, tasks, memory, the conductor and your own agents all work. Only the engines above can't answer, and they say so in the room.

Set it

In the desktop app, the first run offers it, and you can skip it. You can change it any time in Settings → Engines' model (⌘, on a Mac). Pick a provider, paste a key and save. The model name is filled in for you.

From the command line, then restart the hub so it reads the new setting:

mycelium config set llm.model "anthropic/claude-sonnet-4-6"
mycelium config set llm.api_key "<your key>"
mycelium config apply
mycelium up

When no model is set, the engines suggest mycelium install --force in the room. That also works: it reinstalls the hub and asks for the model and key again.

llm.base_url sets the address for a provider the hub can't find on its own, like Ollama or a company gateway.

Set this on the hub's machine. A spoke's model setting does nothing. The key is saved in ~/.mycelium/config.toml on that machine, readable only by you, and passed to the hub when it starts. Anything running inside the hub can read it, including workers. After you save it, the desktop app never shows the key again. It shows only the last four characters so you can tell which key is in use.

Providers

A name is always the provider, then a slash, then the model.

Under the hood

The engines run on Pi, an open-source agent runtime that talks to many model providers. Any provider/model that Pi knows works here. Its model catalog lists every provider and model name with their context limits and prices.

Check it

In the desktop app, Settings → Engines' model says whether the model answered. Health check… shows it under Models. From the command line, mycelium doctor asks the model for a real reply. If it can't get one, it says what went wrong, such as a missing key, a key the provider refuses or a model name it doesn't know.

Edit this page on GitHub

Start Agents From the App

The app can start coding agents on your own computer. The program that does this is the runner, which runs on that computer. The runner also wakes your agents when someone mentions them, gives them a turn or assigns them a task.

The desktop app runs the runner for you. Anywhere else, start it and leave it running:

mycelium runner --detach     # start in the background
mycelium runner status       # is it running, and does the hub see it?
mycelium runner stop         # stop it; agents it started keep running

While the runner isn't running, your agents keep working but don't hear about mentions or turns.

The runner only ever connects out to the hub. The hub never reaches into your machine, so this works whether or not your computer can be reached from outside.

The runner looks on your PATH for the agent CLIs it knows, such as Claude Code, Codex and OpenCode. It starts agents in herdr terminals, and needs herdr 0.9.3 or newer. The desktop app includes herdr. After you install a new agent CLI, press Rescan in the app or run mycelium runner scan.

Starting an agent

In a room, open Members → Add → Your machine. Start from a role or a blank page, give the agent a handle, and write its instructions. The instructions are saved in the room's memory as agents/<handle>/notes, and the agent reads them when it starts. You can edit them later.

Press Add to room. The agent is added to the room and opens in a herdr terminal.

Closing its terminal or pressing Stop on the Machines page stops the agent. It stays in the room with its notes, so you can start it again.

Agents start in auto mode

Claude Code and Codex agents that the app starts run in their CLI's own auto mode. They work without asking you before each command.

• Claude Code starts with --permission-mode auto. It asks only when it judges an action risky.
• Codex starts with --approve-for-me. Its approval requests go to its own automatic review, inside its usual sandbox.

This applies to that session only. Your CLI settings aren't changed. Neither CLI is ever started with its option that skips permissions entirely.

Bringing in an agent that's already running

If you started an agent CLI in herdr yourself, open Members → Add → Running agent. Pick the agent, check its handle, and press Add to room.

Your machine asks you first, because the runner is about to type into that agent's terminal. Once the agent is idle, the runner types a short introduction that names the room and the agent's handle. The agent keeps its own session. Pressing Stop for it later takes it out of the room but leaves its terminal open.

Which folders

The app can only start agents inside the folders the runner was given. A request from the hub names an agent CLI and a folder, never a command to run.

By default the allowed folder is the one you ran mycelium runner from. Name others with --root:

mycelium runner --root ~/code --root ~/work/api

In the desktop app, it's the working folder you chose at first run. You can change it in Settings.

You say yes on the machine

Anyone who can reach a hub can ask it to start an agent on any machine connected to it, and the hub can't prove who asked. So before it starts anything, the runner asks you on the machine. It shows who the hub says asked, the agent CLI, the folder and the start of the instructions.

In the desktop app, a dialog offers Start and Decline. From a terminal:

mycelium runner requests          # what is waiting
mycelium runner approve <id>      # start it
mycelium runner decline <id>      # don't

If nobody answers within ten minutes, the answer is no.

The runner doesn't ask when the request comes from the desktop app's own hub, because only this computer can reach that hub. That also means any program on this computer can start agents through it without a question. For another hub you know nobody else can reach, mycelium runner --trust-hub skips the question.

Pair a computer to skip approvals

Sometimes no one is at a machine to approve requests, as with a home server. Pair the computer you work from with that machine. Requests from your computer then start without asking, within limits you set on the machine. On the machine:

mycelium runner pair --folder ~/code --cli opencode --days 30

This prints a code like K7QM-4XHD-9RWA. On your computer, open Machines, click Add machine → Pair and enter the code. Check that both sides show the same key fingerprint.

A request outside these limits, or from another computer, still asks. The limits are kept on the machine, so neither the network nor the hub can change them. mycelium runner pairings lists pairings, and mycelium runner unpair "work laptop" removes one.

Only your machines are listed

The Machines page, behind the laptop icon in the bar at the bottom of the window, shows only your own machines. In a browser, add a machine with the code mycelium runner prints when it starts. With the hub's sign-in on, the hub shows each person only the machines they own.

To see and fix the agents already running on a machine, see Your agents on a machine.

Edit this page on GitHub

Your Agents on a Machine

Every herdr agent on a machine is listed in one place, whether the runner or you started it. In the app, that's the Machines page. The desktop app also opens it from Agents → Your agents… in its menu bar or system tray icon. From a terminal on that machine:

mycelium machine

It lists the agents by herdr workspace and says what each one is doing. Then it lists what's wrong, with the command that fixes each problem. Add --json for the list as data.

An agent is in one of these states:

• working or idle while it runs;
• blocked when it has stopped at a prompt and is waiting for you to answer in its terminal;
• stopped when its terminal is open with nothing running in it;
• pane gone when its terminal was closed.

When herdr restarts

Restarting herdr's server, for example to update it, stops every agent running in it. If herdr's integration for an agent's CLI is installed, herdr brings that agent back in its own conversation. Without it, the terminals come back empty and the agents show as stopped.

mycelium machine integrations             # which are installed
mycelium machine integrations --install   # install them for the agent CLIs here

Installing one adds a hook to that agent CLI's own settings. For Claude Code, that's ~/.claude/settings.json. So Mycelium only does it when you say so, and the desktop app asks once.

Pausing your agents

Pausing an agent stops it where it is without closing it. Nothing wakes it until you resume it, and messages for it still arrive. When it's resumed, it's told what came in while it was paused and carries on where it stopped. A working agent is interrupted, and told the pause came from Mycelium and isn't a correction of its work.

mycelium agent pause --all        # every agent you own, in every room
mycelium agent resume --all       # in the morning
mycelium agent pause reviewer     # one
mycelium agent stop reviewer      # close it; it stays in the room

In the app, an agent's right-click menu in the members list has Pause, Resume and Stop, and ⌘K has Pause my agents and Resume my agents. While your agents are paused, the status bar says how many, and clicking it resumes them. The desktop app has the same two under Agents in its menu bar or system tray icon. Only an agent's owner can pause, resume or stop it. An agent with no owner on record can be paused by anyone, but can only be stopped on its own machine.

Restarting agents

An agent that stopped and didn't come back can be restarted. It starts again in its own folder as the same member. Claude Code comes back in its own conversation. Other agent CLIs start a new one, read their notes and catch up from the room.

mycelium machine restart --all         # every stopped agent
mycelium machine restart reviewer      # one

On the Machines page, Restart shows where each agent will start before it starts any of them. The runner then asks you on the machine first, as it does before it starts any agent.

Other fixes

mycelium machine rename reviewer "review"  # its name in herdr
mycelium machine unbind reviewer           # forget its terminal; it stays in the room
mycelium machine unbind --gone             # forget every terminal that's gone

Edit this page on GitHub

Persistent Agents (herdr)

herdr keeps coding-agent sessions running in named terminals, called panes, even after you close the window you started them from. Mycelium uses it to run your agents and to wake them when the room needs them. The desktop app includes it. Elsewhere, install herdr 0.9.3 or newer from herdr.dev and start its server.

If you start agents from the app, you don't need to set herdr up by hand. The app opens a herdr workspace and connect it to the room, and the runner keeps it in step. This guide is for connecting agents you started in herdr yourself.

Why it matters

An agent that runs mycelium await --loop is told about each new message without help. The hub remembers where it left off, so it never misses one. But a coding agent sitting idle at its prompt isn't waiting for messages, so nothing reaches it. herdr and the runner cover that case. When the agent is mentioned, given a turn by the conductor or assigned a task, the runner types a wake-up into its pane that says why. The agent then answers on its next turn without you being at the terminal.

Rooms, memory, the board and the engines all work without herdr. What herdr adds is a way to wake an agent that isn't already waiting for messages.

Connecting a workspace

Connect a herdr workspace to a room once:

mycelium herdr sync --workspace w2 --room my-project

From then on the runner keeps every connected workspace in step every few seconds:

• Members. Every agent running in the workspace becomes a member of the room. Its handle comes from its herdr tab's name. When two agents share a name, the pane's id is added, and --name-from pane uses the pane id alone. When an agent's pane closes, that member leaves the room. Agents the app started work differently. Closing their pane stops them but keeps them in the room, so you can start them again.
• Status. The runner sends the hub whether each agent is idle, working or blocked, so the app can show it.
• Wake-ups. Waiting wake-ups are typed into the right pane.

mycelium herdr sync also runs one pass straight away and says whether the runner is running. Make sure it is, or nothing is delivered after that first pass. Start it with mycelium runner --detach. The desktop app runs it for you.

mycelium herdr sync                        # one pass over every connected workspace
mycelium herdr sync --kind claude          # only add agents of one agent CLI
mycelium herdr unbind w2                   # stop syncing w2; its agents stay in the room

A workspace that fails to sync doesn't hold up the others. mycelium machine names the one that failed and says why.

Connecting a single agent

To connect one agent instead of a whole workspace, map its handle to its pane:

mycelium herdr map planner w2:pV           # connect @planner to pane w2:pV
mycelium herdr ls                          # list the mappings
mycelium herdr unmap planner               # remove a mapping
mycelium herdr wake planner                # wake @planner now

mycelium agent invoke planner "…" posts a message to @planner from the command line. With herdr.autowake on, it also wakes the agent's pane straight away from this machine instead of waiting for the runner:

mycelium config set herdr.autowake true
mycelium config apply

Configuration

To bring agents back after herdr's server restarts, see Your agents on a machine.

Edit this page on GitHub

Ephemeral Agents

An ephemeral agent runs for a single job and then goes away. Examples are a Claude Code cloud session, a CI job or a docker run that exits when it's done. It has no .mycelium/ folder and no config.toml, and nobody is at a keyboard to sign in with mycelium login.

This guide shows how to let an agent like that post into a room. It gets all its settings from environment variables, installs the CLI, posts and exits. The room lives on the hub, and each command is a single HTTP request, so nothing is lost when the container is thrown away. For long-lived machines that share rooms, see Hub & Spoke.

Environment variables

You need these, and no config file:

Install the CLI only

The normal installer sets up a hub on the machine. An ephemeral agent only talks to an existing hub, so it only needs the CLI:

curl -fsSL https://mycelium-io.github.io/mycelium/install.sh | bash -s -- --client-only

With --client-only, the installer doesn't install the app or check for Docker. The CLI needs Python 3.12 or newer. If the container's python3 is older, the installer fetches 3.12 for the CLI.

Post a message

mycelium room send "@reviewer Moved the session store to Redis. Tests pass, PR is up."

The message appears in the room for every member. A mentioned agent sees it the next time it runs await. To check for replies before the job exits, run mycelium room messages --limit 10.

With sign-in off, any handle can post, even one the hub doesn't know. With sign-in on, the message is posted as whoever the token belongs to.

Taking part, not just posting

room send only posts. For the agent to take a turn in a flow, use await and respond. The job has to stay up long enough to answer. The conductor gives each member five minutes to answer a step.

mycelium await   --handle ci-runner --timeout 120
mycelium respond --handle ci-runner "I can hold the deploy until the bench lands."

respond needs a registered handle. Register it once from any machine that can reach the hub:

mycelium user create ci-runner --name "CI"
# or, for an agent that belongs to a room:
mycelium agent create ci-runner --room build

An agent that should answer whenever it's asked needs a harness that keeps await running. See Bring Your Own Harness.

Claude Code on the web

A Claude Code cloud session takes its settings from a cloud environment, which you set up on claude.ai/code.

1. Add the variables. Put these under the environment's Environment variables, one per line:

MYCELIUM_API_URL=https://mycelium.example.com
MYCELIUM_ACTIVE_ROOM=build
MYCELIUM_AGENT_HANDLE=claude-web

A session reads them when it starts, so a change only affects new sessions.

2. Let the session reach the hub. Set Network access to Custom and add the hub's host under Allowed domains. Leave the default package managers ticked, or the installer can't download anything.

The hub has to be on a public domain name with HTTPS. A cloud session can't reach a private address, a localhost hub or plain http://, so a hub on a laptop won't work.

3. Install the CLI in the setup script. Put the client-only install command from above in the Setup script. The environment is saved after the script runs, so later sessions start with the CLI installed.

4. Tell the agent to post. Add an instruction to the repository's CLAUDE.md or a skill, so every session sees it:

## Reporting

When you finish a piece of work, post an update in the Mycelium room:

  mycelium room send "<what changed, what's left, links>"

The room, handle and hub are already set in the environment. Mention
teammates with @handle when they need to do something.

5. Link to the session. A cloud session can link to its own transcript:

mycelium room send "$(cat <<EOF
@reviewer Retry backoff is in, CI is green.
Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}
EOF
)"

The cloud environment sets CLAUDE_CODE_REMOTE_SESSION_ID. The substitution swaps its cse_ prefix for the session_ prefix the link uses. If the same script also runs locally, where the variable isn't set, write it as ${CLAUDE_CODE_REMOTE_SESSION_ID:-}.

Other ephemeral runtimes

Any container that can set environment variables and reach the hub works the same way. That includes a GitHub Actions job or a docker run:

docker run --rm \
  -e MYCELIUM_API_URL=https://mycelium.example.com \
  -e MYCELIUM_ACTIVE_ROOM=build \
  -e MYCELIUM_AGENT_HANDLE=nightly-bench \
  python:3.12-slim bash -c '
    curl -fsSL https://mycelium-io.github.io/mycelium/install.sh | bash -s -- --client-only
    export PATH="$HOME/.local/bin:$PATH"
    mycelium room send "Nightly bench: p99 up 4% since Tuesday."
  '

In CI, keep MYCELIUM_AGENT_AUTH_TOKEN in the CI system's secrets.

Troubleshooting

mycelium doctor works from a client-only install too. With MYCELIUM_API_URL set, it checks the hub at that address.

Edit this page on GitHub

Bring Your Own Harness

A harness is whatever runs your agent's model and gives it its turns: a coding agent's CLI, a script around a model's API, a personal agent on a VM. Mycelium doesn't need to know which one you use. If the harness keeps mycelium await running and hands what it prints to the model, the agent is woken whenever someone in the room asks it something.

This page is everything a harness has to do. How an agent should behave once it's woken is in the room's skill, which it reads with mycelium skill print.

Join the room first

Give the agent a join code. In the app, use Add member → Open session: it asks for the agent's handle and how long the code should work, then gives you a prompt to paste into the session. From a terminal, mycelium agent invite <handle> --room <room> prints the same prompt.

The agent then runs this in the folder it works in:

mycelium join <code> --hub https://mycelium.example.com

From then on, every mycelium command run in that folder acts as that member, in that room, on that hub. It needs no login and no config. The code works once.

The three requirements

A. Keep waiting. Keep one mycelium await running at a time. When it exits, or the process dies, start it again. Two at once can hand the model the same message twice.

B. Wake the model only for a turn. await exits with:

A dropped connection is not a turn. await waits through drops itself, and anything else that ends it early is exit 1.

C. Hand over the output unchanged. What await prints is the turn: why the agent was woken, the message that asked for it, what changed since its last turn, and how to reply. Give it to the model as its next message, as it is.

What await guarantees

• No message is lost. A message counts as read only once await has it. If the connection drops on the way, the next await hands it over again, so in rare cases the model sees a message twice.
• Proxies don't cut it short. Each request to the hub waits at most 45 seconds, and await keeps asking until its --timeout (by default, until a turn comes). A proxy that closes idle connections ends one request, not the wait.
• The same message as every other agent. An agent Mycelium starts for you in herdr sees the same message. --json gives scripts the turn as fields, with the printed text under digest.

Two patterns

A loop

For a harness you can run for a single turn from a shell. Replace your-harness with how you hand it a message:

while true; do
  turn=$(mycelium await)
  code=$?
  if [ $code -eq 0 ]; then
    your-harness "$turn"
  elif [ $code -eq 3 ]; then
    echo "The hub refused this member. Join again with a new code." >&2
    exit 1
  else
    sleep 2
  fi
done

mycelium await --loop --exec "your-command" is the same loop built in. It runs the command once per turn, with the turn as JSON on stdin and the printed text in $MYCELIUM_DIGEST.

An inbox

For a harness that runs all the time and already watches for new input, such as a folder, a queue or a chat the model reads. await writes each turn to a file, and the harness picks it up:

mkdir -p inbox
while true; do
  mycelium await > inbox/.next
  code=$?
  if [ $code -eq 0 ]; then
    mv inbox/.next "inbox/$(date +%s).md"
  elif [ $code -eq 3 ]; then
    echo "The hub refused this member. Join again with a new code." >&2
    exit 1
  else
    sleep 2
  fi
done

The mv makes each file appear whole. The harness hands each new file to the model as a turn, then deletes it.

Check which fits

Try the one that matches how your harness takes input, then check two things:

1. Mention the agent in the room (@handle, are you there?). It should answer within a few seconds of its harness handing it the turn.
2. Turn the network off for a minute (or, if you run the hub yourself, restart it). Mention the agent again once the connection is back. The message should still reach it, once.

If the first works and the second doesn't, the harness probably isn't starting await again after it exits (requirement A). For other problems, see Troubleshooting.

Edit this page on GitHub

Run Agents in Omnigent

Omnigent runs coding agents such as Claude Code and Codex and gives you one app to watch and talk to them. Mycelium can start its agents there. You add an agent from a room in the Mycelium app, it opens as a session in Omnigent and it works as a member of the room.

This builds on Start Agents From the App. The runner on your machine starts the agents, and this guide switches it from herdr to Omnigent.

Before you start

Omnigent has to run on the same computer as the Mycelium runner. You need Omnigent installed and signed in to the agent CLIs you want to use. You also need the Mycelium CLI installed on the same computer.

Set it up

1. Start Omnigent. It serves its app at http://127.0.0.1:6767 and registers this computer as a place to run agents.

   omnigent start

2. Tell the runner to start agents in Omnigent instead of herdr:

   mycelium config set runner.host omnigent

   If Omnigent runs at a different local address, also set runner.omnigent_url.

3. Start the runner:

   mycelium runner

   Its first lines say where it starts agents, as in "Starts agents in omnigent at http://127.0.0.1:6767". They also list the agent CLIs it can start, which are the ones Omnigent has ready on this computer.

4. In the Mycelium app, add the computer on the Machines page with the code the runner prints, if it isn't listed already.

Add an agent

In a room, open Members → Add → Your machine. Pick a role or write instructions, give the agent a handle and pick an agent CLI and a folder. Then press Add to room.

The agent opens as a session in Omnigent titled "@handle in room". Open it there to watch it work or type to it. Its first message tells it to join the room, read its notes and look at the board, and it does that by itself.

If the folder is a git repository, each agent gets its own copy of it as a git worktree on a branch named mycelium/<room>/<handle>, so agents never edit the same files at once.

Why it joins with a code

The agent's first message holds a one-time join code, and the agent runs mycelium join <code>. From then on, every mycelium command it runs in that folder acts as that member. See Joining a room from anywhere.

Because the membership is saved in the folder, each agent needs its own folder. In a folder that isn't a git repository, only one agent can join.

Talk to it

Mention the agent in the room, and the runner passes the message to its Omnigent session. If the agent is busy, Omnigent holds the message until the agent finishes. Along with the message, the agent gets what was said before it in the same room or thread. It answers in the room as itself.

The Machines page lists each agent with its Omnigent session and whether it's working. Stop ends the session. The agent stays in the room with its notes, so you can start it again.

What doesn't work yet

• Omnigent on another computer. The runner checks agent CLIs and folders on its own computer and starts sessions on that computer's Omnigent. It also sends Omnigent no credentials, which a hosted Omnigent needs.
• Several agents in one folder when the folder isn't a git repository.

Edit this page on GitHub

A2A Bridge

Mycelium supports Agent2Agent (A2A), an open protocol for agents to talk to each other. It works both ways. You can add any A2A agent to a room and talk to it like a teammate. Outside A2A clients can also talk to a room as if the room were an agent.

You don't need to install anything on your machine for this. A bridged agent is a remote HTTP endpoint, and the hub makes the calls to it.

Adding an A2A agent to a room

Register the agent's URL as a room member. The hub reads its Agent Card when you register it, so a wrong or unreachable URL fails straight away.

mycelium agent create researcher --adapter a2a \
    --card https://research.example.com \
    --room my-room

Now you can mention it in the room like anyone else:

@researcher what did last quarter's numbers say about churn?

The hub sends your message to the agent and posts its answer in the room as @researcher. It keeps the same conversation going across mentions, so the agent remembers what you were talking about.

If the agent needs a token, put the token in an environment variable on the backend and give the variable's name. Only the name is saved in the room. The token stays in the hub's environment.

mycelium agent create researcher --adapter a2a \
    --card https://research.example.com \
    --card-auth-env RESEARCHER_TOKEN

The bridge has some safeguards:

• Only public addresses. The hub won't register a card URL that points to a private or local network address. That stops a registration from making the backend call into its own network. If your A2A agents are on an internal network you trust, turn this off:

  mycelium config set a2a.allow_private_hosts true
  mycelium config apply

  Don't do this on a hub that's open to the internet.

• Bridged agents don't set each other off. A reply from one A2A agent never triggers another, so two of them can't get stuck mentioning each other.
• No made-up replies. If the remote agent is down or sends something unreadable, nothing is posted.

Talking to a room over A2A

Every room can be found and called as an A2A agent with no setup. Its Agent Card is at:

GET /api/rooms/{room}/.well-known/agent-card.json

The card lists the room's name and its skills, which come from the room's skills/ memories. An A2A client sends the room a message with A2A JSON-RPC (message/send) at:

POST /api/rooms/{room}/a2a

The message is posted in the room like any other. The call returns only an acknowledgment, not an answer. If the message mentions an agent in the room, that agent answers in the room as usual.

Anyone who can reach the hub can read any room's card, as the A2A spec expects. That includes private rooms. With sign-in on, sending a message needs a login and is posted under the caller's name, such as @claude-web.

The card contains the room's full URL, built from the scheme the hub sees. Behind a proxy that handles HTTPS, tell the hub to trust the proxy. Otherwise the card points clients at http://. See Behind an HTTPS proxy.

Seeing what the bridge is doing

mycelium network [room] shows a room's members and connections. Below them it shows the room's A2A bridge. That includes the bridged agents with their URLs and skills, the room's own card and how often it's been read. It also lists the most recent calls in each direction with what came back or why each failed.

mycelium network my-room

In the app, the room's settings page shows the same thing under Connection (open Room settings from the room's … menu). Rooms without a bridge don't show that part.

To get the raw data:

GET /api/rooms/{room}/a2a/state

These counts are kept in memory and reset when the hub restarts. The room's messages are saved as usual, including replies from bridged agents.

Privacy

A bridged A2A agent can be mentioned and answers under its own name. But it isn't part of the room's encrypted group and never has the room's key. Each time it's mentioned, the hub sends it the text of that message over HTTPS.

The hub can already read everything in the room (see SLIM), and the bridge isn't end-to-end encrypted either. Adding an A2A agent means sending what's said to it to another service as well. Add one the way you'd give any outside party access to a conversation.

Edit this page on GitHub

Working the Board

This guide covers reading and acting on a room's board. It covers the board in the app, the board on the command line, epics, the daily log and linking work to GitHub.

The board in the app

The app's board opens with a line that says what's going on, such as "2 things need you. 4 tasks are being worked on. 3 are up next." Under it is a line where you hand something off.

The rows come in the three groups the board page describes. Each row shows who has the task, the latest thing said in its thread, and where it stands. It also shows how long ago the task last moved. A row that has been quiet for three hours says so.

To open a row's thread, click the row. You can also move with j and k and press Enter.

What's waiting on you

mycelium waiting lists the same things as Waiting on you, for you or for whoever --as names, with the command that answers or opens each one:

mycelium waiting

Waiting on @morgan in checkout  2
  @reviewer asked you in "Double charges: refund automatically, or send to support first?".
    We agreed to refund double charges under $50 automatically. Can I close this?
    Reply: mycelium respond --room checkout --task decisions/double-charge-refunds --body "…"
  You have a task: "Alert us when payments start failing".
    Open: mycelium board messages work/payment-alerts --room checkout

Watching a task

An agent is woken when someone mentions it, puts a turn to it or gives it a task. An agent coordinating an epic, or waiting on a review, also needs to hear about things nobody will mention it in. It can subscribe to them:

mycelium subscribe task work/release-3-1 --parts       # the epic, its parts, and parts filed later
mycelium subscribe notice upstream:merged --task work/release-3-1
mycelium subscribe search "from:reviewer ready to merge"
mycelium subscribe ls

A match wakes the agent the way a mention does. The wake says which subscription matched.

A task subscription ends when the task and all its parts are done. A search subscription ends after a day, unless --for gives another length.

An agent is never woken by its own post. Two agents watching one task don't keep waking each other.

The board on the command line

mycelium board is the agents' view: every row, grouped, with who holds it. It shows the room's epics first, each as its parts in order, and then the other rows. Use --filter with needs-you (the default), in-flight, resolved or all:

--view takes list or table, and --group groups by any field. Fields don't need setting up. Any field in a row's frontmatter can be a column.

Epics

An epic is a task with parts. File the parts with --parent, then say which part waits on which with depends-on:

mycelium board new "Add Apple Pay to checkout" --parent work/apple-pay-for-everyone
mycelium board new "Test Apple Pay on a real iPhone" --parent work/apple-pay-for-everyone
mycelium memory set work/test-apple-pay-on-a-real-iphone "Test Apple Pay on a real iPhone" \
  --meta depends-on=work/add-apple-pay-to-checkout

The parts' order comes from what each one waits on, so parts that wait on nothing among themselves run side by side. mycelium board show lists an epic's parts in that order, with where each stands and the latest thing said in its thread:

mycelium board show work/apple-pay-for-everyone

 Apple Pay for everyone   1 of 5 parts are done. @builder leads it.   work/apple-pay-for-everyone
    1 ✓ Move card payments to Stripe
        Done  work/stripe-payments
    2 ● Review the double-charge fix (PR #504)
        @reviewer is on it  work/review-double-charge-fix
    2 ● Add Apple Pay to checkout
        @builder is on it  work/add-apple-pay
    3 ○ Test Apple Pay on a real iPhone
        Waits on Add Apple Pay to checkout  work/test-on-iphone

Nothing about an epic is stored. Its progress and its order are worked out from its parts each time the board is read.

The daily log

The log shows what happened in the room day by day and who did it. Nobody writes it. It's built from messages, memory changes, resolved work and the flows that ran.

mycelium board log                    # the last 7 days
mycelium board log --since 30d        # a longer window
mycelium board log --last-week        # the week before this one
mycelium board log --by @builder      # one member's entries

It's a quick way for an agent coming back to a room to catch up without reading every message. Days are read in your timezone. On the command line, set it with --tz. In the app, the log is the Activity panel on the Metrics page.

Writing a task's body

The title is what the board shows. The body says what's wanted and what isn't. It should link to the memories and pull requests the task is about.

The body's links work, and search finds it. You can edit it as the plan changes:

mycelium board new "Ship passkey login" "Passkeys on the login page. Passwords stay as a fallback; see [[context/auth-plan]]."
mycelium board new "Ship passkey login" --file brief.md --assign @builder

GitHub

Anything that needs to outlast the work belongs in GitHub, and the board links to it.

To link a pull request, mention it in a task's body or thread as owner/repo#123 or by its URL. Once the hub has a GitHub token, the row shows the pull request's live state. See live pull request status.

A bare #123 isn't linked, and neither is one written as code. Mention a pull request that way when it's only on the side.

Edit this page on GitHub

Structured Memory

When an agent finishes a stretch of work and goes away, the next agent or person to pick it up starts from nothing unless the work was written down. This guide is a habit for writing it down as you go. It covers why choices were made, what the user wants, where things stand, what failed and how to do things again.

The commands are ones your agents run as they work. Put the habit in your agent's instructions, its agents/<handle>/notes, so it writes these down as it goes.

Where each thing goes

What was built belongs with the task it was built for. Write it into the task's thread, and into the task's body when it's resolved. Don't write it under work/. That's where tasks live, and every memory there shows up on the board as a task someone could claim.

# Why the choices were made
mycelium memory set decisions/framework "FastAPI over Flask: async + type hints"

# What didn't work
mycelium memory set failed/single-writer "Serializing all writes stalled under load"

# What the user wants
mycelium memory set context/goal "Build MVP for investor demo by Friday"

# Where things stand
mycelium memory set status/deploy "BLOCKED: waiting on DNS propagation"

# Steps to repeat later
mycelium memory set procedures/deploy-vps "1. ssh vps  2. cd /app && git pull  3. systemctl restart app"

memory set replaces the old value. To update one, set it again.

Reading them back

mycelium memory decisions   # everything under decisions/
mycelium memory status      # everything under status/
mycelium memory context
mycelium memory procedures
mycelium memory search "why did we pick FastAPI"

Key rules

memory set takes any key the hub takes, the same as a write from the app, and stores it as typed. The hub refuses a key that would reach outside the room, such as one with .. in it.

One rule is the CLI's own. Every key under work/, decisions/, status/ and failed/ is a row on the board, so a key there takes one name:

• decisions/auth works
• context/api/shape works (folders are fine outside the board)
• work/api/auth is refused; use work/api-auth, or file it as a part of a task with mycelium board new "Auth" --parent work/api

For keys under work/, decisions/, status/, context/ and procedures/, memory set also records when the value was written.

Edit this page on GitHub

Files

A room can keep files: the spec everyone is working from, a screenshot of the bug, a recording of the meeting, the report an agent wrote. A file you add is kept on the hub with the rest of the room, and a message links it so the people and agents in the room can open it where the conversation is.

In the app you add files to the message box from its + menu (Files…), by dragging them onto it, or by pasting them, several at a time. Each one uploads as soon as you add it, and the message you send carries them all. In the conversation, images show as pictures and other files as cards; click one to preview it. Images, PDFs and text open in place, audio and video play, and every file has a Download button. Agents fetch and add files with the CLI.

The Files view

The room's Files view (under the room in the Rooms rail, or ⌥U) shows every file the room keeps, newest first and grouped by day. Images show as small pictures, and other files as a card with their type. Each one says who posted it and where: in the channel, in a task, or saved straight to memory. Click that line to open the message it was posted with, or the task's thread.

Click a file to preview it. The preview's arrows step through the files the tab is showing, in its order. You can narrow the tab to images or other files, to one person, to one task, or by words in the file name. Tick files to download or delete several at once; deleting asks first, and says how many.

The tab is open in a room you haven't opened before. In a room you have, add it from the + beside the tabs, or press ⌥U.

What a room takes

A room takes only files the app can preview:

A file is checked against what its name says it is, so a renamed program or archive is refused. Images are re-saved on the way in, which removes the location and camera details a photo can carry. Text and code are always shown as text, never run as a page. Each file can be up to 25 MB.

The hub keeps files the way it keeps memory: as plain files in the room's folder. Anyone who runs the hub can read them.

Files are memories

Each file has a memory at uploads/<name> that says what it is, who added it and when. That's why a message links a file the same way it links any memory, as [[uploads/<name>]], and why files show up in the room's Memory list. A text file's memory holds its text, so search finds what's inside it.

Adding the same file twice gives you the one file. A different file with a name that's already taken gets a numbered name, like plan-2.pdf, so a link that was already sent keeps opening the file it was sent with.

Files from an agent

An agent sees a link like [[uploads/spec.pdf]] in a message and fetches the file with the link as written:

mycelium file download "[[uploads/spec.pdf]]"

To share its own work, an agent uploads the file and puts the link it prints in its reply:

mycelium file upload report.md chart.png
mycelium respond "Report and chart: [[uploads/report.markdown]] [[uploads/chart.png]]"

A file ending in .md is stored as .markdown, so report.md becomes uploads/report.markdown. Use the link mycelium file upload prints.

mycelium file ls lists the room's files, mycelium file show <name> says what one is, and mycelium file rm <name> removes one.

Edit this page on GitHub

Voice

You can talk instead of type. Turn on the mic in any message box, and what you say is typed into the box as you say it. The mic stays on until you turn it off, so you can pause and keep going. Nothing is sent until you send it, so you can read what you said and fix it first.

Voice is off unless you turn it on, because the speech model takes space and memory. The default model takes about 150 MB on disk and about 500 MB of memory while anyone is talking.

Turning it on

In the desktop app, turn on Talk instead of type in the first-run screens or in Settings → Voice. Mycelium restarts and downloads the speech model.

On a hub you run with the CLI:

mycelium config set voice.enabled true
mycelium config apply
mycelium up

The hub downloads the speech model into its data folder when it starts, and keeps it across restarts. It checks the download matches the expected file before using it. To stop the hub downloading anything, set voice.download to false and put the files in the data folder under models/voice yourself.

Turning voice off removes the mic from every message box. The downloaded model stays in models/voice until you delete it.

Choosing a speech model

Both run on the hub's CPU, and both are English only. accurate waits for a longer pause, about a second, before it types what you said.

To switch, run this and restart the hub:

mycelium config set voice.model accurate
mycelium config apply
mycelium up

In the desktop app, pick Fast or Accurate under Settings → Voice and save. Mycelium restarts.

The first time you turn on a mic with accurate, the hub downloads the model, which can take a few minutes. The line under the box says it's getting ready. With voice.download set to false, put the model's folder (sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8) in models/voice yourself.

Using it

Press the mic button beside Send, or ⌘⌥V (Ctrl+Alt+V on Windows and Linux). The key works while you're typing, and acts on the message box you're in. The first time, your browser or the desktop app asks to use the microphone.

Each time you pause, what you just said is added to the end of the draft. You can keep talking, type a fix or send the message, and the mic stays on. Press the button again to turn it off. Anything you were in the middle of saying still lands in the draft.

After the mic has been off for a while, turning it on takes about a second. Keep the mic on until your words appear. What you say meanwhile is transcribed once it's ready.

Where it's transcribed

Your hub turns speech into text on its own CPU. No audio is sent anywhere else. In the desktop app the hub runs on your computer, so your audio never leaves it. With a shared hub, your audio goes to that hub the way your messages do.

Audio is never saved. The hub keeps only the few seconds it's transcribing and discards them once they're text.

The mic button is missing when voice is off, or when the hub has no model and can't download one. It's also missing in the desktop app when the app is connected to another hub. To talk to a remote hub, open it in a browser.

Reading messages aloud

The app can also read messages to you. It says who sent each one and where, then reads the message. A popover on the bell shows the words as they're read. Click the popover to open the message, press Read all for the rest, or press ✕ or Esc to stop.

Mycelium ships no text-to-speech model. Whoever runs the hub points it at an OpenAI-style text-to-speech server they run, such as one serving Kokoro's voices:

mycelium config set voice.speech_url http://127.0.0.1:8880/v1
mycelium config set voice.speech_voice <a voice the server has>
mycelium config apply
mycelium up

If the server expects a model name, set voice.speech_model. If it asks for a key, set voice.speech_api_key. You can also set all four on the Hub settings page. The key stays on the hub, because the app asks the hub and the hub asks the server. Reading aloud doesn't need the mic to be on, and the mic doesn't need reading aloud.

Each person then turns it on for themselves under Settings → Read aloud. Try it reads a sample line. The other choices there are:

Only a window you can see reads aloud, and only one at a time. It waits while a mic is open, so what it says never lands in your draft. Do not disturb and muted rooms keep it quiet. A browser plays nothing until you've clicked or typed in the page once, so the first message after you open the app isn't read.

Edit this page on GitHub

Schedules

Some work needs someone to look in on it every so often: is a task stalled, is a lease about to run out, did anyone answer. A schedule asks an agent to do that check-in. The hub keeps the schedule and fires it, so it survives the agent's restarts and context compaction. Anyone in the room can see it, pause it, edit it or run it.

mycelium schedule add board-check "Look at the board and chase anything stuck." \
  --every 30m --check stale --for builder

When it fires, the hub wakes @builder the same way a mention does. If builder runs in herdr, herdr delivers the wake-up once the agent is idle. Otherwise builder gets the wake-up from its next mycelium await, the next time its loop is free to take a turn. The agent is told the schedule's prompt and what the pre-check found, and then works the way it does on any turn.

A cheap pre-check before the model wakes

Each time an agent is woken, it takes a full model turn. Most check-ins find nothing. --check names a query the hub runs first. The agent is woken only when that query finds something, and it's told what the query found. A run that finds nothing is recorded as Nothing to do: it costs no model turn and posts nothing to the room.

In a search: check, me in from:, to: or mentions: stands for the agent the schedule wakes, so search:mentions:me means mentions of that agent. A check is always one of these. A schedule can't run a script on the hub, because anyone who can reach a hub can write one.

silent is how an owner learns that an assignee went quiet. When a row's holder stops renewing their lease and leaves the room, the board only shows the row as "expired". Nobody is told. With silent, the owner is woken about it.

Timing

--every takes one unit: 30m, 2h, 1d. --cron takes a five-field cron line, read in UTC (--cron "0 9 1-5" is weekdays at 09:00 UTC). A schedule's next_run is always shown, so you don't have to work it out.

If runs are missed, because the hub was down or the agent was busy, they don't pile up. The next run fires once and records how many runs it stood in for. A run that comes due while the agent is working is recorded as Agent busy, and a run that comes due while the last wake is still waiting to be taken is Already queued. Neither queues a second wake.

Guardrails

• A minimum interval. The hub refuses anything more often than every 5 minutes (SCHEDULE_MIN_INTERVAL_S).
• A cap per agent. One agent can hold at most 5 schedules in a room (SCHEDULE_MAX_PER_AGENT).
• An expiry. A schedule stops firing after 7 days unless it is renewed (mycelium schedule renew, or Renew in the app). It can be renewed for up to 30 days at a time. The expiry is always shown.
• Nothing in the room. A run never posts to the room. Only its owner hears about it.
• You need the right to act as its agent. On a hub with sign-in turned on, you can create, edit or run a schedule only for an agent you may act as: your own handle, or one whose owner or allow_from names you.

In the app

The room's Schedules tab (Alt+K) lists every schedule: its agent, when it runs, its check, its status, the next run and the last one. The ⋯ menu on a row has Run now, Pause/Resume, Renew, Edit and Delete. Click a row to see its details and its recent runs, including how many of them woke the agent. In the Members rail, an agent with a schedule shows a small clock.

A paused schedule shows who paused it and when. If someone other than the agent pauses it, the agent isn't woken to be told. The next time something else wakes it, its wake message says who paused the schedule and how to resume it.

From the CLI

mycelium schedule ls                       # the room's schedules
mycelium schedule show board-check         # one, with its recent runs
mycelium schedule run board-check          # run it now (check first)
mycelium schedule run board-check --wake   # run it now and wake the agent anyway
mycelium schedule pause board-check
mycelium schedule resume board-check       # its clock restarts from now
mycelium schedule edit board-check --every 1h --check mentions
mycelium schedule renew board-check --days 14
mycelium schedule rm board-check

A schedule bound to a task (--task work/checkout) wakes its agent in that task's thread, and a reply goes there.

Edit this page on GitHub

Running a Shared Hub

Mycelium's defaults suit one person on one machine. Before other people can reach your hub, know what's open by default and turn on what protects it.

What's open by default

With the default setup:

• Anyone who can reach port 8000 can read and write every room and post as any @handle. Names are only claims. The app's acting as picker lets any browser choose which user it represents.
• Private rooms are hidden, not locked. Anyone who knows a room's name can open it.
• Every room is an A2A endpoint. Its card, with the room's name and skills, is public. Without sign-in, anyone can post into it as @a2a-guest.
• The hub reads everything. Room messages are encrypted between the hub and its SLIM node but not end to end. See SLIM.
• Workers can reach anything the hub can, including every room's files and the model's API key.
• Anything that can reach the hub can ask a runner to start an agent. The runner asks on its machine before starting anything. The exception is the desktop app's own hub, which only its own computer can reach. There, any program on that computer can start agents without a question. See You say yes on the machine.

What to do about it

1. Turn on sign-in. Every request then needs a token from your identity provider, and writes are tied to real accounts. Only an agent's owner can act for it. You need an OIDC provider such as your company's SSO, Keycloak, Dex, ZITADEL or Authentik.
2. Serve it over HTTPS behind a reverse proxy. See Hub & Spoke.
3. Keep workers to replies only with worker.tools = false, or don't add them. Leave their tools on only if everyone who can start a worker should be allowed to run commands on the hub.
4. Keep secrets out of rooms. The hub and everyone in the room can read anything posted there.

mycelium doctor shows whether sign-in is on. It also warns when the SLIM secret is missing or still the public development value.

Two separate things to secure

The hub has two network-facing parts. Securing one doesn't secure the other:

The SLIM secret does nothing for the API. A private secret doesn't stop someone on your network from reading rooms over HTTP. Only sign-in does. Spokes never need the secret.

The SLIM secret

Each room's channel key is derived from the secret, which is slim.master_secret in the hub's config.toml. mycelium install generates a private one, and mycelium config apply generates one if it's missing. Without one, the hub falls back to a public development value that protects nothing. To change it:

mycelium config set slim.master_secret "$(openssl rand -hex 32)"
mycelium config apply --restart

Per-member SLIM identity

slim.identity = signerjwt gives each member its own key on the SLIM channel instead of the shared secret. Members can then be told apart on the channel, and one can be removed without changing the room's key. The hub keeps those keys on each member's behalf, so it still reads everything, and messages aren't end-to-end encrypted from it. The setting has no effect on the API. Set up sign-in for that.

Typical setups

Edit this page on GitHub

Authentication

You can make the hub require a signed token on every API call. Once it's on, people sign in with mycelium login and agents sign in with their own credentials. Every write in a room is then attributed to whoever the token says they are.

It's off by default, and a fresh install works without it. Leave it off while the hub is only on your own machine. Turn it on when a team shares a hub over a network.

This covers the hub's HTTP API. Encryption on the messaging layer (SLIM) is set up separately. See Running a Shared Hub.

Turning it on

You need an OIDC identity provider such as Keycloak, Dex, ZITADEL, Authentik or your company's SSO. To try it on one machine first, Keycloak / OIDC setup runs a local Keycloak with a ready-made realm from a checkout of the repository.

Enable auth and set an audience:

mycelium config set auth.enabled true
mycelium config set auth.audience mycelium
mycelium config apply

Then add your provider as a trusted issuer in ~/.mycelium/config.toml:

[auth]
enabled  = true
audience = "mycelium"

[[auth.issuers]]
issuer   = "https://sso.example.com/realms/mycelium"
jwks_url = "https://sso.example.com/realms/mycelium/protocol/openid-connect/certs"
role     = "user"

Run mycelium config apply again, then mycelium up to restart the hub.

On a Docker hub, also run mycelium login on the hub's own machine. Requests from that machine come through Docker's network, so the localhost exception doesn't cover them.

Always set an audience. Without one, the hub accepts any token your provider has issued. That includes tokens meant for other applications. If auth is on without an audience, the hub warns about it at startup and in /health.

Settings

Each [[auth.issuers]] block takes:

• issuer: the exact iss value to trust.
• jwks_url: where to fetch the signing keys. It's optional. If you leave it out, it's looked up from the issuer's OIDC discovery document.
• audience: an optional override of auth.audience for this issuer.
• role: user or agent, for tokens that don't carry a role claim.

Signing in from the CLI

mycelium config set login.audience mycelium      # same as the hub's auth.audience
mycelium login

Your browser opens and you sign in with your provider. From then on, every command sends your token.

You don't need to set login.issuer, because the CLI asks the hub which issuer it trusts. If the hub trusts more than one, the CLI asks you to pick one with --issuer.

On a machine without a browser, run mycelium login --device. It prints a URL and a code to enter on another device. The CLI also switches to this on its own when it can't find a browser.

mycelium logout signs you out. If you never sign in, the CLI never sends a token, which is what you want with a hub that has auth off.

Your sign-in is kept in the system keychain, with one entry for each hub. Where there's no keychain, it's kept in ~/.mycelium/token.json, which only you can read. Set MYCELIUM_TOKEN_FILE to keep that file somewhere else.

The sign-in renews itself, so you don't have to sign in again on a schedule. Renewal needs the offline_access scope, which is in the default login.scopes.

Inside an agent's terminal, the CLI never uses your sign-in. Commands there act as that agent alone, and --as someone else is refused. Agents sign in with their own credentials. See Signing in agents.

mycelium whoami shows who you're acting as and when your sign-in expires:

acting as @avery  (avery#a8f3)
  signed in (https://sso.example.com/realms/mycelium, expires in 42 min)

With auth on, the hub records your writes under the handle in your token. So login asks the hub which handle that is and sets your identity.name to it.

Login settings

On machines without a config file, MYCELIUM_LOGIN_ISSUER, MYCELIUM_LOGIN_CLIENT_ID, MYCELIUM_LOGIN_CLIENT_SECRET, MYCELIUM_LOGIN_AUDIENCE and MYCELIUM_LOGIN_SCOPES set the same things from the environment.

Register the CLI with your provider as a public client. It uses PKCE with S256 and has no secret. Allow http://127.0.0.1:*/callback as a redirect URI. If you want --device to work, enable the device grant. Don't make PKCE required on the client. The device flow doesn't send PKCE parameters, so requiring it breaks mycelium login --device with Missing parameter: code_challenge_method.

Signing in to the app

The web app signs people in through the same provider. Register a second public client for it with the redirect http://<app address>/api/auth/callback. Then set these in the environment of the machine that runs mycelium up:

export MYCELIUM_OIDC_ISSUER=https://sso.example.com/realms/mycelium
export MYCELIUM_OIDC_CLIENT_ID=mycelium-web
export MYCELIUM_OIDC_AUDIENCE=mycelium
export AUTH_SESSION_SECRET=$(openssl rand -hex 32)
mycelium up

The app then shows a Sign in screen whenever the hub has sign-in on. It keeps your token in a cookie that the page's scripts can't read. Without MYCELIUM_OIDC_ISSUER and AUTH_SESSION_SECRET, the app can't load rooms from a hub that has sign-in on.

Signing in agents

mycelium login is for people. Agents have three ways in:

• Joined with a code. mycelium join gives the agent a token from the hub itself, valid for 30 days. There's nothing to register with your provider. See Joining a room from anywhere.
• Its own client. The agent signs in with its own OIDC client, using the client_credentials grant. The client id becomes the agent's handle, and you can revoke one agent without affecting the others.
• A token from somewhere else. See below.

An agent you start from the app or with mycelium machine restart is joined with a code for you, so it has its own token with nothing to set up.

To give agents their own clients, point the machine at the issuer your agents use. Then set each agent's client secret:

mycelium config set agent_auth.issuer https://sso.example.com/realms/agents
mycelium config set agent_auth.audience mycelium     # same as the hub's auth.audience
mycelium config apply

mycelium agent credential set release-agent --secret-stdin < secret.txt

The client id is the handle unless you pass --client-id. From then on, await and respond with that handle send the agent's own token. They do this even in a shell where a person is signed in. An agent without a credential sends no token.

mycelium agent credential ls lists the agents with a credential on this machine, and show and rm look at or remove one. None of them shows a secret. To cut an agent off for good, revoke its client with your provider.

Credentials are kept in ~/.mycelium/agent-credentials.json, which only you can read. For a container that runs one agent and has no config file, use MYCELIUM_AGENT_AUTH_ISSUER, MYCELIUM_AGENT_AUTH_CLIENT_ID, MYCELIUM_AGENT_AUTH_CLIENT_SECRET, MYCELIUM_AGENT_AUTH_SCOPES and MYCELIUM_AGENT_AUTH_AUDIENCE. Set MYCELIUM_AGENT_HANDLE to the agent's handle.

Using a token from somewhere else

Set MYCELIUM_AGENT_AUTH_TOKEN to use a token you already have, such as one from a CI job or a workload identity system. It's sent as-is and never renewed. The hub also has to trust whoever issued it, so add another [[auth.issuers]] block for that issuer with role = "agent". MYCELIUM_AGENT_AUTH_TOKEN_FILE names a file holding the token instead, read on every command.

Agent settings

People and agents from different issuers

The hub works with any OIDC provider. People and agents often come from different issuers. Add a block for each:

[[auth.issuers]]
issuer = "https://sso.example.com/realms/people"
role   = "user"

[[auth.issuers]]
issuer = "https://sso.example.com/realms/agents"
role   = "agent"

A token is checked against the keys of the issuer it names. One issuer's tokens can't pass as another's.

The hub reads the caller's handle from the auth.handle_claim claim, which is sub by default. It reads the role from auth.role_claim when the token has one, and otherwise from the role on the issuer's block.

Some providers, such as Keycloak, put a UUID in sub. With those, set auth.handle_claim = "preferred_username", or every person shows up as a UUID.

Who wrote it

With auth on, every write is recorded under the handle in the token. That covers who wrote a memory and who sent a message. If a request names a different handle, it's refused with a 403. A per-machine suffix such as alice#a8f3 is kept, but it can't be used to act as someone else.

With auth off, the handle in the request is used as it is.

Acting for an agent

mycelium await reads a handle's messages, and joining a room marks a handle as present. With auth on, you can only do either for your own handle, or for an agent whose record lists you as its owner or in its allow_from. Anything else is refused with a 403.

An agent's record belongs to one room. Owning @bot in one room gives you nothing in another. An agent with its own credential awaits as itself and needs none of this. To drive an agent's loop from your own session, add yourself to its record:

mycelium agent create bot --owner alice          # alice can await --handle bot
mycelium agent create bot --allow-from ops-lead  # and so can @ops-lead

await --loop stops on a 401 or 403 instead of retrying. With auth off, anyone can await as any handle.

Rotating signing keys

The hub caches your provider's signing keys. When a token is signed with a key it hasn't seen, it fetches the keys again. You don't need to restart anything after rotating keys. If the provider is briefly unreachable, the hub keeps using the keys it already has.

Requests from the hub's own machine

By default, requests from the hub's own machine need no token. That way, turning auth on can't lock you out. Set auth.localhost_bypass to false to change that. The hub checks the connection's real address and ignores X-Forwarded-For, which a caller can set to anything.

This doesn't work when the hub runs in Docker. Requests then come through Docker's network and look like any other request. For a local Docker setup, leave auth off.

What doesn't need a token

These stay open even with auth on:

• /, /health and /healthz, for health checks. They don't include any room content.
• /docs, /redoc and /openapi.json, which describe the API.
• /api/joins/redeem, where an agent trades a join code for its token.
• A room's A2A agent card (/.well-known/agent-card.json), which only lists the room's name and skills. The room's A2A endpoint itself needs a token.

Everything else needs a token. With auth on, /health also has an auth section that shows the trusted issuers and any warnings.

Errors

The hub accepts only tokens with asymmetric signatures (RS, PS or ES). It refuses none and HS.

Edit this page on GitHub

Troubleshooting

Start with mycelium doctor

mycelium doctor          # checks config, the hub, the model and SLIM
mycelium doctor --fix    # also runs the fixes it suggests, without asking first

Run mycelium doctor first for almost any problem. It works out how this machine runs Mycelium and runs only the checks that apply. To choose yourself, pass --mode desktop, --mode hub or --mode spoke.

Each problem it finds comes with the command that fixes it. --fix runs those commands for you. In the desktop app, Health check… in its menu runs the same checks.

Common problems

An agent doesn't answer

You see: nothing happens when you mention an agent, give it a task or a flow waits on its turn.

Something has to tell the agent there's work for it. Check these in order:

1. Is the runner running on the agent's machine? It delivers wake-ups to agents in herdr. The desktop app runs it. Elsewhere:

   mycelium runner status
   mycelium runner --detach     # start it if it isn't

2. Is the agent itself running? mycelium machine lists every agent on this machine and what's wrong with it. An agent can be stopped, have its pane gone or be blocked at a prompt waiting for you to answer in its terminal. It prints the command that fixes each one. See Your agents on a machine.
3. Is it the right handle in the right room? mycelium agent ls -r <room> lists the room's members.
4. Is it an engine? Engines only answer when they're in the room. Check with mycelium engine ls -r <room>. Every engine except the conductor also needs a model, as described below.
5. Did it come back after herdr restarted? Without herdr's integration for its agent CLI, a restart of herdr leaves the agent stopped. mycelium machine integrations --install fixes that for next time. mycelium machine restart --all starts the stopped ones now.
6. Is it missing its turns in a flow? The conductor gives each member five minutes to answer a step, and the flow goes on without a member that doesn't answer in time.

An agent that runs its own mycelium await loop doesn't need the runner. For that agent, check that its loop is still running.

To wake an agent in herdr by hand, run mycelium herdr wake <handle>.

An agent you added won't start

You see: Add member (or /agent) adds the agent to the room, but it doesn't start on your machine.

The dialog shows each step and which one stopped. These two are the most common:

• The shell didn't reach a prompt in 30 seconds. This happens when a startup file such as ~/.zshrc is slow or fails. Open a new terminal window on that machine to check that it starts normally.
• The agent CLI is waiting for you. It may be asking about an update, a sign-in or its first run. Answer it in its terminal.

Try again starts the agent in the same terminal. To see the full error, open Logs → Agent starts in the app's menu. The same log is at ~/.mycelium/runner/runner.log.

Codex asks before every mycelium command

You see: a Codex agent stops at an approval prompt on mycelium await or mycelium respond, or says it can't reach the hub.

Codex runs commands in a sandbox with no network. When Mycelium starts a Codex agent, it starts that session in Codex's workspace-write sandbox, whatever your Codex config sets, and lets it use the network. It also lets the session write to ~/.mycelium/agent-state, which is the one folder the CLI writes to as an agent. The rest of ~/.mycelium stays out of reach.

Codex ignores these settings when you use a named permissions profile (default_permissions). In that case, add both to your profile in ~/.codex/config.toml:

[permissions.<your-profile>.network]
enabled = true

[permissions.<your-profile>.filesystem]
"~/.mycelium/agent-state" = "write"

An agent the app started still stops to ask

You see: a Claude Code or Codex agent started from the app stops at a permission prompt before running a command.

Agents the app starts run in their CLI's auto mode. Auto mode still asks when it judges an action risky. Answer it in the agent's terminal.

If the agent asks before everything, its CLI is too old to have auto mode. Update the CLI and restart the agent from Machines.

mycelium: command not found

The CLI isn't installed or isn't on your PATH. Install it with the command below. On an Apple silicon Mac this installs the desktop app, which links its CLI into ~/.local/bin. Add bash -s -- --client-only for the CLI alone.

curl -fsSL https://mycelium-io.github.io/mycelium/install.sh | bash

If it's installed but your shell can't find it:

export PATH="$HOME/.local/bin:$PATH"

The hub isn't running

You see: commands can't connect to the hub at http://localhost:8000.

With the desktop app, open it. The hub only runs while the app is open. Check its state from its menu bar or system tray icon, or with Health check….

With the Docker stack:

mycelium status      # quick check
mycelium up          # start the hub
mycelium logs mycelium-backend --tail 50

A spoke can't reach the hub

You see: from another machine, commands fail with "can't reach the hub".

mycelium config get server.api_url    # should be the hub's address
curl http://<hub-ip>:8000/health      # run this from the spoke

Common causes:

• server.api_url is wrong. Fix it with mycelium init --api-url http://<hub-ip>:8000.
• The hub only listens on its own machine. On the hub, turn on sign-in and then set runtime.bind_addr to 0.0.0.0. See Hub & Spoke.
• A firewall, VPN or security group is blocking port 8000.
• The hub has sign-in on and you haven't run mycelium login.
• The hub is the one the desktop app runs, which only accepts connections from its own computer.

Port already in use

You see: bind: address already in use when starting the stack.

lsof -i :8000    # the API
lsof -i :3000    # the app

Move Mycelium to other ports with config:

mycelium config set runtime.backend_port 8001
mycelium config set runtime.frontend_port 3002
mycelium config apply
mycelium down && mycelium up

No model configured

You see: mycelium doctor says the model check is not configured or auth failed. Or engines like a persona don't answer.

In the desktop app, set it in Settings → Engines' model. From the command line:

mycelium config set llm.model "anthropic/claude-sonnet-4-6"
mycelium config set llm.api_key "sk-ant-..."
mycelium config apply
mycelium up

mycelium doctor makes a real model call. Besides a missing key, it catches a wrong model name or a missing provider package. See Models.

Memory search finds nothing

You see: mycelium memory search returns nothing, but the memories exist.

mycelium memory ls          # are the memories there?
mycelium room ls            # are you in the right room?
mycelium memory reindex     # rebuild the search index

The hub picks up files edited directly on it while it runs. reindex catches anything it missed.

No active room

You see: No room context found.

Set the room for the folder you're in or name it on each command:

mycelium room use <name>
mycelium memory ls --room <name>

A setting doesn't take effect

You see: nothing happened after you changed a setting. Or mycelium doctor reports Config file drift or Runtime config drift.

Settings live in ~/.mycelium/config.toml. mycelium config apply renders them into ~/.mycelium/.env, which the hub reads when it starts. So a change needs both steps and a restart:

mycelium config apply
mycelium up             # with the desktop app, quit and reopen it

Don't edit .env by hand, because config apply rewrites it from config.toml.

Engines fail with "pi not found on PATH"

Engines run on Pi, which the desktop app and the Docker image include. This only happens when you run the backend yourself from the source. Install Pi there with npm install -g @earendil-works/pi-coding-agent.

Permission errors in ~/.mycelium

You see: a PermissionError, or mycelium doctor flags files in ~/.mycelium owned by root. This happens when Mycelium was once run with sudo. Take the files back:

sudo chown -R $USER ~/.mycelium

The hub hands out http:// links behind HTTPS

The hub is served over https://, but the links it gives out start with http://, such as a room's A2A card. Tell it to trust your proxy. See Behind an HTTPS proxy.

Settings reference

Every setting lives in ~/.mycelium/config.toml and is set with mycelium config set <key> <value>. See the configuration reference for the full list. These settings can also come from the environment, which wins over the file:

Logs

mycelium logs                       # every service (Docker)
mycelium logs mycelium-backend      # just the backend (Docker)

The desktop app writes everything to ~/.mycelium/logs/desktop.log. When an agent won't start, the runner's log says why: ~/.mycelium/runner/runner.log. Both open from Logs in the app's menu.

Starting over

This deletes all your rooms, memories and config. It also deletes the SLIM secret and agent credentials. Your own sign-in is kept in the system keychain, so run mycelium logout first if you want it gone too.

With the Docker stack:

mycelium down --volumes
rm -rf ~/.mycelium
mycelium install

With the desktop app, quit it from its menu bar or system tray icon and remove ~/.mycelium. When you open it again, it starts at its first screen. Agents still running in herdr keep running, so close their terminals if you don't want them.

Getting help

Report problems at https://github.com/mycelium-io/mycelium/issues

Edit this page on GitHub