# Mirasim Documentation > Mirasim is the team workspace for coding agents: run Claude Code, Codex and other agents side by side, work with your team, and keep it running in a team space. Team spaces are not yet available in mainland China, Hong Kong or Macau. ## Key facts - Workbench (local, free): a desktop app for macOS, Windows and Linux that runs CLI coding agents (Claude Code, Codex, Kimi Code, DSH, Pi, Antigravity, Qwen Code, ZCode, Grok Build and OpenCode) with your own accounts or API keys. Many projects and sessions side by side; switch agents mid-session and keep the conversation; sessions can @ each other. - Following sessions from the phone app (Android; iPhone via TestFlight) is part of the free local product; the phone can connect straight to your own computer. - Collaboration (channels, threads, comments, notes on artifacts, attribution) needs a team space, a computer attached to the cloud, or a shared account. It is not sold separately; it comes with team spaces. - Cloud (paid): team spaces on Linux or Mac, with 5 collaborator seats each (more can be added) and room for 100 observers. The team can share space credit and its own API keys. Git credentials are never stored in the space; the gateway fills them in per sender. - Team spaces are not yet available in mainland China, Hong Kong or Macau (the local workbench is not affected). - Pricing (https://mirasim.ai/pricing is authoritative): Free $0; Collaboration: $0 free (Your computer space: Your own Mac, Windows or Linux computer · tokens BYOK · follows your computer's uptime, runs on your own computer with your own API keys), $99 / 30 days (Lite space: Linux · 4 cores · 8 GB RAM · 50 GB disk (expandable), 50 credits on us), $169 / 30 days (Standard space: Linux · 8 cores · 16 GB RAM · 100 GB disk (expandable), 80 credits on us), $249 / 30 days (Pro space: macOS · Apple silicon · 10 cores · 16 GB RAM, 120 credits on us), each with one team space and 5 collaborator seats (extra seats $30 per person / mo); Free and Collaboration can both add token packs (credits, where 1 credit = $1 of model usage at API list prices; from $10, currently $1 buys 2 credits, for every model, and more can be bought separately any time); Enterprise: contact support@mirasim.ai. The plan on your own computer is free and the desktop app already supports it; the other plans are a one-time payment for 30 days and do not renew automatically. This file is the plain-text form of the full documentation, for models and scripts to read. The web version is at https://mirasim.ai/docs/quickstart ; Chinese at https://mirasim.ai/docs/zh/quickstart . ## 01. Quickstart Install Mirasim, complete first-run setup, and run your first session in a workspace. https://mirasim.ai/docs/quickstart ### Install Mirasim Mirasim is a desktop app for macOS, Linux and Windows. Get the installer for your computer from the Download page. 1. **Download the installer** — macOS needs macOS 13 Ventura or later. Choose the Apple Silicon installer for an M-series Mac, or the Intel (x86_64) installer for an Intel Mac. Linux ships as an AppImage or a .deb, x64 or Arm64, for Ubuntu 22.04 or an equivalent glibc distribution. Windows needs Windows 10 1809 or later; if SmartScreen shows a prompt on the first install, confirm it to continue. 2. **Drag Mirasim into Applications, then open it** — The first launch may ask you to confirm opening an app downloaded from the internet — choose Open. 3. **Verify the file (optional)** — Every release publishes SHA256SUMS for every public download. Compare your download against it before you open it. *Check a download against the release checksums* ```bash shasum -a 256 ~/Downloads/Mirasim-*.dmg # compare the hash against the matching line in SHA256SUMS ``` *What a release publishes* | Artifact | What it is | | --- | --- | | Mirasim--arm64.dmg | The macOS desktop app for Apple Silicon. | | Mirasim--x64.dmg | The macOS desktop app for Intel (x86_64). | | mirasim-.apk | Release-signed Android companion, Android 8.0+. | | Mirasim--linux-x86_64.AppImage | The Linux desktop app; a .deb ships beside it, each in x86_64 and arm64. | | Mirasim--win-x64.exe | The Windows installer; an arm64 build ships beside it. | | SHA256SUMS | Checksums for every public download. | Click the account card at the bottom left, then Version: it shows the version you are running, when it last checked, and whether a new version is ready. New versions download on their own; click once to install. Help is on the same page, with the documentation and Send feedback. Feedback can be sent anonymously, but anonymous feedback cannot be answered. ### The setup assistant on first launch The first launch opens a setup assistant before the workbench. Signing in is required and there is no Skip. Back works on every step after the first. 1. **Sign in** — Use GitHub or Google, or a code sent to your email, and agree to the Terms and the Privacy Policy. Once you are signed in, this step shows your plan, and you can redeem a code here. 2. **Install an agent** — Install Claude Code or Codex; one is enough. The assistant lists what this computer already has and installs what is missing. You can continue while it installs. 3. **Skills & plugins** — The skills, plugins and MCP servers already on this computer carry over as they are, and you can turn on Computer Use here. Change any of it later on the Plugins tab in Settings. 4. **Get started** — Opens the workbench. With a plan, agents run on the platform and use the plan's credit. On the free plan, agents run on their own accounts (Own). You can switch this later in Settings. > **If it asks you to sign in again later** > > When your sign-in expires, a prompt over the workbench asks you to sign in again; running sessions are not affected. ### Add a workspace and pick an agent 1. **Add a workspace** — Click Add workspace in the sidebar and choose a folder: an existing repository, or an empty directory. 2. **Choose the agent** — Claude Code, Codex or another installed agent. Existing sign-ins carry over. To install an agent, use Agent config. 3. **Choose the model and reasoning level** — Each session has its own model and effort. The picker groups models as Native and Your models. 4. **Decide on isolation** — Turn on worktree in the composer to run the session in a new Git worktree, based on the branch you pick. ### Run one real task 1. **Send a prompt** — Describe the result you want in the prompt box and send it. 2. **Watch and steer** — The transcript shows thinking, tool calls and results, and sub-agent work as they happen, with the usage for the turn. While it runs you can queue the next prompt, steer the current turn, or stop it. 3. **Review and commit** — Changes are made in the repository itself. Open Git on the right toolbar to read the diff, then stage and commit what you want to keep. - `⌘ K` — Command palette — jump to any session, run any workbench command, search every transcript - `⌘ N` — New window - `⌘ D` — Split a new pane to the right - `⇧ ⌘ E` — Open the file panel for this pane's workspace ### Other ways to use Mirasim Every surface connects to the same host, so a session started in one shows up in the others. | I want to… | Use | | --- | --- | | Stay in the terminal | The `mirasim` command that comes with the desktop app — `mirasim claude`, `mirasim codex` (chapter 20) | | Check in from my phone | The phone app, Android or iPhone (chapter 19) | | Keep work running with the laptop closed, or share it with my team | A team space (chapter 10), and its members and team chat (chapter 11) | | Script or automate the app | `mirasim ui-cli` — control the workbench from scripts (chapter 20) | *Once the desktop app has started* ```bash ~/.mirasim/bin/mirasim doctor # check the install and its environment ~/.mirasim/bin/mirasim claude # Claude Code, with its own TUI and auth ~/.mirasim/bin/mirasim codex # Codex, with its own TUI and auth ~/.mirasim/bin/mirasim ui-cli help # the scriptable control surface ``` ## 02. The workbench What each part of the workbench window does, and which chapter covers it. https://mirasim.ai/docs/workbench ### Every part of the window - **Left column** — The space you are in, search (⌘K), and your workspaces and sessions (chapter 04). - **Pane area** — Sessions, documents and terminals side by side, grouped into layouts (chapter 08). - **Composer** — Where you send, queue and steer prompts, and pick agent, model and reasoning level (chapters 05 and 13). - **Right toolbar** — Git, files, artifacts and schedules, plus collaboration, members and notifications (chapters 09, 11 and 16). - **Account card** — Bottom left: your account, credits, version and settings. *The window, region by region* ### Left column, account card and right toolbar The main window has no title bar. The space you are in and the window's search sit at the top of the left column; your account is the card at the bottom left; tools, people and notifications are on the toolbar along the right edge, which is always shown. *The space menu, at the top of the left column* - **Space ⌄** — Click the space's name to open the space menu: the current space, Space settings, Space credit, Recent, and All spaces. All spaces lists every space; click one to go there, or use Add a space at the top. - **Search ⌘K** — The command palette: jump to any session, workspace, file or command by name. - **Sidebar ⌘B** — Collapse or bring back the left column. - **Computer Use preview** — Shown next to Search while an agent operates a browser or emulator: a live view of it. - **You** — Your avatar, name and email. Opens Settings › Account. - **Usage** — How much of each agent's subscription and of the platform credit is used. Click a row for its details. - **Version** — The running version, updates, help and feedback. - **Settings** — Agents, models, plugins, network and the rest of the app's settings. Git, Files, Artifacts and Scheduled tasks open in one panel beside the right toolbar, showing the workspace of the current session. Opening one replaces the one showing; click the same button again to close it. - **Git** — Diffs, staging, commits and branches for this workspace. - **Files ⇧⌘E** — The file tree, with Git status shown on each row. - **Artifacts** — What runs produced: builds, screenshots, logs, exports and evaluation reports. - **Scheduled tasks** — The prompts that run on a clock (chapter 17). Things the team needs to follow up on are items in Collaborate (chapter 11). - **Remote desktop** — See and operate this space's screen. Shown only on spaces that can share their screen. - **Running pages** — The web pages this space is serving, ready to preview. Shown only when there are any, with their count. - **Collaborate ⇧⌘M** — Open or close the space's chat in this window (chapter 11). - **Member avatars** — The others in this space right now. Hover for a person's card; click to open Space settings › Members. - **Member settings** — Opens Space settings › Members. Shown in team spaces and on computers attached to the cloud. - **Notifications** — Things waiting on you: approvals, mentions in other spaces, and being added to a space. - **Appearance** — Theme, language, text size, motion, window mode and density. ## 03. Core concepts What a host, workspace, session, pane and group are. https://mirasim.ai/docs/concepts ### Three layers: workbench, team, cloud Mirasim has three layers: - Workbench (local, free): the desktop app. Run several agents at once in split panes and groups, each session in the project folder or its own worktree, with files, diffs, terminals, Git and artifacts beside it. Following sessions from the phone app is included. - Team: channels, threads, comments and notes on artifacts, with each turn showing who sent it. Available in team spaces, on computers attached to the cloud and on shared accounts, at no separate charge (chapters 11 and 12). - Cloud (paid): team spaces on Linux or Mac that keep running when your laptop is closed. Each space has 5 collaborator seats (more can be added) and room for 100 observers; the team can share space credit and its own API keys (chapter 11). Team spaces are not yet available in mainland China, Hong Kong or Macau (chapter 10). ### The host: where sessions run The host is where your agents run and where project files, Git worktrees, session history, artifacts and schedules are kept. Normally it is your own computer, started by the desktop app. The desktop app can instead connect to a macOS or Linux server you run yourself. A team space, or a computer attached to the cloud, is also a host (chapters 10 and 12). In the app each host is a space; switch between them from the space menu at the top of the left column. > **Switching hosts is not migrating** > > Phone pairings and schedules stay on the host where they were set up and do not move when you switch; for a manually added remote host, use an HTTPS/WSS address or a trusted network. ### A workspace is a folder you added The sidebar lists the folders you added as workspaces, and each one can be removed. A fresh install starts with an empty sidebar and an Add workspace button. If a session starts in a folder that is not on the list yet, that folder is added automatically. ### A session is one conversation with one agent A session is one agent with one model and one reasoning level, running in a workspace folder, or in its own Git worktree based on a branch you choose. Each session has its own transcript, prompt queue and terminals. - **Agent** — Claude Code, Codex or another installed agent, chosen per session. Which account an agent uses applies to all of that agent's sessions. - **Model + effort** — Picked per session from native subscription models and your own profiles. A queued prompt keeps whatever was selected when you sent it. - **Workspace + branch** — The folder it runs in, and the base branch it starts from. - **Worktree** — Optional: the session runs in a Git worktree on its own branch. - **Transcript** — Turns, thinking, tool calls, sub-agent work, plans, decisions — searchable, forkable, exportable. ### Groups, tiles, document stacks The workbench nests three levels: groups, tiles and document stacks. - **Group** — A whole scene, switched from the group strip above the panes (Each group keeps its own layout. A session can appear in several groups; closing a group closes only the view, and its sessions keep running.) - **Tile** — One box in the split tree: a session, a terminal, or a document - **Document stack** — Tabs, but only inside a document tile (Only documents stack into tabs; sessions and terminals always keep a tile of their own.) > **Opening a file never hides your agents** > > A document you open stacks into the document tile already on the stage; if there is none, it opens as a new column on the right, and the other panes narrow or re-flow without closing. ### Artifacts Builds, screenshots, logs, exports and evaluation reports stay on the host that produced them and can be previewed beside the session that made them. Files an agent delivers are listed as artifacts you can open, reveal in the file system, or download. ### Where things live on disk - **~/.mirasim** — Host state: settings (setting.json), session records and local usage data. - **/.mirasim** — Project configuration that can be committed with your repository: workspace skills and schedules.json. ## 04. Parallel sessions Run several agent sessions at once, switch between them, and see which one needs you. https://mirasim.ai/docs/sessions ### Running more than one agent Every session is a pane, and panes run at the same time. Each session has its own agent process, transcript and queue. ### Switching between agents without losing your place The sidebar lists your workspaces and their sessions. You can show only the current workspace or all of them, filter the list, pin sessions, and rename any session (clear the title to restore the automatic one). - `⌘ K` — Command palette: sessions, workbench commands, and full-text transcript matches in one list - `⌘ 1` — …through ⌘9 — jump to the Nth group (⌘9 is the last one) - `⌥ 1` — …through ⌥6 — focus pane N inside the current group - `⌘ ⌥ ←` — Cycle focus between panes (⌘⌥→ the other way) - `⌃ ⇥` — Cycle groups (⌃⇧⇥ backwards) In ⌘K, sessions waiting on you come first, then running ones, then the rest by recent activity. Typing searches session titles; from two characters on it also searches transcript text. Spaces separate terms that must all match, and "double quotes" keep a phrase together. Transcript matches are grouped by workspace. ### Reading a running session Each turn shows the agent's thinking, its tool calls and their results, any sub-agents it delegated to, and its plan. These are collapsed by default; expand them to see the detail. - **Thinking / tool calls** — The reasoning and every tool invocation with its result, expandable inline. Long output collapses with its character and line count. - **Sub-agents** — A delegated unit of work shown as its own block: the brief it was handed, the trail of what it did, the result it handed back. - **Plan** — The agent's own step list with live progress — how many steps are done, in progress, or not started. - **Live usage** — A per-turn line: how long the reply took, and the context used as a percentage and in tokens. - **Notes and status** — Give a session a status (Inbox, Active, Review, Done, Parked), record what it produced (Answer, Proposal, Implementation, Partial, Blocked, Conversation), and leave yourself a note. ### Knowing which session needs you Each session shows its current state. When a session has had no output for a while, it shows why. - **Running** — A turn is in flight. - **Needs you** — The agent asked a question, requested a permission, or needs a decision. Answer in place; the session does not restart. - **Queued** — Your next prompts are lined up behind the current turn. - **Stalled** — Nothing has moved for a while. The reason is shown: quiet for N seconds, a named tool still running, awaiting the model, or the process merely alive. - **Done / failed** — The turn finished, ended without a reply, or ended with an error. A group tab pulses when a session inside it is running, and pulses differently when one is waiting on you. ### Answering an agent mid-task When an agent needs a permission or a choice, the question appears in the session, numbered if there are several. Pick one of its options, type your own answer, or skip it. The agent continues from where it paused. From the command line: `ui-cli answer --prompt-id ID --action select|text|skip|cancel`. ### Context, compaction, and long sessions The ring beside the send button shows how full the context window is now, and each turn's footer shows what that turn used. When the window fills, the conversation is compacted (summarized to free room) automatically. To compact on demand, hover over the ring and choose Compact conversation, or run `/compact` from the composer's command list. The transcript records each compaction and how much it freed. ### Ending and cleaning up sessions Deleting a session lets you choose how much to remove. A deletion cannot be undone. - By default only the Mirasim record is removed. The agent CLI's own transcript stays, so you can still resume the conversation outside Mirasim. - "Also delete agent transcript" removes the agent's own jsonl / rollout files too, so the conversation is fully gone. - "Also remove this worktree" applies to a session that ran in one. Git refuses while the worktree has uncommitted changes. A running session has to be stopped before it can be deleted. To continue a conversation in the agent's own CLI, choose "Copy resume command" in the session menu. ## 05. Queues and steering Queue prompts, steer a running turn, cut the line, or take a prompt back, per session. https://mirasim.ai/docs/queue ### Queueing prompts Each session has its own queue. If you send while a turn is running, the prompt is queued with its position shown and runs when the current turn finishes. > **A queued prompt is pinned to its settings** > > It runs with the model and reasoning level selected when you sent it. Changing them afterwards only affects prompts you send later. ### Acting on a live session These actions apply to a running or queued session. They differ in what happens to the turn already in flight. - **Send** — Nothing — the prompt joins the back of the queue. - **Steer** — Nothing — the guidance is handed to the running turn and picked up at its next step. The transcript marks it as steered. - **Stop & run** — Stops it — the current turn is interrupted and this prompt runs next. - **Recall** — Nothing — takes a queued prompt back into the composer, where you can edit it. ### Managing the queue itself Drag queued prompts to reorder them, and recall the ones you no longer need. The same operations are available from the command line: *Queue control over ui-cli* ```bash # what is lined up behind the current turn mirasim ui-cli --port 4970 queue --session KEY # hand a queued prompt to the RUNNING turn mirasim ui-cli --port 4970 queue steer --session KEY --ref R # interrupt, then run this one next mirasim ui-cli --port 4970 queue jump --session KEY --ref R # take one back out, or move it up the line mirasim ui-cli --port 4970 queue recall --session KEY --ref R mirasim ui-cli --port 4970 queue move --session KEY --ref R --to 0 ``` ### The composer In the composer you can paste or drop images and files, reference project files, and run a skill or built-in command with `/`. Drafts are kept per session. ## 06. Branches, reruns and worktrees Fork a conversation, re-run or rewind a turn, and run parallel sessions in separate Git worktrees. https://mirasim.ai/docs/branches ### Forking a conversation Any reply in a transcript can start a new branch. The branch inherits the history up to that point, and the prompt you write becomes its first turn. 1. **Choose where to branch** — At the end of the reply right before the point you want to change, open ⋯ and choose "New session from here". 2. **Write the branch's first prompt** — The branch is a separate session. The original keeps running and keeps its history. 3. **Compare, then keep one** — The branch shows which session and turn it came from, and the parent lists its branches. Delete the one you do not keep. > **Not every agent forks** > > Where an agent does not support forking, Mirasim tells you. ### Re-running and rewinding turns "Re-run", in the ⋯ menu at the end of a reply, asks the same question again with that turn's own agent, model and reasoning level. Re-running an earlier turn drops the turns after it; the menu item says so. To change a message you sent, choose "Rewind" on it and pick whether to restore the conversation, the code, or both to before that message. The message goes back into the composer, where you can edit it and send it again. "Put in composer" fills the composer with a message without changing the conversation. ### Worktrees: parallel agents on one repository A session can run in its own Git worktree: a separate checkout on its own branch, so parallel agents in one repository do not edit the same files. `git status`, `git diff` and your own editor work as usual. Merging a session's work back is an ordinary merge; discarding it is an ordinary branch delete. 1. **Turn on worktree in the composer** — It sits beside the workspace and branch pickers. When you send, a new git worktree is created with an automatic name and the session runs in it. 2. **Pick the base branch** — The agent switches to it first; with worktree on, the new worktree is branched off it. 3. **Remove the worktree when you delete the session** — Deleting a session offers to remove its worktree too. Git refuses while uncommitted changes remain; commit or discard them first. ## 07. Session messaging Name a session with @ in your prompt, and the agent can read it, message it, or start a new session. https://mirasim.ai/docs/messaging ### What session messaging does Sessions are isolated from each other by default. Session messaging lets one session's agent read another session, send it a message, or start a new session that has its own transcript and keeps running after the current turn ends. ### How sessions get connected Connection is automatic. When you name a session with @ in your prompt, both ends are connected on the spot, effective on that same turn. A session an agent creates with `start_session` is connected too. Sessions that are not connected do not appear to other agents and cannot receive messages. ### Naming a session in your own prompt Type `@` in the composer and pick a session from the "Sessions" tab. Each row shows its title, the agent running it, and whether it is running, idle, or a terminal session. Picking one writes `@session[the session's name]` into your draft. Up to three sessions are expanded per message. A mention only names the session; Enter still runs a turn in the session you are in. Whether the agent reads the named session, messages it, or waits for it to finish depends on what you write around the mention. - “Read where @session[Login rework] has got to before we change anything here.” — the agent reads it and reports back. - “Tell @session[Login rework] that the field is now `tenant_id`.” — the agent writes and sends the message itself. - “Watch @session[Login rework] and tell me when that turn is done.” — the agent waits until that turn finishes. Click a mention in a sent message to jump to that session. If it has been renamed or deleted, Mirasim says it cannot find it. ### Tools the agent gets In a connected session, the agent gets these tools: *What each one is for* | Tool | What it does | | --- | --- | | list_sessions | Lists the connected sessions it can reach, with their state. Shows the current workspace by default; asked for all, it also lists other workspaces and your sessions in other spaces and on other computers. | | read_session | Reads a summary of another session's last four turns (up to 2KB) and whether it is still running. With the wait option it returns as soon as that session's turn finishes, or after five minutes reports that it is still running. | | send_session_message | Sends a message to another session, or replies to one it received. Up to 8KB of text; returns how the message was delivered. | | read_session_message | Fetches the full text of a message it sent or received, by the message's id. | | start_session | Starts a new session with a chosen agent, model, reasoning level and opening task. It does not block; the new session's reply comes back as a message. | ### How a message is delivered Delivery depends on what the target session is doing at that moment. *The target's state decides the delivery* | Target state | What happens | | --- | --- | | Idle, or its last turn has ended | A new turn starts there right away, with the message as the prompt. | | Running, on an agent that takes mid-turn input | It joins the running turn at the next step, without interrupting a tool call in progress. | | Running on an agent that does not, or waiting on a question to you | It is held until the next turn boundary, for up to five minutes, then expires with a notice. | | Not connected | Refused. | | A terminal (TUI) session | Can be read, but cannot receive messages. | A received message is shown with the session it came from, never as something you said. Click the source to jump to that session. If a message expires or fails to deliver, the sending session shows it. ### Limits and the message log - **Send rate** — A session can send up to 30 messages in a burst, then one more every two seconds. The same text to the same session within 30 seconds is dropped as a duplicate. - **Chain depth** — A chain of relayed messages stops at 24 hops. Any human input resets the count. - **Ping-pong breaker** — If two sessions exchange more than 12 messages within five minutes with no human input on either side, that pair is cut off and the interface shows it. Every message is recorded locally under `~/.mirasim/messages/`: who sent it to whom, the text, and how it was delivered. Files are split by month, kept 90 days, and never uploaded. *Reading the message ledger* ```bash # the last few messages this month, as they were recorded tail -n 5 ~/.mirasim/messages/msgs-.jsonl # everything one session sent or received grep '' ~/.mirasim/messages/msgs-.jsonl ``` ## 08. Panes, groups and windows Split panes, switch groups, open documents and terminals beside sessions, and the shortcuts for each. https://mirasim.ai/docs/layout ### Splitting the stage Split the stage right or down. Each pane holds a session, a terminal, the workspace panel or a document. Drag a divider to resize; double-click it to even the split. - `⌘ D` — New pane, splitting right - `⇧ ⌘ D` — New pane, splitting down - `⌘ W` — Close the focused document; when it was the last one, the tile; then the pane. Does nothing on the last pane - `⇧ ⌘ ⏎` — Zoom the focused pane to the whole stage, and back - `⌃ `` — Flip the focused pane between chat and its agent's terminal UI - `⌃ ⇧ `` — Open a fresh standalone terminal pane ### Groups: several scenes, switched instantly Each group is a separate layout of panes. Start one with ⌘T, New group in the command palette, or Move to new group in a pane's menu. With two or more groups, the group strip appears above the panes; switching closes nothing. - A session can appear in several groups at once. - Closing a group closes the view only. Its sessions keep running and stay in the sidebar. - Each group tab shows what it contains, and pulses when something inside is running or waiting on you. - `⌘ T` — New group - `⌃ ⇥` — Cycle groups (⌃⇧⇥ backwards) - `⇧ ⌘ ]` — Cycle groups with the other hand (⇧⌘[ backwards) ### Documents and terminals on the same stage Files, diffs and terminals open as tiles beside your sessions. A pane can hold several tabs, switched from the tab bar in its header. ⇧⌘T adds a tab; drag to reorder. A session in a hidden tab keeps running, with its transcript, scroll position and unsent message intact. Double-click a tab, or press F2, to rename it. Renaming a session's tab renames the session everywhere, including the sidebar; a terminal or blank tab's name stays on the tab. A terminal tab is named after the first command you run in it. A document opens in the current group: as a new tab in the existing document tile, or, if there is none, as a column on the right. The other panes stay on screen. A session pane can switch to its agent's own terminal UI, such as Claude Code's or Codex's. A standalone terminal pane is a shell in your workspace. Drag a file or folder onto any terminal pane to type its path, quoted. This works in agent terminal UIs and plain shells alike. ### More than one window The workspace panel (file explorer, search, source control, artifacts and terminal) can open as its own window, for example on a second display. Artifact previews can open in their own window too. - `⇧ ⌘ E` — Open the files and Git surface for the focused pane's workspace - `⌘ F` — Find within the transcript you are reading — next, previous, and a match count Groups, splits and open documents are restored when you reopen Mirasim. From ui-cli, `ui layout.set` applies a one-, two-, three-, four- or six-pane layout. ### The command palette ⌘K, or Search at the top of the left column, opens one search box over three things at once: your sessions, the workbench's own commands, and the full text of every recorded transcript. - Sessions — ranked by recency, opened as a pane on ⏎. - Commands — new session, split right, split down, close pane, zoom pane, theme, language, settings, the files surface. - Full-text matches — transcripts are scanned as you type, with progress and a hit count. Space splits terms; "quotes" match exactly. - `⌘ K` — Open or close the palette - `↑ ↓` — Move through results - `⏎` — Open the selected result - `⎋` — Close ## 09. Files, Git and terminals Browse and edit files, review and commit changes, search code and transcripts, preview artifacts and export conversations. https://mirasim.ai/docs/workspace ### The file tree, and file operations The explorer shows the workspace with Git state on every row: how many files changed inside a folder, which files are modified or untracked, and what Git is ignoring. Rows update when an agent writes a file. Right-click a row to open, open to the side, open with another app, reveal in Finder, copy the file, copy its path or relative path, cut, paste, rename, duplicate, move to trash, and create new files and folders. When a session's output folder differs from its project, the panel labels them: workspace is the session's output folder, project is the original code. ### Editing and navigating code Files open in a code editor with syntax highlighting. Markdown, JSON and other structured formats also have a view mode, a source mode, a split of the two, and a preview. JSON shows parse errors with line and column, and warns about comments and trailing commas. ⌘-click a symbol to jump to its definition, or look up the other places it is used. - `⌘ click` — Go to definition - `⌘ F` — Find in the current file or transcript - `⇧ ⌘ E` — Focus the explorer > **When an open file changes on disk** > > The editor asks whether to reload from disk or keep your version; save or close an edited file before restoring its Git changes. ### Reviewing and committing The source control panel shows staged and unstaged changes and a diff for every file. Diffs render side by side or inline. - **Stage / unstage** — Per file or everything at once. You can also discard a file's changes or delete an untracked file; both ask for confirmation and cannot be undone. - **Commit** — Commit staged changes, commit everything, or commit and push in one action, with the message written in the panel. - **Branches** — See the current branch, switch branches, and see how far ahead or behind the upstream you are, or that there is no upstream yet. - **Pull / push** — Pull and push from the panel. - **Restore** — Roll a single file back to HEAD, staged and unstaged changes together, after an explicit confirmation. When an operation fails, the panel names the cause, such as local changes that would be overwritten, diverged branches, no upstream, an unfinished merge or rebase, refused credentials or an unreachable remote. Where it can, it offers a fix such as stash-and-pull or pull-with-rebase. The repository is unchanged until you take the offered action. > **Keeping the behind count current** > > With "Check git remotes in the background" on in settings, Mirasim fetches watched repositories' remotes read-only so the sidebar's ahead/behind counts stay current; with it off, the panel notes the counts may be stale. ### Searching files and searching conversations ### In the code Filter the tree by filename, or search file contents across the workspace with match case, whole word and regular expressions, narrowed by include and exclude globs. Results are grouped by file with match and file counts, and truncated results are marked. ### In the transcripts ⌘K searches the full text of every recorded session, showing progress while it scans and how many sessions it covered. ### Previewing what the work produced Files an agent hands back are listed as artifacts and can be previewed in place: Markdown, JSON, CSV as a table, images with zoom, PDFs, audio and video. Previews are read-only; to edit, open the file in another app. A preview can fill the stage or sit as a side panel. - Open in your default app, choose a specific app, or reveal it in Finder. - Very long files preview their first several thousand lines; binaries, oversized files and unsupported media show what to do instead. - Only artifacts inside the workspace can be previewed. ### Exporting a conversation Export a whole chat, or a single round, to a folder with its text and the images and files that went with it. Progress shows while it packages. ## 10. Team spaces A hosted Linux or Mac environment where sessions keep running after you close your laptop and your team works together. https://mirasim.ai/docs/cloud-hosts ### What a team space is A team space is an environment Mirasim hosts for you. Its workspaces, sessions, terminals and files live there, so sessions keep running when you close your laptop, lose the network or switch devices, and every device sees the same thing. - **Lite** — Linux · 4 cores · 8 GB RAM · 50 GB disk (expandable). - **Standard** — Linux · 8 cores · 16 GB RAM · 100 GB disk (expandable). - **Pro** — macOS · Apple silicon · 10 cores · 16 GB RAM — for work that needs macOS or Xcode. - **People** — 5 collaborator seats per space for admins and collaborators (the owner takes none), plus up to 100 observers who take no seat. To add seats, write to support@mirasim.ai. Chapter 11 covers adding people. - **Models** — Platform models run on space credit or personal credit; shared API keys are billed by their provider — see “Models and credits” below. > **Not available in mainland China, Hong Kong or Macau** > > Connections to team spaces from networks in these regions are refused. The local workbench and the phone app are unaffected. ### Getting a team space Team spaces come with Collaboration: Lite, Standard and Pro run in our cloud and come with credits, and the plan on your own computer is free (chapter 12 covers attaching it). Prices are on the Pricing page (mirasim.ai/pricing). Your account has a team space allowance: how many of each spec you can create. Without one, “New collaboration space” under “Add a space” says “Your account has no cloud spaces available”; once all are in use it says “All available cloud spaces are in use”. For more members or more spaces, write to support@mirasim.ai. ### Create one 1. **Open the space menu** — Click the space name at the top of the sidebar. “All spaces” in the menu lists this computer, your team spaces, and any space or computer shared with you. 2. **All spaces › Add a space › New collaboration space** — “Add a space” asks where it comes from. “New collaboration space” is the one we host for your team; it shows how many you have left. 3. **Pick a spec** — “Collaboration space” or “Collaboration space · Mac”. A spec your account does not include says “Not enabled”. Once it is assigned, the team space appears in your space list. 4. **Set up its environment** — Once it is ready, this window opens its Space settings › Environment & sync: its spec and runtime components, Agents and sign-ins, and its workspaces. You can come back to it from the space's settings at any time. *Add a space: pick where it comes from* Under “Bring over from this computer”, “Sync” copies a local workspace up: its files, its sessions and the agents' memory. It is a one-time copy; the two sides do not sync afterwards, so move code between them with git. Credentials, `~/.ssh` and `~/.aws` are not copied. > **Nothing to install** > > Mirasim is already installed in a team space. The one-line install command is for a Linux server of your own (chapter 12). ### Opening it Click the space name at the top of the sidebar, then click a team space under “Recent” or on the “All spaces” page. It opens in its own window, or that window comes forward if it is already open. The window you clicked from stays as it was. The top of the sidebar shows which space a window is on. *All spaces, from the space menu at the top of the left column* - **Opened** — It has a window already; under “Manage spaces” its row also shows who is online and how many sessions are running there. - **Available** — Click to open it in a new window. - **Offline** — The team space cannot be reached right now. If the connection drops, the window reconnects by itself and the space menu shows when it will retry; “Reconnect now” tries at once. The team space keeps running while you are disconnected. ### Working in a team space A team space window is the same workbench as on your own computer — sessions, panes, files, Git, terminals — only everything runs in the team space. A few things are specific to it: - Coding agents such as Claude Code and Codex are already installed. Project toolchains are yours to install, from the team space's terminal. - Running pages: when an agent or your terminal starts a dev server, its localhost port is listed under “Running pages” on the tool rail at the right of the window — click to open it in the preview. A localhost link in a conversation opens in the preview too. - Remote desktop: “Remote desktop” on the same tool rail shows the team space's screen, for example for a browser sign-in inside the space. *A team space three people use. This session is Owen's: Lena can read it and fork her own copy* ### Pushing code as yourself Settings › Connections › Code hosting connects GitHub and GitLab. After that, agents and terminals in team spaces clone, pull and push as you. Each person connects their own account, and every git operation runs as whoever started it. ### Models and credits The team can use two kinds of models in the same space: - **Platform models** — Run on Mirasim credits. The credits that come with your plan go straight into the space credit and are shared by the whole team; anyone can add more from their personal credit, with 25% added on the way in. - **Shared API keys** — The owner or an admin connects any provider or relay under Settings › Model config. With “Share with members” ticked, everyone can pick it, billed to that key. Setting up agents, keys and credits for the team is covered in chapter 11. ### Where your data is - Workspaces, sessions and the team's chat are stored in the team space. - When a team space is reclaimed, everything in it is erased. Push code you want to keep to a remote repository. ## 11. Members and collaboration Add people to a team space or an attached computer, give them agents, models and credits, see who is doing what, and talk next to the sessions. https://mirasim.ai/docs/team ### Who can get in This chapter applies to team spaces and to your own computer attached to the cloud (chapter 12). Each has its own member list, and each member has one of four roles. | Role | Who | Can | | --- | --- | --- | | Owner | Whoever holds it: who created the team space, or whose computer it is | Everything. Only the owner appoints or removes admins. Cannot be demoted or removed, and cannot leave. | | Admin | Appointed by the owner; takes a collaborator seat | Also updates Mirasim there, installs and updates agents, configures models, adds people, moves them between collaborator and observer, and removes them. | | Collaborator | Takes a collaborator seat (5 per space; more can be added) | Uses everything there — workspaces, sessions, terminals. Cannot change credentials, models, agents or settings. Can leave. | | Observer | Up to 100 per space, apart from the seats | Follows sessions, files, members and chat, and can @ the assistant in a group. Cannot start or drive a session. Can leave. | ### Adding people 1. **Open Space settings › Invite** — Click the space name at the top of the sidebar › Space settings › Invite. Here you add people by email, share an invite link, and approve requests to join. The member list itself is Space settings › Members, which “Member settings” on the tool rail at the right of the window, or any face there, also opens. 2. **Enter their email** — They do not need a Mirasim account yet. Someone who has one is added straight away; anyone else gets an invitation email and joins automatically the first time they sign in with that address. Only the owner can invite someone as an admin. 3. **They find it in All spaces** — Signed in, they get a notification and the space shows up under “All spaces” in their space menu; it opens in its own window like any other. *Space settings › Invite* - When the 5 collaborator seats are full, Invite says “New people join as observers”; to add seats, write to support@mirasim.ai. An invitation not yet accepted holds a place in its role's count; pending invitations are listed under “Invited” with their expiry and can be withdrawn. - To let people join for a price, turn on Paid join under Space settings › Apps (see “Apps” below). - Changing someone's role reaches their open windows within 15 seconds. - Removing someone disconnects every window of theirs at once; they cannot come back unless added again. A member can also leave on their own: Space settings › General › Danger zone › “Leave space”. - The owner hands the space over from a member's role menu in Members, with “Transfer ownership”; it takes effect when they accept. - Space settings › Access history records who added, promoted, demoted or removed whom — from the moment the current owner got it. *Space settings › Members* ### Agents for the team Agents such as Claude Code and Codex do the work. In the space's window, Settings › Agent config is where the owner and admins install and update them and set the “Default agent”, its model and “Reasoning level”; new sessions start from there. Collaborators can switch agent and model in the sessions they start; observers only watch. > **A model the whole team can use** > > A subscription signed in to an agent serves the owner and admins themselves. To give everyone a model, share an API key or use space credit — both below. ### Sharing an API key 1. **Open Settings › Model config** — In the space's window. The owner and admins can change this page. 2. **Connect a provider** — Any provider or relay: enter its API address and key, then import the models you want. 3. **Tick “Share with members”** — New entries start ticked. For a key added earlier or imported, edit it, tick the box and save. 4. **Members pick it** — It appears in the model picker of every member's sessions. They use it without seeing its key or endpoint. - Turns on a shared key are billed by its provider and spend no Mirasim credits. Set spending limits in the provider's console. - In a team space, Member usage on the same page shows who used how much: admins see everyone, members see themselves. - A key is managed by whoever added it; everyone else can pick it but not change it. ### Space credit and personal credit Platform models run on Mirasim credits; 1 credit is $1 at API list prices. Credits come in two kinds: | Credit | Where it comes from | Who uses it | | --- | --- | --- | | Personal credit | Credits that come with a plan, and token packs | You | | Space credit | Credits that come with a space, and what members move in from their personal credit (25% added); never expires | Everyone in the space | ### Giving the team space credit 1. **Add credit** — Space settings › Space credit › Add credit. Any member can add from their personal credit, 10 credits or more: add 100 and the space gets 125. It then belongs to the space — it can't be moved back, and stays when a member leaves. 2. **Space credit is on by default** — Every space starts with space credit on. Only the owner can turn it off with “Turn on space credit”; the balance stays. 3. **Decide how it is shared** — The owner and admins set how much each member can use — see below. While it is on, each person picks Space or Personal under “Paying with”; Space is the default. Their turns draw on space credit first, and when their share is used up or the space runs low, a turn falls back to their own personal credit. While the space can pay, members need no credit of their own. ### Sharing and member caps | Sharing | What it does | | --- | --- | | No caps | Everyone shares the balance until it runs out. | | Fixed split | Splits today's balance evenly among today's members. For people who join later, or credit added later, use “Split again”. | | Periodic split | Hourly or daily, splits the balance at that moment evenly among all members. | You can also give one person a “Custom” cap. Caps count total use: someone who has used 30 and should get 20 more needs a cap of 50. ### Who is here, and what they are doing - On the tool rail at the right of the window, under Collaborate, are the faces of the other people here right now, up to five; the rest fold into +N. A small dot means they have a turn running; a dimmed face means they stepped away. - Point at a face for their card: role, device, last activity, the sessions they are running. Click it to open Space settings › Members with that person selected. - “Activity” in Space settings › Members opens “Who is doing what”, which draws who is running or viewing which session right now. ### Sharing sessions Every prompt a person sends is signed. In a session several people have written in, each of their messages carries the sender's name and avatar, and the session's row in the sidebar shows the faces of whoever asked in it. - **Private by default** — You can read anyone's session, but only its creator can send in it. To carry on yourself, use “Fork for me”; or ask the creator to turn on “Share with members” in the session's ⋯ menu, after which everyone can send there. - **One turn at a time** — While someone's turn is running, others can watch and send once it ends. The owner can stop another person's turn, after confirming. - **All / Mine** — A switch at the top of the session list. “Mine” keeps the sessions you created or have written in. - **Notifications** — On the phone, notifications that a session finished or is waiting for an answer are only for turns you sent. *Share with members, in the session's ⋯ menu* ### Collaborate: channels, DMs and threads Every team space and every shared computer has its own team chat, opened with “Collaborate” on the tool rail at the right of the window (⇧⌘M). It docks on the right of the window, or opens in a window of its own with “Open in window”. The messages are stored in the space or on the computer, so its agents can read them; while it is offline, its chat is unavailable. *Collaborate, docked beside the session* - **Channels** — Every team space and shared computer starts with the Lobby. Only the owner and admins create channels and change their members. - **Direct messages** — One to one. - **Session comments** — One room per session, holding the comments on its turns — see the next section. - **Threads** — “Reply in thread” keeps a side discussion off the main flow. Follow a thread and its new replies land in For you; when it is done, right-click it (long-press on the phone) and “Wrap up thread” — it stays readable and can still be replied to. - **For you** — @-mentions of you, replies to you, followed threads and keyword hits. @everyone and @here reach the whole room or whoever is online. - **Your own settings** — Per-room notifications (all messages, only @ and replies, or muted), Do not disturb with a daily schedule, keyword alerts, and exporting the chat history. ### Assistants @-mention an assistant in a chat and it starts a session in that team space (or on that computer) to do the work; the result comes back into the thread. An assistant is an agent with a name, a model, a default workspace and a chosen set of skills and MCP servers — the owner and admins create them under Manage assistants. When an assistant needs an answer, only the person who called it can give one. ### Between the chat and the sessions - Comment on a turn: hover a turn in a session and choose Comment; @ someone to pull them in. “Hand to agent” sends the comment into the session as a turn from you; “Resolve” closes it. - Share to chat…: post a session, or one of its turns, into a room as a card others can open. - Send to session…: from a message's ⋯ menu, hand the message to a session as its next turn. - Add as items…: from a turn's ⋯ in a session, pick the things to do out of that answer; from a message's ⋯, keep the message as an item — next section. ### Items: what the team has to do Items are the team's list of things to do, under the Items tab in Collaborate, on a team space or an attached computer. Each gets a number (T-1, T-2…). Write one in the line at the top of the list. In a session, a turn's ⋯ › “Add as items…” picks several out of that answer; a message in Collaborate can be kept as an item from its ⋯ too. Click an item to open its page: its fields, its sessions, its sub-items, its history, and a discussion you start only when you need one. An item stays in the list until you also post it to the room. - **Owner** — One owner, or none — then it waits to be claimed and anyone in the room can Claim it. Assign hands it over with an optional handoff note. - **Collaborators** — People doing it with the owner. They follow its thread and get the same status changes and questions. - **Status** — To do, In progress, In review, Done or Canceled — click the status icon at the front of the row to change it. Until someone sets one, an item a session has picked up reads In progress. - **Sub-items** — Two levels. Add them one by one, split them out of the description's list, or attach items that already exist; the parent shows how many are done. - **Sessions** — New session on the item's page starts one for it — yourself, or delegated to an assistant — with what it is for (Work, Research, Review, Compare or Split) and a first message already filled in from the item; the assistant's answer comes back into the item. Link a session attaches one that is already running. Each session shows its live state beside it, and an item added from a session turn keeps that session as its Origin. In the session, a line above the composer names the item it belongs to. - **Due date and milestone** — A due date turns yellow on the day and red once it has passed. A milestone groups items under its own due date and progress. Views across the top — All, Mine, Collaborating, Sent and Done, plus Milestones — cut the list by who it belongs to; Filter narrows it further and Views saves a filter you use often. Expand spreads the items across the window; switch from List to Board and To do, In progress, In review and Done become columns, so dragging a card to another column changes its status. On the phone you get the same list, status icons, sub-items and sessions, without the board. ### Apps: what the space offers outside Space settings › Apps lists everything this space offers to people and systems outside it, who need not join: the space page, its agents (reached over ACP from editors such as Zed or JetBrains), the pages and services you published, and API apps. Published pages, services and agents go through review before they are public; API apps take effect as soon as they are saved. Everything lives in the workspace's .mirasim/publish.json — edit it yourself, or ask an agent in a session: the built-in mirasim-publish skill writes it, previews it on this computer and shows you the result before anything is submitted. An API app lets an outside system — an alert, a webhook, a feedback form on your page, another tool keeping items in sync — send events into the space. This computer handles each event by rules, by an agent, or by your own service, and acts in the space only with the permissions you grant: create items, post to a room, notify a member, run an agent, take in a file, run a schedule. - **Access** — Token: an outside system calls it with an access token. Public: visitors to this space's live pages call it, no sign-in, a daily limit per visitor. - **Handling** — Direct (the caller uses the actions itself), Rules (a few fixed steps), Agent (a turn in a folder you choose, its instructions in AGENTS.md), or your own service on a local port. - **Permissions** — Nothing is allowed until you tick it. Messages can only go to the people and rooms the app names. - **Billing** — Only agent turns cost anything. Space credit with an optional daily limit (a public app spends the public wallet), or your own account. - **Event delivery** — When its items change or a task finishes, the space posts a signed event to the URL you give; Deliveries shows each attempt and can resend it. - **Access token, Call log, Test** — The token is shown once when you generate it — hand it to the other system yourself. The call log keeps 30 days. Test runs the app once on this computer, for real. > **It runs on the space's computer** > > When the computer is off, API apps pause and callers get an error; only item writes are queued until it is back. Paid join, also under Apps, sells a place in the space itself. Set a price, or just tell the agent in the space “charge 1 credit to join”, and you get a link. Visitors open it, sign in and confirm in Mirasim's payment sheet; the credits come from their own account. On a cloud space whoever pays joins at once, as a collaborator or an observer as you chose, and the credits go into the space credit. Nobody is charged while seats are full, and anyone who can't be added gets the credits straight back. On a connected computer a paid request still waits for your approval, and is refunded if you decline it, it is withdrawn, or 14 days pass. ### On the phone Sign in to the phone app with the same account and your team spaces are listed under Cloud. Connected to one, the phone has the same chat and the same members sheet, where admins can also promote, demote and remove people. ## 12. Attach your own computer Put your Mac, PC or Linux server on your space list, reach it from your other devices, share it with people you trust, and optionally its desktop. https://mirasim.ai/docs/attach ### Three sources to choose from “Add a space” offers three sources. They differ in where you can reach them from and whether other people can join. | Source | What it is | Reachable | Members | | --- | --- | --- | --- | | Team space | A space we host for your team; it runs even when this computer is off (chapter 10) | Any device, any time | Can invite | | Your own computer | Your Mac, PC or Linux server, on your list so you can reach it from elsewhere | Any device, while the computer is on | Can invite | | SSH server | A Linux or macOS server you manage yourself (chapter 19) | Only from this computer | Cannot invite | ### Attach to cloud 1. **On the computer you want to reach** — Sign in to Mirasim. In a window on this computer, click the space name at the top of the sidebar › Space settings › Remote access, and turn on “Attach to cloud”. “Add a space” › “Your own computer” has the same switch. 2. **Confirm** — While the computer sleeps or Mirasim is closed, it shows as offline. 3. **Reach it from anywhere** — On another computer or the phone, signed in to the same account, it is in the space list as “My computer” and opens in its own window. *This computer's Space settings › Remote access* *The confirmation before attaching* Turn the switch off at any time and the computer shows as offline; its space and members stay, and come back when you turn it on again. On a computer that will not attach, the switch says why: not signed in, the account's limit of attached computers reached, or attaching not enabled for the account. ### A Linux server without a desktop On a server without a desktop, one command installs Mirasim, signs in and attaches it. SSH into the server and run it in the server’s own terminal (not on your laptop or in a team space): *In the server’s terminal* ```bash curl -fsSL https://mirasim.ai/install.sh | sh ``` 1. **Install** — Installs the stable Mirasim command-line build, adding tar and xz with the system’s package manager if they are missing. 2. **Sign in** — Email and a one-time code, typed at the same terminal. Use the account you sign in with on your other devices. 3. **Run as a service** — With systemd it keeps running after you leave SSH and comes back after a reboot. Without systemd it runs as a background process; after a reboot, run the command again. 4. **Attach to cloud** — Sign in to the same account on your desktop or phone and the server is in the list, ready to share with members like any other computer. > **Run it as the user the agents should work as** > > Members you share the server with act as the system user that ran the command. Run as root, it installs a system service; run as a normal user, it installs a user service that keeps running after you log out. - **System** — An x86_64 Linux on glibc, such as Ubuntu, Debian or Fedora. ARM64, and musl systems such as Alpine, are not supported yet. - **Account** — Attaching has to be enabled for the account; to have it enabled, write to support@mirasim.ai. Until then the command says so, and once it is enabled the server attaches by itself within 10 minutes. - **A Linux with a desktop** — You can install the desktop app instead (AppImage or .deb) and turn on “Attach to cloud” there. Use one or the other on the same computer, not both. *Upgrade, check, remove* ```bash # run again: upgrade in place, the sign-in is kept curl -fsSL https://mirasim.ai/install.sh | sh # install and sign in, attach later curl -fsSL https://mirasim.ai/install.sh | sh -s -- --no-attach # is it attached? mirasim ui-cli --port 4939 machines attach status # detach, remove the service and the files (keeps ~/.mirasim) curl -fsSL https://mirasim.ai/install.sh | sh -s -- --uninstall ``` ### Sharing it with members Once attached, “Share with members…” under the switch opens this computer's Space settings › Members, which work exactly as in a team space (chapter 11); the people you add see it as “’s computer” in their space list. > **Share only with people you trust** > > Members run commands, read and write files and run agents on this computer as your current system user. - Members can pick the models you share with “Share with members”, billed to that key, and use space credit once you turn it on (chapter 11). The sign-ins on this computer stay for you and your admins. - You, and admins you appoint, get the same settings as at the computer itself, including its sign-ins and keys. ### Sharing the desktop (macOS) Under “Attach to cloud” is a second switch, “Share desktop”. With it on, anyone who can reach this computer can see its screen through “Remote desktop” on the tool rail at the right of the window, and control it with their keyboard and mouse. 1. **Turn on Share desktop and confirm** — They see everything on the screen, including your windows, chats and notifications. 2. **Grant Screen Recording** — So they can see the screen. 3. **Grant Accessibility** — So their keyboard and mouse work. Sharing starts once both permissions are on. ### Removing a computer from the list To remove an offline computer of yours for good: space menu › All spaces › Manage spaces, click its row to open its Space settings, and under General › Danger zone choose “Delete space”. Its members and space balance are erased and cannot be restored. If “Attach to cloud” is still on at that computer, it reappears the next time it comes online, so turn the switch off there first. ## 13. Organizations One account for your company: it owns the team spaces, shares one seat pool and one credit pool, and pays in one place. https://mirasim.ai/docs/organizations ### What an organization is An organization owns team spaces in place of a single person. Everyone joins with their own account, and one person can be in several organizations. Creating one is free; you pay when the organization first buys space slots. Organizations are managed on the website: sign in at mirasim.ai, open “My spaces”, and switch to the organization in the menu at the top left. *Organization roles* | Role | Can | | --- | --- | | Owner | Everything, including transferring and deleting the organization. | | Admin | Invites and removes members, manages every space in the organization, buys, and changes settings and domains. | | Billing admin | Buys, sees billing and usage, edits company details, and gives credits from the pool to spaces. Cannot create or manage spaces. | | Member | Sees the spaces they are in and, unless the organization turns it off, creates spaces from its slots. | Inside a space, people keep the space roles from chapter 11: admin, collaborator and observer. A member of the organization can be the admin of a space. *The overview, the first page of an organization* ### Creating or joining one 1. **Open “Create organization”** — In the menu at the top left of “My spaces”, or from “Create an organization yourself” on the Pricing page. 2. **Name and address** — Give it a name and an address (mirasim.ai/org/
: 3–40 lowercase letters, digits and hyphens), then click “Create organization”. You become its owner. 3. **Invite members** — Paste email addresses, pick an organization role and click “Send invitation”, or “Skip”. 4. **Move in your spaces** — Tick team spaces you own and click “Move in”, then “Go to the organization”. To join by invitation, open the link in the email, sign in with the address it was sent to, and click “Accept and join”. If the invitation names spaces, you are added to them too. Invitation links work for 14 days. Once an organization has verified its email domain, people who sign in with that domain see it under “My spaces” and can “Join” or “Ask to join”, depending on its settings. ### The organization's spaces An organization gets spaces in two ways: create one from a space slot, or move in a team space you own. “Spaces” lists every space it owns; members see only the ones they are in. 1. **Click “New space”** — At the top right of “Spaces”. 2. **Pick a tier** — Lite, Standard or Pro, each showing how many slots are left. 3. **Ask for credits if it needs them** — Under “Credits for this space”, the amount moves from the organization's credit pool to the new space when it is created. No approval; up to 10,000 credits; 0 asks for none. 4. **Create it** — You become the space's admin, and it opens in your browser. - A slot costs nothing more at creation. Each space brings 5 collaborator seats into the organization's seat pool. - Spaces created from slots have no end date. When the organization's slots expire it cannot create more, and the spaces it has keep running. - If the credit pool holds less than you asked for, the space is not created. *Create a space from a slot* “Move in my space” has two parts. A team space you own becomes the organization's: you stay on as its admin, its seats join the organization's pool, its old invite links stop working, and it cannot be moved back out yet. A computer you attached to the cloud (chapter 12) can be linked with “Link to organization”: it stays yours, the organization manages its members and seats, and the link ends when you leave the organization. The “⋯” menu at the end of a row has “Manage members” (change space roles, add people, remove them). Owners and admins also get “Enter as admin”, which adds them to any space in the organization without taking a seat; it is written to the audit log and the people in the space are told. “Close the space” releases it at once and clears what is on it; it cannot be undone. In the app, organization spaces are grouped under the organization's name in the space list, and “Manage on the website” in the space's settings opens that space in the organization's pages. ### Members 1. **Click “Invite”** — At the top right of “Members”. 2. **Paste email addresses** — Up to 50 at a time. 3. **Pick the “Organization role”** — Member, admin or billing admin. 4. **Optionally, “Also add them to these spaces”** — With a space role for each. The drawer shows how many seats this takes. 5. **Click “Send invitation”** — Each invitation comes with a link that works for 14 days. If the email does not arrive, copy the link and send it yourself. *Invite members* - “External collaborators”: people in the organization's spaces who are not members of it. They take seats unless they are only observers. - “Pending invitations”: copy the link or revoke it. - “Join requests”: people from a verified domain asking to join. Approve or decline. - “Remove from organization” also removes the person from every organization space, and their seat goes back to the pool. ### Seats and credits - The seat pool is 5 seats for each organization space, plus extra seats bought and any the platform gives. It covers every space. - Only admins and collaborators of an organization space take a seat, and a person in several spaces takes one. - Observers, members who are in no space, and people who used “Enter as admin” take none. External collaborators take one. - A space holds up to 25 collaborators. Credits the organization buys, including the credits that come with space slots, go into its credit pool and stay there when slots expire. In “Seats & credits”, the owner or a billing admin picks a space, enters an amount and clicks “Give”. A “Monthly budget” gives a space a fixed amount on the 1st of every month (UTC). *Seats & credits* ### Buying and renewing Owners, admins and billing admins buy in “Billing”. Each payment covers 30 days and does not renew by itself. | Item | Price | Each one gives | | --- | --- | --- | | Lite space slot | $99 / 30 days | 1 slot, 5 collaborator seats, 50 credits on us | | Standard space slot | $169 / 30 days | 1 slot, 5 collaborator seats, 80 credits on us | | Pro space slot | $249 / 30 days | 1 slot, 5 collaborator seats, 120 credits on us | | Extra seat | $30 per seat a month | One person across all of the organization's spaces | | Credit pack | From $10 | $1 buys 2 credits right now, into the credit pool | 1. **Set the quantities** — Slots per tier, extra seats and a credit pack. The total on the right lists what the organization gets. 2. **Continue to checkout** — Checkout opens in a new tab. 3. **Company details, the first time** — Owners and billing admins are asked for “Company details”, shown on orders and receipts. It can be skipped. 4. **Start using it** — When the payment page says it is active, everyone allowed to can create spaces from the new slots. *Buying slots, seats and credits* The overview warns you 7 days before the slots expire. “Renew for a month” buys the same slots and seats again, starting where the current ones end; credit packs are not bought again. Slots the platform gave you cannot be renewed. If you let them expire, existing spaces keep running, you cannot create new ones from slots, and the credit pool stays. For a contract, a purchase order or one invoice for the company, use “Contact sales” under Enterprise on the Pricing page. ### Settings, usage and audit log - **Basics** — Name, address and picture. Changing the address breaks links to the old one at once. - **Policy** — “Who can create spaces from slots” (all members by default, or owners and admins), whether people outside the organization may join its spaces, and the default agent and model for new sessions. - **Domains** — Add your company's domain, add the TXT record shown to your DNS, and click “Check now”. Then choose what happens to people who sign in with it: “Join automatically as members”, “Can ask to join” or “Nothing happens”. Public email domains such as gmail.com cannot be used. - **Transfer and delete** — Owner only. “Transfer ownership” to an existing member makes you an admin. To “Delete the organization”, close all its spaces first; orders are kept and it cannot be undone. - **Usage** — Owners, admins and billing admins. What the organization's spaces spent from their space credit since joining the organization, by space, member or model. “Export CSV”. - **Audit log** — Owners and admins. Invitations, role changes, payments, settings changes, space membership changes and “Enter as admin”, newest first, with filters and “Export CSV”. ## 14. Models, accounts and quota Set the model and reasoning level per session, use your own keys or local models, manage several accounts, and choose per session between your own accounts and Mirasim credit. https://mirasim.ai/docs/models ### Model and reasoning level are per session The composer has three pickers: agent, model and reasoning level. They apply to the current session only, so two panes can run different models side by side. *Pick the agent and model in the composer* The model list has up to three parts: the agent's own models first, then Built-in (models Mirasim provides, on platform credit), then Your models (the profiles you configured). Reasoning level is offered only for models that support it. > **Queued prompts keep their settings** > > A queued prompt runs with the model and reasoning level selected when you sent it. ### Which agent to run - **Claude Code** — Anthropic's coding CLI, with its own sign-in and terminal UI. - **Codex** — OpenAI's terminal coding agent, with its own sign-in and terminal UI. - **Kimi Code** — Moonshot AI's coding agent, running the Kimi K models. - **DSH (DeepSeek Harness)** — DeepSeek's agent harness, running DeepSeek V4 models; signs in with a DeepSeek API key. - **Pi** — A minimal terminal agent that runs the models you add in Model Config. - **Antigravity** — Google's agent CLI, running the Gemini models. - **Qwen Code** — Alibaba's open-source coding agent for the Qwen3-Coder models. - **ZCode** — The ZCode CLI agent, running GLM models or a model provider you configure. - **Grok Build** — xAI's coding agent, running the Grok models on your account. - **OpenCode** — An open-source coding agent that uses the providers you set up in OpenCode, plus free models that need no sign-in. If an agent is not installed yet, Agent Config installs it for you. Settings also shows each agent CLI's installed version next to the latest one. ### Bring your own keys Model Config has three layers: providers (an endpoint plus a credential), profiles (one model on a provider, with its reasoning level and token limit), and bindings (which profile an agent uses). Anthropic, OpenAI, Google and any OpenAI-compatible endpoint, including OpenRouter, are supported. *The same three layers over the CLI* ```bash # 1 · a provider: endpoint + credential mirasim ui-cli --port 4970 provider save \ --kind openai-compatible --name MyRouter \ --base-url https://example.com/v1 --api-key sk-… # 2 · a profile: one model on that provider mirasim ui-cli --port 4970 profile save --provider PROVIDER_ID --model some-model # 3 · a binding: route an agent through it, or back to its own subscription mirasim ui-cli --port 4970 model bind --agent codex --profile PROFILE_ID mirasim ui-cli --port 4970 model bind --agent codex --native # test a provider with one real call mirasim ui-cli --port 4970 model test --provider PROVIDER_ID --model some-model ``` ### The 1M-token window Some Anthropic models offer a one-million-token context window. To use it, choose the model's long-context variant, marked `[1m]`; it is never the default. Models without a 1M window do not show the variant. ### Local models Mirasim can run sessions on local inference: Ollama, plus `mlx-lm` on macOS. Other OpenAI-compatible local servers can be added as custom providers. Mirasim can detect what is installed, start a backend, and pull Ollama models with progress or delete them. *Local backends from the CLI* ```bash mirasim ui-cli --port 4970 local probe # what's installed mirasim ui-cli --port 4970 local start --backend ollama # bring it up mirasim ui-cli --port 4970 local pull --model qwen3 # Ollama pull, progress on stderr mirasim ui-cli --port 4970 local pulls # in-flight pulls ``` ### Several accounts, and live quota You can store more than one account per agent and switch which one is active. The active account applies to the whole agent, not to each session. Each stored account shows its live quota: the plan, remaining credits, how much of each current window is used, and when it resets. The state reads healthy, low or exhausted, and you can refresh it by hand. To see every agent's quota and your platform credit at once, open the account card at the bottom left › Usage. Click a row to see its details and switch accounts. *Accounts and usage headlessly* ```bash mirasim ui-cli --port 4970 accounts --fresh # accounts + quota each mirasim ui-cli --port 4970 usage # per-agent quota snapshots mirasim ui-cli --port 4970 account use --agent claude --id work-account ``` ### Own account or platform credit Each session runs on one of two routes: Own (your own accounts, API keys or local models) or Platform (Mirasim credit). The routes do not fall back to each other. When one runs out, switch the session to the other route. 1. **Set the default route** — In Settings › Traffic monitor › Model routing, or under the account card at the bottom left › Usage › Platform, choose Own or Platform. 2. **Override one session** — In the composer's model menu, set Quota source to Own, Platform or Follow global. It applies to that session only, from your next message. *Routes from the CLI* ```bash mirasim ui-cli --port 4970 login # sign in to Mirasim mirasim ui-cli --port 4970 relay # sign-in, credit and current route mirasim ui-cli --port 4970 config set relay.mode=local # default route: local = Own, cloud = Platform mirasim ui-cli --port 4970 session route --session KEY --to own # one session: own | platform | default ``` ## 15. Usage and cost Three ways to pay for models, and a ledger of every model call with tokens, cache hits and estimated cost. https://mirasim.ai/docs/usage ### Three ways to pay for models Every model call is paid one of three ways. Each session uses one, you can switch at any time, and one space can mix all three. | Mode | How to start | Who pays | | --- | --- | --- | | Your own account | Sign in to your Claude, ChatGPT or other subscription in the agent (chapter 14). | Your subscription; Mirasim charges nothing. | | Your own API key | Connect any provider or relay under Settings › Model config; in a space, tick “Share with members”. | The provider, billed to that key. | | Mirasim credits | Get a plan or a token pack, then pick a platform model in the session. | Personal credit or space credit; 1 credit is $1 at API list prices, across every model. | The ledger below keeps them apart: “Own vs platform” shows how the two routes split, with your own accounts and keys on the own side, and each platform call's “Paid by” says whether personal or space credit paid for it. > **A team needs no accounts of its own** > > The owner moves credit into the space (25% is added on the way in) or shares an API key, and everyone can start. Subscriptions signed in to an agent stay with the owner and admins. Chapter 11 has the steps. ### The traffic monitor Settings › Traffic monitor records every model call in one ledger. Pick a range: today, 7, 30 or 90 days, or custom. The page shows calls, tokens, cache hit rate and estimated cost for that range, each compared with the previous period. ### Finding where the money went The trend chart shows token usage over time, split by kind, agent or model. Click a legend entry to hide that series. The breakdown table covers five dimensions: agents, models, accounts, workspaces and sessions. Each row shows token share, calls, input, output, cache reads, hit rate, estimated cost and last activity. Click any row to add it to the page-wide filter. ### Down to a single call The call list shows calls newest first, with time, agent, model, status, duration and workspace. Select one to see its session, workspace, account, route, duration and size, token breakdown, reasoning tokens, cache hit rate and estimated cost. Export the current view to CSV. *The same ledger from a script* ```bash mirasim ui-cli --port 4970 traffic stats --days 30 --group-by model mirasim ui-cli --port 4970 traffic calls --hours 24 --limit 50 mirasim ui-cli --port 4970 traffic meta # ledger size on disk ``` ## 16. Skills, MCP and tools Manage skills, MCP servers and connectors, check your CLI tools, and turn on Computer Use for browsers and apps. https://mirasim.ai/docs/skills-tools ### Skills A skill is a named, reusable set of instructions, such as how to run your tests or how your deploy works. An agent loads it when the task calls for it. Type `/` in the composer to list your skills alongside the agent's built-in commands. Skills install at global scope (available everywhere) or workspace scope, stored under `/.mirasim`. *Managing skills* ```bash mirasim ui-cli --port 4970 skill list # workspace + global mirasim ui-cli --port 4970 skill install --source https://github.com/o/r --scope global mirasim ui-cli --port 4970 skill create --name run-our-tests --scope workspace mirasim ui-cli --port 4970 skill update --name run-our-tests mirasim ui-cli --port 4970 skill remove --name run-our-tests ``` ### MCP servers Add an MCP server as a local command or a URL, with its own environment variables, and its tools become available alongside the built-ins. Servers use global or workspace scope. The list shows both the servers Mirasim manages and the ones an agent brought itself. *Add, toggle and health-check a server* ```bash mirasim ui-cli --port 4970 mcp list mirasim ui-cli --port 4970 mcp add --name gh \ --command npx --arg -y --arg @some/mcp-server --scope global mirasim ui-cli --port 4970 mcp toggle --name gh --enabled false mirasim ui-cli --port 4970 mcp health --name gh # live handshake probe ``` ### Connectors Connectors are a curated catalog on top of MCP. Install one, give it its secrets or run it remotely, and enable it per agent. You can validate a connector against the live service and re-run its OAuth grant when a token expires. *Connector lifecycle* ```bash mirasim ui-cli --port 4970 connectors list mirasim ui-cli --port 4970 connectors install SOME_ID --mode remote --secret KEY=value mirasim ui-cli --port 4970 connectors enable SOME_ID --agent claude mirasim ui-cli --port 4970 connectors validate SOME_ID # records tool count / error mirasim ui-cli --port 4970 connectors auth SOME_ID # (re)start OAuth, prints the URL mirasim ui-cli --port 4970 connectors search "issue tracker" # the official registry ``` Connector search also queries the official MCP registry. ### The CLI tools already on your computer Mirasim lists the common developer CLIs on your PATH, such as git, gh and docker, and shows whether each is signed in. *What's installed, and what's signed in* ```bash mirasim ui-cli --port 4970 cli-tools # dev CLIs on PATH + auth state mirasim ui-cli --port 4970 clis # agent CLIs: version / latest / update available ``` ### Computer Use Computer Use is a tool called by the agent in your current session. Calls follow that session, including its model and account. Open Settings → Computer Use and turn it on; it is off by default. Enable the connections you want the agent to use, then describe the task in your session, such as checking a page or filling in a form. ### Browser connections - **Embedded browser** — Operate browser pages inside the local desktop workbench, including port and HTML previews. No extension or external browser is needed. Hosts without a local desktop shell show this connection as unavailable. - **Independent browser** — Operate a separate Chrome or Chromium with its own data folder. Manage opens the browser path, data folder and optional Copy your logins setting. Login copying is a one-time snapshot of a selected Chrome profile. - **Browser extension** — Operate your running browser through Browser Bridge, using its existing logins. Manage shows the connection status and installation instructions. Load the extension folder from ~/.mirasim/gui/extension through your browser's extensions page with Developer mode enabled. The three connections can be enabled together. Each keeps its own browser state and logins; copying logins affects only the independent browser. The agent selects a connection for each call. ### macOS apps Enable macOS apps and open Manage to check permissions. Accessibility is required to read controls and operate apps; Screen Recording is needed for screenshots and live preview. Follow the panel to grant them in macOS System Settings, then return to Mirasim to recheck. When the agent operates an app outside your always-allowed list, the session asks for permission, and allowing it covers the current task only. To stop being asked about an app, add it under Settings → Computer Use → Always-allowed apps; you can remove it there later. ### Electron apps Computer Use can also operate Electron apps that expose a renderer debugging endpoint. Start the target app with its debugging port enabled and give the endpoint to the session's agent. ### Live preview Turn on Live preview to watch the browser or app the agent is operating. The preview is read-only. Closing it hides the picture while the session keeps working; stop the task with the separate stop control or stop the session's turn. *Check and enable Computer Use* ```bash mirasim ui-cli --port 4970 computer-use mirasim ui-cli --port 4970 config set computerUse.guiAgentEnabled=true ``` ## 17. Schedules and goals Run prompts on a schedule, set goals the agent works toward, and find what is waiting on you. https://mirasim.ai/docs/orchestrate ### Scheduled prompts A schedule is a session prompt that starts itself on a clock, with the agent, model and reasoning level you choose. 1. **Create it in its workspace** — Open Scheduled tasks in the right-hand toolbar and choose New scheduled task; the composer turns into a schedule for the current workspace. Schedules are saved per workspace, in /.mirasim/schedules.json. 2. **Write the prompt and pick a frequency** — Write the prompt as you would type it. Pick a preset (Daily 9:00, Weekdays 9:00, Mondays 9:00, Hourly, Every 30 min) or write a 5-field cron expression in local time. The minimum interval is 10 minutes. 3. **Watch it, pause it, or run it now** — Each schedule shows its next run and run history, with a link into the session each run started. You can pause it without deleting it, or use Run now to trigger it immediately. > **Runs on this computer's clock** > > Schedules fire only while Mirasim is running, and missed runs are skipped. ### Goals Type `/goal` in the composer followed by a completion condition. The agent keeps working until it judges the goal met. If several checks in a row flag the same issue, use Convert to Goal to turn it into an orchestrated goal in the Goal room. There an agent splits the work into tasks, dispatches them, and comes back to you only when a decision is needed. The Goal room shows the master conversation on one side and, on the other, the spec it produced: the outcome, acceptance criteria, scope, boundaries, non-goals, decisions and assumptions, and open questions. The spec is read-only; change the goal in the master conversation. - **Aligning** — The orchestrator turns your conversation into a testable outcome and an execution map. - **Review → Confirm start** — Once the outcome, evidence and boundaries are set, you confirm a specific revision. Agent work starts only after that. - **Running** — Tasks run against the published map, with a mission graph and board, live status per task, and the critical path marked. - **Needs you** — Only decisions that change scope, safety, permissions, or an irreversible outcome pause progress. Each pending decision shows how many workers it is blocking. - **Acceptance → Complete** — Criteria are checked against evidence: each node carries its artifact, its verification and the worker record. Open any task node to see the artifact it produced, whether it was verified, its dependencies and dependents, and the work record of the agent that did it. ### What needs you - Sessions that stopped to ask you are collected under Waiting on you at the top of the sidebar. - When the window is not in front, a system notification fires when a session finishes, fails, stalls, or waits for you. Click it to open that session. - In Collaborate, For you collects every @ and reply addressed to you, including items handed to you. - The Items tab's Mine and Collaborating views list the open items you own or help with, grouped by status. ## 19. Phone, other computers and SSH servers Use Mirasim from the phone app, or open another computer or an SSH server as a space. https://mirasim.ai/docs/surfaces ### Every surface Mirasim ships - **Desktop** — The multi-agent workbench. macOS (Apple Silicon or Intel, macOS 13+) as separate DMGs; Windows as an installer and Linux as an AppImage or .deb, both in x86_64 and arm64. Goal boards are not available on Windows; the GUI pane is macOS-only. - **Android** — Paired companion for sessions, prompts, decisions, notifications and transcript images. Signed APK, Android 8.0+. - **iPhone** — The same companion on iOS, distributed through TestFlight: install TestFlight first, then open the invite from the download page. iOS 15+. - **CLI / TUI** — Launch Claude and Codex, run the server, manage accounts, run diagnostics and automation. Comes with the desktop app (chapter 20); a Linux server without a desktop gets it from the one-line install in chapter 12. ### The Android companion Install the signed APK and pair it with your computer. You can then read sessions, send prompts, answer questions and permission requests, and get notified when something needs you. 1. **Turn on remote access on the computer** — In Space settings › Remote access, turn on Over the internet, via relay, Direct on the same Wi-Fi, or both. If this computer has a public address, enter it under Advanced › Public address. 2. **Pair the phone** — Click Add device on the same page, then scan the code from the app or paste the connection code. The code contains the access token, so share it only with people you trust. Accounts in the phone's Settings switches which subscription account the conversations on that computer run under. The switch takes effect from the next turn. Add accounts on the computer. The phone can also update the computer it is paired with. Updating restarts the app on that computer, so the connection drops and then reconnects. Instead of scanning a code, you can sign in to the phone app with your Mirasim account and pick one from the list: your team spaces and attached computers are listed under Cloud. Chapter 11 covers what the phone shows once it is connected to one. When the phone temporarily cannot reach the computer, the link reconnects on its own. You do not need to pair again. ### Opening another computer Click the space name at the top of the left sidebar, then All spaces: every space you can open is listed there, and Open enters it in its own window. Add a space adds one from three sources: New collaboration space, Your own computer, or SSH server. To add another computer, open mirasim on that computer and go to bottom-left › Local › Remote access › Attach to cloud. To share this computer with a device, use Add device in Space settings › Remote access. The dialog shows a QR code and the connection code; Copy access token gives you the token on its own. Files, sessions, artifacts, paired devices and schedules belong to each space. Opening another space shows the ones there. ### A Linux or macOS server over SSH In Add a space, choose SSH server and enter the user name and server address. The server does not need Mirasim installed beforehand, and no ports need to be opened on it. Closing the window leaves the agents on that server running. - Sign in with your SSH agent, a password, or a private key. The agent option uses your ssh-agent and ~/.ssh/config. - Servers already in ~/.ssh/config are listed for you to pick. - Jump host and environment sets a bastion host and environment variables, which are passed to Mirasim on that server when it launches. *The same thing from a terminal* ```bash mirasim ssh ubuntu@dev.example.com # connect, tunnel, stay in the foreground mirasim ssh list # saved servers and their status mirasim ssh stop dev.example.com # stop mirasim on that server ``` An SSH connection is reachable only from this computer. To let members use the server too, or reach it from your phone, attach it to the cloud with the one-line install command in chapter 12. ## 20. CLI, TUI and ui-cli Run agents from the terminal, drive the app from scripts, and read or apply settings as one JSON tree. https://mirasim.ai/docs/cli ### The mirasim command The `mirasim` command launches Claude Code and Codex, manages accounts and routing, runs the server, and runs diagnostics. It comes with the desktop app: once Mirasim has started on a computer, it is at `~/.mirasim/bin/mirasim`. `mirasim claude` and `mirasim codex` open each agent's own terminal UI. *Everyday commands* ```bash ~/.mirasim/bin/mirasim doctor # check the install and its environment ~/.mirasim/bin/mirasim claude # Claude Code ~/.mirasim/bin/mirasim codex # Codex ~/.mirasim/bin/mirasim agents # installed versions and updates ~/.mirasim/bin/mirasim ssh ubuntu@dev.example.com # connect to a server over SSH ~/.mirasim/bin/mirasim ui-cli help # the whole control surface ``` The other commands are below. `mirasim help` prints the full list. *The full command surface* | Command | What it does | | --- | --- | | login [github\|email] | Sign in — third-party OAuth or an email code. Stores a token. | | logout | Forget the stored login token. | | agents | What is installed, each version, and whether an update is available. | | update [agent] | Update an agent through whichever channel installed it. | | accounts [add\|use\|remove] | List subscription accounts and switch which one an agent launches under. | | relay [mode\|key] | Show the current route and the platform's health. mode local\|cloud switches between your own accounts and platform credits; key pastes a platform key by hand. | | statusline [set] | Show the running agent's live route; set adds your own text to that line. | | doctor | Diagnose the install, the configuration and recording. | | serve | Run the server: web workbench and pairing. Default port 4939; --host 127.0.0.1 binds loopback only. | | ui-cli [flags] | Drive the UI over its server protocol, for agents and scripts. --port N attaches to a running serve, otherwise it spawns one. | | chat | Read and post in this space's chat from the terminal, without the app running. | | publish | Publish this space's work to people outside it: init, check, preview, submit, status. Needs the app running. | | ssh [list\|stop\|uninstall] | Connect to a Linux or macOS server over SSH, and manage the saved ones. | | checks [session] | Run deterministic checks over a recorded session. | | eval | Browse local eval-skill simulation records: the run list, and per-case traces with screenshots. Default port 4960. | | version · help | Version, and the authoritative command list. | The current route shows in Claude's status line and in Codex's terminal title. Your own status line is kept, and you or other tools can add a segment to it. *Add your own status segment* ```bash mirasim statusline set deploy "staging ✓" ``` ### ui-cli: the app, scriptable `ui-cli` drives a running Mirasim from the command line. What you can do in the app is available as a command, and the effect shows up live in the open window. Each call prints one JSON object, for use from scripts and agents. *Choosing an instance* | Flag | What it drives | | --- | --- | | --port 4970 | The installed desktop app's server — the usual choice. | | (no --port) | A private throwaway server, just for this command. | | --shell desktop \| mobile | Which app answers the shell operations — the desktop window, or the paired phone. | *Read state, run real work, drive the window* ```bash # read-only facts, safe any time mirasim ui-cli --port 4970 state mirasim ui-cli --port 4970 sessions --limit 20 mirasim ui-cli --port 4970 workspaces # start a real run — identical to typing it in the UI mirasim ui-cli --port 4970 prompt --agent claude \ --cwd ~/code/proj --text "summarize this repository" # drive and observe the actual window mirasim ui-cli --port 4970 navigate --to settings mirasim ui-cli --port 4970 ui settings.open --value traffic mirasim ui-cli --port 4970 dom mirasim ui-cli --port 4970 click --text "By model" mirasim ui-cli --port 4970 screenshot --out shot.png ``` ### Settings as one declarative tree Every saved setting forms a single JSON tree: the default agent, per-agent model, effort and access mode, the routing mode (your own accounts or platform credits), browser and screen automation toggles, display sleep, agent auto-update, the working directory and registered workspaces. You can read the whole tree, set individual dot-paths, or apply a desired tree in one go. *Read, set, and apply* ```bash mirasim ui-cli --port 4970 config get mirasim ui-cli --port 4970 config set \ defaultAgent=codex relay.mode=cloud # see exactly what would change, then apply only that mirasim ui-cli --port 4970 config apply --file desired.json --dry-run mirasim ui-cli --port 4970 config apply --file desired.json ``` `config apply` changes only the fields that differ from the live values, takes effect immediately, and is safe to run again. The reply lists each changed field with its before and after. The platform key, account tokens and provider keys are not in the tree; set them with their own commands. ### When a command does not exist yet `raw` sends a protocol frame as-is and prints the responses. Use it for an operation that has no command of its own yet. *Send a raw frame* ```bash mirasim ui-cli --port 4970 raw '{"type":"…"}' --await someReplyType --seconds 5 ``` ## 21. Data, recording and privacy What Mirasim records, where your data lives, and how to turn recording off. https://mirasim.ai/docs/privacy ### What lives where Project files, Git worktrees, session history and usage data live on the host you selected, mostly under `~/.mirasim`. Workspace configuration lives in `/.mirasim`. - Your code is sent to the model providers you use. Turns on Mirasim's platform credits go through Mirasim. - Local models keep everything on your computer. - Provider and connector keys are stored in the system keychain where one is available. ### Usage recording Recording is on by default. For each model call, Mirasim records the model, route, status, latency and token counts on this computer; message content is never written. The Traffic monitor page shows these records. *Turn recording off* ```bash # for one launch MIRASIM_RECORD=0 mirasim # persistently, from the next launch touch ~/.mirasim/capture.off # …then relaunch. Remove the file to enable recording again. ``` Feature-usage statistics have their own switch: "Help improve mirasim" in Settings. ### Remote hosts and team spaces - A connection code contains an access token. Share it only with people you trust. - Selecting a remote host does not migrate the local host's pairings or schedules. - In a team space, workspaces, sessions and the team chat are stored in that space. - API keys configured in a space are stored in that space. Members can use the models shared with them without seeing the key or endpoint. ## 22. Reference Keyboard shortcuts, ui-cli commands, the settings tree, paths, ports and platform requirements. https://mirasim.ai/docs/reference ### Keyboard map ### Navigating - `⌘ K` — Command palette: sessions, commands, and full-text transcript search. Also opens from Search at the top of the left column - `⌘ N` — New window - `⌘ 1` — …⌘9: jump to group N (⌘9 is the last group) - `⌥ 1` — …⌥6: focus pane N in the current group - `⌘ ⌥ ←` — Cycle pane focus (⌘⌥→ forwards) - `⌘ F` — Find in the transcript, with next, previous and a match count ### Arranging - `⌘ D` — New pane, splitting right - `⇧ ⌘ D` — New pane, splitting down - `⌘ W` — Close the focused document, then its tile, then the pane - `⇧ ⌘ ⏎` — Zoom the focused pane, and back - `⌘ T` — New group - `⇧ ⌘ T` — New tab inside the focused pane - `⌃ ⇥` — Cycle groups (⌃⇧⇥ backwards) - `⇧ ⌘ ]` — Next group (⇧⌘[ previous) ### Code and terminals - `⇧ ⌘ E` — The files and Git surface for this pane's workspace - `⌃ `` — Flip the focused pane between chat and the agent's terminal UI - `⌃ ⇧ `` — New standalone terminal pane - `⌘ click` — Go to definition in the editor ### ui-cli command catalog `mirasim ui-cli help` prints the full command list. Commands that act have the same effect as doing the same thing in the app. *Read* | Command | What it returns | | --- | --- | | state | Host bootstrap: version, working directory, platform | | agents · clis · cli-tools | Installed agents and their default; agent CLI versions; dev CLIs on PATH and their auth | | sessions · history · queue | Session rows; a session's settled turns; its queued prompts | | catalog · commands · models | Composer options for an agent; its slash commands; the BYOK provider/profile/binding layer | | accounts · usage · relay | Stored accounts with quota; per-agent quota snapshots; Mirasim platform sign-in, credits and routing mode | | workspaces · git | Registered folders; one folder's live Git status | | mcp list · connectors list · skill list | Tool inventory at each scope | | traffic stats · calls · meta | Usage statistics, recent calls, and the disk space the usage records take | | system · permissions · resources | Host telemetry; macOS permission states; a resource baseline | *Act* | Command | What it does | | --- | --- | | prompt · send · watch · stop | Start or continue a run (blocks until the turn settles), stream snapshots, interrupt | | answer | Answer an agent's interactive prompt — the scriptable “click Allow” | | queue steer \| jump \| recall \| move | Hand a queued prompt to the running turn, cut the line, take it back, reorder | | session new \| open \| rename \| delete \| resume | Session lifecycle, including printing the native resume command | | workspace add \| update \| remove | Register, edit, unregister a workspace folder | | account use \| add \| rename \| token \| remove · login · logout | Agent account management; sign in to or out of your Mirasim account | | provider · profile · model bind · model test | The BYOK layers, and one real round-trip to prove it | | local probe \| start \| pull \| pulls \| delete | Local inference backends and models | | mcp add \| remove \| toggle \| health | MCP servers at workspace or global scope | | skill install \| create \| update \| remove | Skills at workspace or global scope | | connectors install \| enable \| validate \| auth \| search \| uninstall | Connector lifecycle, including the official registry | | codex-reset · restart | Redeem a Codex limit reset; restart the host | *Config and shell* | Command | What it does | | --- | --- | | config get \| set \| apply | Read the whole settings tree, set dot-paths, or converge onto a desired tree (--dry-run shows the diff) | | screenshot · shell | A PNG of the real app window; window and app facts | | navigate · ui · dom · click · press · type · read | Route the UI, run a semantic UI command, list actionable controls, and drive them by text or selector | | raw | Post any protocol frame verbatim | ### The settings tree `config get` returns one JSON tree covering every saved setting. Keys and tokens are not included. - **defaultAgent** — The agent new sessions start with. - **agents..{model,effort,accessMode}** — Per-agent default model, reasoning level, and whether it runs on a subscription or an API key. - **relay.mode** — Routing: `local` uses your own accounts, `cloud` uses Mirasim platform credits. Neither falls back to the other automatically. - **computerUse.guiAgentEnabled · computerUse.guiPreviewEnabled** — Enable Computer Use tools and show their live preview. - **computerUse.{guiEmbeddedBrowserEnabled,guiManagedBrowserEnabled,guiExtensionBrowserEnabled}** — Independent switches for the embedded browser, independent browser and browser extension. They can be enabled together. - **computerUse.{guiBrowserBinary,guiBrowserDir}** — The independent browser's executable and data folder. - **computerUse.{macosControlEnabled,macosAllowedApps}** — Allow native macOS control and list apps that may be used without asking. Other apps ask for permission when first used. - **preventDisplaySleep · agentAutoUpdate** — Keep the screen awake while the app runs; keep agent CLIs up to date. - **workdir · workspaces[]** — The default working directory and the registered workspace folders. ### Paths, ports and requirements *On disk* | Path | Holds | | --- | --- | | ~/.mirasim/setting.json | Host settings — what the Settings UI and `config set` write | | ~/.mirasim/traffic | Per-call usage records (no message content) | | ~/.mirasim/capture.off | Create this file to disable recording from the next launch | | /.mirasim/schedules.json | This workspace's scheduled prompts | | /.mirasim/ | Workspace-scoped skills and configuration that belong in your repo | *Ports ui-cli connects to* | Port | Instance | | --- | --- | | 4970 | The installed desktop app's server | | 4939 | A server started by `mirasim serve` — its default port | | (none) | Spawn a private throwaway server for one command | *Platform requirements* | Surface | Requires | | --- | --- | | Desktop | Apple Silicon or Intel Mac, macOS 13 Ventura or later; Windows 10 1809 or later (x64, Arm64); or Linux via AppImage / .deb (x86_64, arm64) | | Android | Android 8.0 or later | | iPhone | iOS 15 or later, TestFlight beta | | CLI / TUI | Comes with the desktop app; on a Linux server without a desktop, x86_64 through the one-line install (chapter 12) | *Useful environment variables* ```bash MIRASIM_RECORD=0 # turn off usage recording for this launch MIRASIM_ANALYTICS=0 # send no usage statistics for this launch ```