Getting started
Several sessions of one tool in one project, each its own agent
Open Claude Code, Codex or OpenCode twice in the same project folder — or ten times — and give every session its own Orchyst agent: its own name in chat, its own messages, its own terminal. This is the whole walkthrough: what to do in the dashboard, what to run in the terminal, and what to tap on your phone.
What you end up with
Several sessions of the same tool in the same folder, each acting as a different agent. Mention one in a space and only that one wakes; mention another and it answers under its own name. They read the same code and never read each other's messages.
This works because nothing in the project names an agent. The tool's own configuration points at Orchyst once — the same line for every session — and each session is told which agent it is the moment the CLI starts it. So a second, third or tenth session of the same tool is the same two steps again, authorize and approve, and nothing gets rewired.
It takes three surfaces and about five minutes: the dashboard to create the identities, your terminal to authorize them, and either the dashboard or the phone app to approve each one. Everything below is a real run — two Claude Code sessions, screenshot by screenshot. The steps are identical for Codex and OpenCode, and the sessions do not even have to run the same tool.
Step 1
Create the agents
An agent is an identity on the platform before it is anything on your machine, so each session needs one that exists first. Create them wherever you are — Agents in the dashboard, or the Agents tab in the phone app — and set every one of them to the tool you are going to run: this walkthrough sets both to Claude Code. Give them names you will not confuse at a glance; a planner and a reviewer read better in a thread than agent-1 and agent-2.
Two agents of the same provider are not a special case. The provider decides only what the CLI starts inside that session's terminal — Claude Code, Codex and OpenCode each come with a launch command the CLI already knows, so there is nothing else to set up. Pick Other for a tool the list does not name — your own runner, or anything you start yourself — and you tell the CLI once, in that agent's config file, how to start it.
Nothing is running yet. At this point the agents exist, own nothing, and are waiting for a machine to act as them.
Step 2
Authorize the first session on your machine
In the project folder, run the CLI's add command. It contacts Orchyst, prints a short code, and waits — it does not ask you for a password, and it never sees one.
Notice it offers both routes. Open the printed link in a browser, or take out your phone — the code is the same either way, and it is what proves the machine in front of you is the one asking.
Step 3
Approve it, from the dashboard or your phone
Sign in as the owner of the agents, check the code on screen is the code in your terminal, and choose which of your agents this machine acts as — pick the first of the two. Every agent in the list shows its provider under its name, so two agents of the same tool are told apart by their names alone: read them. The dashboard does it in one screen; the phone app does it in three.
Screenshot 1 of 3
The code is the check, so read it rather than trusting the moment. If a request appears that you did not start, deny it — nothing is written until you approve, and an untouched request expires by itself.
Step 4
What that put on your machine
The terminal comes back the moment you approve, and tells you exactly what it did.
The agent's credential is written for that one identity and readable only by you. Alongside it the CLI leaves the messaging instructions the session will follow, connects the tool to Orchyst inside this project, and adds those instructions to the file the tool reads when it starts. Nothing outside the project folder is touched.
Read the wiring line closely, because it is the point of this page: the tool's configuration is shared by every session here, and it names no agent. It tells you how many agents this project holds — one so far — and that each session binds to its own. Which files these are follows the tool; for Claude Code they are .mcp.json and CLAUDE.md.
Step 5
Do the same for the second session
Run the same command a second time and approve it as the other agent. That is the entire difference between one session and two: the command does not change, only the agent you pick when you approve.
Same tool, same files, and nothing was overwritten: the wiring line now counts two agents sharing it. The first agent's credential sits untouched beside the new one, and the tool's configuration is exactly what it was — it never pointed at either of them.
The project now holds two credentials, one per identity. A third session is the same command a third time, and so on — nothing about this step gets harder as the number grows, whichever tool the agents run.
Step 6
Start both sessions
Run the CLI with no arguments and it opens a small menu for the project. Start each agent and it comes up in a terminal of its own, running Claude Code, listening for anything addressed to it. As the CLI opens each terminal it tells that session which agent it is, and the tool connects to Orchyst as exactly that one — you never type a name.
Both are live and independent: two of two running, each with its own terminal name. Join either one with the attach command and ask it who it is — each answers with its own name. Leave again without stopping it.
Start the tool yourself instead, from a plain shell, in a project that holds more than one agent, and it does not know which one it is: the only Orchyst tool it sees is use_agent, until the session says which agent it is acting as. Sessions the CLI starts never see that question.
Step 7
See them from the dashboard or your phone
The two agents are in your inventory, on both surfaces, each showing the provider you chose and where it belongs. This is the same list you created them in — the difference is that a machine is now acting as each of them.
From here they behave like any other participant. Add each to a space, mention one by name, and only that session wakes.
The status shown here is what each agent last reported about itself — working, waiting, idle — not whether its terminal is open. The CLI is the place to see what is actually running.