What Mycolab can do, and what to say to make it happen.
You do not operate Mycolab by typing commands — your agent does that. So each block below is written for you: what the capability actually is, a picture of how it works, and the plain sentences that reach for it. The exact commands are still here, folded away, for the agent reading over your shoulder.
The whole surface, at a glance
Three families. Run is what happens on your computers, coordinate is how work survives a turn and several agents, share is how a result reaches a person who is not sitting at your machine.
Run
The agent you already use — claude, codex or pi, on your own machine Workspaces and organizations — one shared context, one boundary A public URL with no port — a link you can send someone, todayEverything named here is in the shipped myco binary or on the console today.
Where something is designed but not finished, this page says so in the block it belongs to rather than
leaving it out — a half-built mechanism that reads as shipped is the one failure a reader cannot
detect for themselves.
Your computers, driven from anywhere
The agent runs where the data already is — on the laptop, the workstation, the server under the desk. What Mycolab adds is a way to reach it, a boundary around it, and a way out to the public internet that does not involve opening a port.
Your computers, as one place. The agent sits on top of the data where it already lives; the workspace is what lets you reach it from anywhere, and what keeps one client’s work from touching another’s.
Run the agent you already use
claude, codex or pi — the real tool, your subscription, your files.
Point Mycolab at a folder on any computer you own and get a working agent session in it — the same assistant you would run in a terminal, reading the same files, on your own account. You can keep several sessions going at once, on several machines, and come back to any of them days later.
And on a machine where you have no terminal at all, you can ask for the tool to be put there for you — choosing which agent to install at the moment you add the machine. That was the gap that used to stop people: a borrowed workstation you can reach but cannot set up.
Mycolab does not reimplement an agent. It runs the vendor’s own tool as a long-lived process and translates three different wire protocols into one — which is why the app can show you a codex session without containing a single line that knows what codex is.
A session is one long-running copy of the real command-line tool, started on your machine as you, holding its own context until you archive it. Which tool can be installed is an allow-list: a request arriving over the network names an id, never a command — so nothing from the outside can nominate what gets run. Versions converge on their own, and an update waits while a live session of that flavour is still working.
Supported today: exactly three. claude (native installer, minimum
2.1.294), codex (npm i -g @openai/codex, minimum 0.161.0), and
pi (npm i -g @earendil-works/pi-coding-agent, minimum 1.1.0).
- “start a session on the lab workstation in ~/projects/trial and get the failing tests passing”
- “use codex for this one instead of claude”
- “install the pi harness on that machine first”
- “put this session to sleep — I will come back to it tomorrow”
The commands behind this — your agent runs these, you do not have to
myco session spawn claude -d ./project --message "fix tests" --wait myco session attach <id|handle> myco session send <id> "…" myco session restart|hibernate|archive|resume <id> myco machine start --daemon
Keep each project — and each client — completely apart
A workspace is the one shared context, and the line nothing crosses.
Put everything for one project in its own workspace: every machine, session, browser tab, published URL and pinned result sees the same one, and nothing in it is visible from another. One computer can serve several workspaces at once, so the laptop you use for a client can also be the laptop you use for yourself without the two ever meeting.
You can also write standing instructions every session in a workspace inherits, and put several workspaces under an organization so colleagues can find each other’s work without it being merged into one pile. An organization buys two things that pull in opposite directions and are both wanted: discoverability, so a group can see what its own people have built, and a ceiling on visibility, so a channel can be opened to the organization and no further.
A workspace is one object at the edge of the network. A machine’s credential is scoped to exactly one of them, which is what makes the separation structural rather than a matter of being careful.
Files on disk are the deliberate exception, because they belong to one machine — which is
exactly why sharing a file here means pinning it or serving it rather than copying it.
Two verbs people confuse: use re-enrols a machine in a workspace, while
attach gets it a second credential, so one computer can serve several.
An organization grants org-wide reads across member workspaces; an answer that could
only be assembled in part says so rather than silently returning less.
Two edges worth knowing before you need them. Listing your workspaces needs a user session — an agent or machine token authorises exactly one workspace and cannot enumerate the others, which presents as an empty list rather than a permission error. And changing org membership is not in the CLI at all: it needs a passkey step-up, so it lives in the app under Settings → Organizations.
- “make a new workspace for the Karolinska project and switch me into it”
- “pin this result so the other machines can pick it up”
- “attach this laptop to the lab workspace too, without leaving mine”
- “set the standing instructions every session here should follow”
The commands behind this — your agent runs these, you do not have to
myco workspace create|list|info|current|select|use|attach|detach
myco workspace members
myco workspace prompt set # the standing instructions sessions inherit
myco lab pin ./result.csv --as result
myco lab get result
myco org list|show
myco manage survey|route|broadcast|changes
Precedence for which workspace a command lands in, highest first:
-w → $MYCOLAB_WORKSPACE → workspace select
→ the machine’s default attachment.
Send someone a working link to something on your machine
No port opened, no router touched, nothing copied anywhere.
Turn a folder or a running local server into a real URL — a built site, a report directory, the dev server on port 5173 — and send that link to a colleague who is nowhere near your machine. Nothing is uploaded and no port is exposed on your network.
You choose who can reach it: everybody, anyone holding the link, your workspace, only you, or a named list of email addresses. And you can ask for a link to stay the same across re-publishes, which matters the moment you have already sent it to somebody.
The connection is made from the inside out. Your machine holds one outbound connection to its own tunnel object; a public request arrives at that object and is carried back down the same connection. One tunnel is one object, so tunnels are isolated from each other by construction rather than by configuration.
Each mount is served at the root of its own hostname, so an app’s absolute paths work with no rebuild. The five tiers share one parser and are enforced twice — once at the edge and again by the daemon on your machine — and an unlisted mount cannot be pinned to a stable label, because in that tier the label is the capability and keeping it stable would be handing it out permanently.
Two rough edges in the shipped build. A mount created before the access gate shipped keeps an ungated edge until it is re-added — re-add anything old that you care about. And targeting a mount at a different machine is marked work-in-progress.
- “publish the built site and give me a link I can send to Anna”
- “share this folder with ana@kth.se and bo@ki.se only — nobody else”
- “expose the dev server on 5173 so I can check it from my phone”
- “keep this link alive, I have already sent it to people”
The commands behind this — your agent runs these, you do not have to
myco serve my-report ./dist --public myco serve lab-notes ./notes --access ana@kth.se,bo@ki.se myco expose 5173 --name api # a running port, not a directory myco tunnel list myco tunnel retain <tunnel-id> # once, AFTER you publish myco tunnel release myco apps status|publish|unpublish myco process apply ./web.yaml # with wake_on_request: true
The tiers are --public, the default link tier (an unguessable 88-bit
hostname), --workspace, --owner, and --access a@x,b@y.
A named URL is minted fresh on each publish, which is what tunnel retain is for.
Work that outlives a turn, and several agents that do not talk each other to death
The moment there is more than one session, two opposite failures appear: agents that flood each other with text nobody needed, and work that quietly stops existing when a turn ends. The three capabilities here were each built against a measurement of one of those.
Nothing here asks an agent to remember. The backlog is files in your folder, the schedule is a file beside them, and finishing something runs a command — so the state of the work does not depend on anything staying in anyone’s head.
Let your agents hand work to each other
A turn one of them starts now, and mail the other reads when it next looks up.
With more than one session running, you can have one of them put another to work — either right now, interrupting whatever it was doing, or as a note it will read when it next finishes a turn. Replies come back attributed, so you can see who said what and answer the exact message rather than shouting into the room.
The whole thing is tuned so that a message you ignore costs you nothing. Both failure modes were counted here first: five sessions over fourteen hours exchanged 122 messages received and 754 sent — about 455,000 tokens of agent-to-agent text for a handful of decisions that genuinely needed two parties; and separately, one mailbox held 15 messages, 15 unread, and 0 still useful by the time anyone read them.
Two planes, and the difference is who waits. A turn is work that begins immediately or the moment the other session is free. A message is mail: it sits until the recipient looks, and it never interrupts anything.
Starting a turn happens under one idempotency key, so a retry cannot duplicate the work — the result tells you whether it is running or waiting. Urgency is the sender’s own declaration and buys exactly one thing: only an urgent message may skip the wait and wake a sleeping session. When a mailbox has to be truncated the ranking keeps urgent first, then merge-requests and blockers, then everything else, and puts no action needed last — and an entry that keeps being ignored starts ringing on its own account and sorts above newer mail.
- “tell the session on the workstation to take over the data cleaning”
- “leave a note for whoever picks this up next”
- “this one is urgent — wake it up if it is asleep”
- “who else is running right now, and on which machine”
The commands behind this — your agent runs these, you do not have to
myco session send <id> "<msg>" --subject "<one line>"
myco session send <id> --body-file - # a path is never shell-evaluated
myco session inbox list [--unread]
myco session inbox send <target> "<body>" --urgency urgent
myco session inbox reply <message-id> "…"
myco session inbox read|peek <id>
myco session inbox clear --message <id>
myco session whoami --all
Park work for later, and put things on a timer
A backlog that is just files in your folder — and a finish that has to be earned.
Anything that should not be done right now can be written down where the next agent — or the next you — will find it. The backlog lives in the project folder as plain markdown, so it travels with the repository, shows up in a diff, and survives every session that touched it. You can also have work happen on a schedule, or when something else finishes.
The part that matters most is the ending. Nothing counts as done because an agent said so: each entry can carry the command that would prove it, and closing it runs that command.
The case that forced this: one task was offered as finished four or five times, and each time the objection came back as a paragraph of prose — which no oracle can read. A sentence cannot close a task. A command that exits zero can.
The backlog is files, and the finish is a command. An entry can record what would settle it, so a claim that the work is done is checked by the shell rather than believed.
Automation is shaped like a familiar CI file — a name, a trigger, and steps that are ordinary shell commands — triggered on a schedule, on demand, when a session goes idle, when an entry becomes ready or is closed or labelled, or when a channel call arrives. The close gate also refuses while the fix’s branch still holds commits the base has never seen, and can require the command’s output to contain, or not contain, a given string. Before writing a new entry it compares the title and body against every open one and names up to three that look similar.
There is one more reason an entry has a shape: on a single day, four separate times, an agent paid for a real measurement only to refute an assumption that had been written down as if it were a fact — and once, following it would have landed a regression. A backlog entry has to be able to say what would settle it.
- “file that as something to do later — it should not block us now”
- “do not call it done until the test suite passes”
- “run the link checker every night at two”
- “what is actually ready to be worked on”
The commands behind this — your agent runs these, you do not have to
myco issue add "<title>" --verify-cmd "npm test" [--scope project|session]
myco issue list|show|ready|work|triage
myco issue assign <id> --to <who>
myco issue comment <id> --body-file ./note.md [--dispatch]
myco issue close <id> --branch main --evidence "npm test" --expect-exit 0
myco issue pending # exit 0 = nothing actionable
myco workflow add nightly --on schedule --cron "0 2 * * *" --run "…"
myco workflow list|show|run|enable|disable|guide
Entries live at .mycolab/issues/<id>.md and automation at
.mycolab/workflows/<name>.yaml. Triggers are schedule,
dispatch, idle, issue (ready, closed, labeled) and
channel. The close gate supports --expect-output /
--expect-contains / --expect-absent /
--expect-exit, and
myco issue --help carries roughly 230 lines of the measured rationale behind it.
Tell it to keep going — and trust it to stop
A command you name decides when the work is finished. Not a model, and not a vibe.
Give a session a goal and walk away. It keeps taking turns on its own: do some work, check, keep going. You can name the command that decides whether it is finished — the test suite, the build, the linter — and that command outranks anything the model believes about its own progress. You can also say whether there is a human to ask; by default there is nobody, which is what lets an overnight run fly.
And you can stop it. There is a stop that latches, so a session cannot talk itself back into motion.
a doom loop with an auto-answerer attached is invisible — worse than the stall it replaced.
The goal is not to keep going, it is to stop at the right moment — and that moment has to be decidable with nobody in the room. If the command passes, the loop ends without asking a model at all; if it fails, it vetoes the model’s claim to be finished; if it will not run, the loop stops.
The software on your machine holds no policy, names no model and carries no threshold. Each round it waits for the turn to genuinely end, reads the last reply, and posts it with the goal to the console, where one pure function ranks the rules in a fixed order: a question only a human can answer (if a human was nominated) → done is done → no progress terminates. That split is deliberate — the thing most likely to need changing lives on a server, not on every machine.
Backoff doubles from 15 seconds to 10 minutes when a turn leaves the gate exactly where it found it. The smarter judging mode needs a key on the console and never silently downgrades to the simpler one. The per-session loop keeps its phase, iteration, maximum and budget in one file, and the app’s progress bar reads that file rather than keeping a second copy.
Not verified: the in-app surface. The CLI help and the shipped skill both describe an Auto pilot switch above the composer and a slash command you can type into it; we have not observed either against the live app, so treat the commands below as the authority.
- “keep working on this until the tests pass”
- “stop when the report builds cleanly — and check with me if you hit a decision only I can make”
- “that is enough. stop, and stay stopped until I say otherwise”
The commands behind this — your agent runs these, you do not have to
myco session autopilot <id> --goal "make the test suite pass" --oracle "npm test"
myco session autopilot <id> [--mode smart|ralph] [--max N] [--human] [--dry-run] [--json]
# smart: judges progress. ralph: just repeats the goal.
myco session steer <id> … # the same command, other spelling
myco session abort <id> # off. there is no --off
myco session abort <id> --lock # latching stop
myco session unlock <id> # the only thing that releases it
curl -s https://console.hypha.run/steer/v1/health
There is no myco loop command — a loop is something the user
begins. Its state lives at .mycolab/<sid>/loop/loop-state.json.
First steps, and the detail underneath
This page is the what and the why. The other two are the how.
Quickstart
From nothing to a public URL in about ten minutes — four commands and two trips to a browser (one to sign up, one to approve the machine), with the four traps that cost somebody an afternoon called out where they happen.
Advanced, by what you are doing
Model access and gateways, the console, autopilot and loops, issues, workflows, channels, worktree children, and keeping a published URL alive across re-publishes.
The overview
What the product is, what it is built on, and what happens to your sessions and machines over time.