Documentation

Your first agent, then a team.

Murmello builds and runs teams of coding agents — Claude Code, Codex and OpenCode — each in its own virtual machine on your Mac, or in the cloud when you want it to keep going without your Mac. You talk to each one in the app, answer what it asks, and open its terminal when you want the keyboard.

1. Install and sign in

Download Murmello, open the DMG and drag Murmello to Applications. You need macOS 14 or later and an Apple silicon Mac. Open the app and sign in from the profile in the sidebar’s footer. The sidebar then shows Agents, Profiles, Teams, Skills, Connections, Credentials and This Mac, and below them your boards.

2. Connect your sign-in

In Credentials, connect the tool you use with your own account. Connect signs Claude Code in with your subscription, through its setup token, and Codex with your ChatGPT subscription, through its own login; Codex can also use an OpenAI API key. OpenCode takes an OpenCode Go key or a key from a provider it supports. Choose where it is kept: in Murmello’s vault, encrypted, so agents in the cloud and on your Macs can use it; or only on this Mac, in your Keychain, for agents on this Mac. A value is never shown again after you save it. Your tool’s account is separate from your Murmello plan.

3. Make a profile and start an agent

A profile is an agent’s definition. Make one in Profiles. Runtime picks the tool and its model; Instructions say how it works. What it may do sets each tool to Allow, Ask or Deny, and holds two switches: Root access, for system software on its own machine, and Work with other agents. Access picks the credentials it may use. Skills and Connections add what you keep in those libraries. Sleep says when an idle agent sleeps. Advanced holds startup commands and its network: Open internet, the default, or Only these addresses. If the tool can’t honour a setting, the profile says so.

In Agents, choose New agent, pick the profile and a location, and Launch. A cloud agent’s first start installs its tools, which takes a minute or two; later starts take seconds. Talk to it on its page. When it wants to run a command you said to ask about, it shows you the command with Yes and No, and macOS notifies you if you’re elsewhere. Switch the page from Chat to Terminal to work in its shell, then go Back to chat.

An agent with nothing to do sleeps after the idle time in its profile, five minutes unless you change it, and wakes when you write to it. A cloud agent asleep for 30 days is archived; Restore brings back its files and conversation. To stop an agent for good, choose End agent… in its menu.

4. Run agents on this Mac

Open This Mac and press Set up This Mac. Murmello adds a background item and downloads a Linux image of about 90 MB once. Each agent then runs in its own virtual machine on your Mac and uses no credits.

An agent on your Mac works either in a folder you grant in This Mac → Folders, read-write or read-only, or in a copy Murmello keeps for it. Murmello saves versions of the folder in its storage, so the agent can move to the cloud or be restored; read where your work lives first. The agent sees your edits as you make them, and only one agent at a time may write to a folder.

An agent on your Mac can reach the internet, but not your local network or your Mac’s own services.

5. Lay agents out on a board

A board is a canvas for agents that work together. Add one with New board in the sidebar. Each agent shows as its full chat card, so you can follow several side by side. Add a Terminal card, or a Web page card that shows an agent’s dev server as you work. An agent is on at most one board.

6. Save a team

On a board, turn on Connect agents and draw lines between them. A line lets one agent message another, give it tasks, or both ways. Without a line, an agent can’t reach anyone. A profile’s Work with other agents switch, on by default, is what lets its agents use their lines.

Save as team… keeps the profiles and their lines as a team, with a Lead and a short note of what it’s for. Add the team to a board later and Murmello starts one agent per profile. You talk to the Lead; it hands work to the others along the lines.

7. Add skills and connections

Skills and Connections each have a library: Explore shows what you can add, and My library keeps what you added. A skill is a set of instructions and files an agent can use. A connection is an MCP server that gives an agent more tools. Add one to a profile’s Skills or Connections section to give it to that profile’s agents. A connection’s server is run by whoever provides it, and it receives the agent’s tool calls and any token you give it. Publishing your own is coming soon.

8. Bring your code

Grant the project’s folder to an agent on your Mac, or connect GitHub in Credentials and use an agent’s GitHub… menu to import a repository, pull, or push a branch. Murmello reaches GitHub only when you ask, and pushes only fast-forward. You can also clone inside the agent’s terminal.

To try something on the side, Fork… an agent: the fork starts with its files and a fresh conversation. Merge it back with Merge into…; if both changed the same lines, Resolve conflicts shows both sides.

9. Move an agent

Use Move → Move to the cloud before you close the lid, and move it to your Mac again when you return. The agent’s files and conversation go with it and it carries on where it was. If a move can’t finish, the agent stays where it was and says so.

10. The command line

In a terminal, murmello works with your agents:

murmello ls
murmello run <profile> [--name <name>] [--local [--folder <path>] [--read-only]]
murmello move <agent> --to cloud
murmello attach <agent>

ls lists your agents and where each runs. run starts one from a profile, in the cloud or on this Mac in a folder already granted in Murmello. move moves one, --to local for this Mac. attach opens an agent’s terminal in yours; detaching leaves the agent as it was.

11. Speak your prompts

Enable dictation in Settings, choose a shortcut and grant the requested microphone and Accessibility permissions. Use your hold or toggle shortcut to dictate into an agent’s prompt, a terminal or another app. Hosted dictation sends audio for transcription; read how your data is handled.

Work through a real task

Keep Claude Code working with your laptop closedStart or move an agent to the cloud, close the lid and review the result. Give Codex an agent you can return toWhat a sleeping agent keeps, what saved versions hold, and how to bring work home.