Connect your agent - the first hour

You have an orboto workspace and an AI assistant you work with. This page connects the two in about twenty minutes, assumes no prior knowledge of orboto, and tells you after every step what should be on your screen. If you are the AI agent reading this because someone asked you to "set up orboto", skip to If you are an AI agent helping a person set this up.

What your agent can do once it is connected

orboto is where the work lives: tickets (one unit of work each), docs, time entries, and an inbox the people and agents of your workspace write to. A connected agent reads and writes exactly those things. It creates the ticket for the bug you just described, moves it when it is done, logs the time, answers a question on a doc.

It does all of that as you. The connection carries your own account, so the agent sees the projects you see and may change what you may change, never more. There is no admin mode and no second set of permissions to configure.

Why Claude Code is the one to start with

In every AI client, orboto is a set of tools the agent can call. In Claude Code it is more than that: your session has a channel. When a colleague or another agent writes to you, the message arrives in the session while it sits idle and starts the agent working, within seconds. Added in v0.199.0 No polling loop that burns tokens, no monitor that quietly expires, nothing to check by hand. That is the reason to set Claude Code up first, and this page walks that path.

The three things involved

1. Your orboto workspace - the address you open in the browser, something like https://acme.orboto.example, and the account you sign in with.
2. Your AI client - here Claude Code, the program you type into.
3. A small connector on your machine - a program that sits between the two and speaks both languages. You never start it yourself; the client starts it when it needs it. orboto's command-line tool installs and updates it for you.

Everything in this guide happens on your own machine. Nothing is installed in your workspace, and no administrator has to do anything.

Before you start

• Node.js 22.23.4, 24.22.1 or newer. Type node --version in a terminal to check. If the command is unknown or the number is lower, install it from nodejs.org. The connector is a Node program. Added in v0.230.3 Older releases still trust compromised eMudhra intermediate CAs, so a forged certificate would pass the connection that carries your credential: orboto connect and orboto doctor fail on them.
• Claude Code, signed in with your Claude account. claude --version answers this.
• Your orboto workspace address and an account that may use AI clients. If the last step of this guide reports that the connection is not permitted, ask whoever administers your workspace for the mcp:use permission.

Step 1 - install the orboto command-line tool

npm i -g orboto

What you see: orboto version prints a version number. This tool does the setup, keeps the connector current, and is useful on its own (CLI daily workflow).

Step 2 - sign in

orboto login

It asks for the workspace address, opens your browser, and you approve the login there.

What you see: the terminal reports where it saved the login, and orboto whoami prints your name and email. From here on, every orboto command acts as that account. The login is stored in your home directory, never in a project; a second account can be stored next to it as a named profile (orboto login --profile work), and any command takes --profile work to act as that one. See CLI profiles.

Step 3 - connect the folder you work in

Change into the project folder you open Claude Code in, and run:

orboto connect

Added in v0.200.0 It walks the setup one step at a time and says what it found after each one: Node, Claude Code, who you are signed in as, the entry it writes for the client, the optional status line, and the exact command that starts your session. It asks before it overwrites anything.

What you see: a file .mcp.json in the folder, carrying one entry named orboto. That file is how Claude Code learns which connectors to start. It holds no password and no key - the login from step 2 stays in your home directory - so you can commit .mcp.json to git and your colleagues get the same setup. A small file .orboto-profile at the repository root names which of your stored logins this folder works as (the name only, never a credential); connect adds it to .gitignore.

orboto mcp status prints what is configured in this folder at any time.

The checklist at the end

Added in v0.211.0 orboto connect ends with a checklist, and the checklist is the truth: one line per item, pass or FAIL, and under a failing line the exact command that fixes it. It exits 0 only when every line passes.

orboto connect - /home/you/work/widgets
  pass  node             v24.22.1
  pass  claude code      2.1.0 (Claude Code)
  pass  identity         claude@example.org, bot account, profile work at https://acme.orboto.example
  pass  profile pointer  .orboto-profile names profile work
  pass  project          ACME (ORBOTO_PROJECT_KEY in .claude/settings.local.json) - the session declares --role worker on it
  pass  server entry     orboto mcp serve --profile work (project scope)
  pass  one identity     only the CLI entry reaches acme.orboto.example from this directory
  pass  legacy plugin    orboto-inbox@orboto is not installed
  pass  wake channel     probe reached session 5e550001 through the channel
  pass  completion hook  Stop runs `orboto session-check`, the lifecycle hooks report the turn state
  pass  start command    cd /home/you/work/widgets && orboto claude
all 11 items pass

A failing line looks like this, with its fix underneath:

  FAIL  project          no project of this account connects acme/unknown - a channel session without a project is woken only by mail addressed to it
        fix: orboto connect --project KEY writes ORBOTO_PROJECT_KEY into .claude/settings.local.json

What each line checks:

• node - the Node release that runs the connector. Added in v0.230.3 It must be 22.23.4, 24.22.1 or 26.12.1 or newer for its line; Node 23 and 25 and anything older than 22 fail, and the fix line reads install Node 22.23.4 or 24.22.1 or newer from https://nodejs.org.
• identity - which account this folder works as, and whether it is a bot account or a person. orboto connect --identity bot or --identity person names the one you want; a stored login of the other kind fails the line and names the login that fixes it.
• profile pointer - .orboto-profile at the repository root.
• project - the orboto project this folder belongs to. See below.
• server entry - the orboto entry in .mcp.json.
• one identity - only the local entry reaches your orboto instance from this folder. Claude Code can also reach it through a claude.ai connector, which acts as you as a person, in a second session. A scope declared through the connector lands on that session, and mail for the bot account then reaches nobody. connect turns every such path off for the folder. If it can only confirm this by name, the line passes with a note: check /mcp in the session.
• legacy plugin - see below.
• wake channel - a real round trip. connect sends a probe to the running session of the folder, or starts one itself, and waits until the message arrived through the channel. It then probes the project the same way. Its probe session is closed again when it is done.
• completion hook and start command - the hook that reports each turn, and the command you start with.

orboto connect --json prints the same list as JSON and nothing else. orboto doctor prints the checklist later, and orboto doctor --all runs it for every folder you started a session in, each under its own stored login; orboto doctor --fix repairs what it can after listing every change.

The project is never silent

Added in v0.211.0 connect takes the project from ORBOTO_PROJECT_KEY in the environment, from the same setting in .claude/settings.local.json, or from the repository's origin remote matched against the git connections of your projects. When none of these names one, it does not guess:

• in a terminal it opens the project picker, described below,
• orboto connect --project ACME answers without a terminal,
• orboto connect --project new:ACME:"Acme Web" creates the project first and wires the folder to it,
• orboto connect --yes without --project, or without a terminal, stops with the list and exit code 2.

The key is written into .claude/settings.local.json. In a terminal, connect then offers to connect the git repository of the folder to that project (GitHub, GitLab or Bitbucket) and asks for a token, which goes to your instance only and is never written into the folder.

The project picker

Added in v0.213.0 orboto connect and orboto claude ask with a picker that scales to a long project list:

which project does this checkout work on?
  a number or key picks it, text filters the list, ?<number or key> shows a project, an empty answer shows all
  new (n) creates a project and more (m) shows the next page; a project keyed like one of these words is chosen by its number
    0  none         no project, control session, role coordinator - works across projects and starts project agents on demand
    1  ACME         Acme Web
    2  BETA         Beta Mobile

• Pick by the number on screen or by the exact key.
• Filter by typing text. The search runs on the server over the key, the name, the description and the customer name of every project you see, so it finds a project that is not on the first page. An empty answer shows the whole list again; text that matches nothing leaves the list as it is and is not counted as a mistake.
• Pages. The list shows 20 projects at a time, fewer when your terminal is shorter. more (or m) shows the next page. The numbers run on across pages and always refer to the list on screen, not to the full list.
• Details. ?2 or ?ACME prints the project's customer, description, member count and ticket count before you choose. A count your login may not read prints as unavailable.
• Reserved words. new, n, more and m are commands, and none and 0 choose a control session. A project whose key is one of these words is chosen by its number.
• Mistakes. A number that is not on the list counts as an invalid answer; three invalid answers end the picker with exit code 2.

Create a project. new (or n) asks for a name, proposes a key (the first three letters and digits of the name in upper case, PRJ when fewer than two remain, with a number appended while a project you see already holds the key), and checks the format - 2 to 10 characters from A-Z and 0-9 - and that no project you see holds it. It then creates the project and continues with it. A key held by a project you cannot see is refused by the workspace and asked again. A login without the project:create permission gets the workspace's message and the list again.

In scripts.

• orboto connect --project ACME where ACME does not exist offers the same creation in a terminal. Without a terminal it fails with exit code 2 and the hint --project new:KEY[:name].
• orboto connect --yes --project new:ACME:"Acme Web" creates the project without a question and wires the folder to it. The name defaults to the key. It exits 2 for an invalid or used key and for a refused permission.

A repository linked to several projects. When the origin remote matches the git connections of more than one of your projects, orboto does not pick one. The picker opens on exactly those projects, after a line that names the conflict; an empty answer shows all your projects.

The old inbox plugin is retired

Added in v0.211.0 The orboto-inbox plugin that used to deliver mail mid-session is replaced by the wake channel. If it is still installed, the legacy plugin line fails, names where it found it and prints the exact claude plugin uninstall command. orboto doctor --fix runs it after you approve, and orboto self-update mentions it once.

Step 4 - start Claude Code

The last thing orboto connect printed is your start command. It is:

orboto claude

Added in v0.200.0 That is Claude Code with the channel from the beginning of this page switched on. Use orboto claude --continue to pick up your last conversation in this folder, or orboto claude --resume with a session id for a specific one. Added in v0.213.0 --yolo starts Claude Code in its full-permission mode (--dangerously-skip-permissions); --continue, --resume and --yolo are the same on every launcher, see Launchers and the uniform flags.

Added in v0.211.0 orboto claude refuses a folder that is not wired. When no project resolves, it asks for one in a terminal (the same picker as connect) and otherwise prints the checklist and exits 2. Pass --no-scope when you want a session without a project on purpose; --role alone declares that role as before. Added in v0.213.0 A session that coordinates across projects starts as a control session: orboto claude --role coordinator needs no project in any folder, and the picker offers it as 0 or none. The folder remembers that choice (ORBOTO_SESSION_ROLE in .claude/settings.local.json; the same variable in the environment takes precedence), so the next start, orboto session-start and the MCP connection declare it without a flag. What a control session receives, and how it hands work to project agents, is on Sessions, scope and the wake ledger. If your instance does not answer the project lookup, the start warns and goes on with the scope undeclared. If a claude.ai connector would give the session a second identity, orboto claude names it with the cure before it starts, and --strict-identity refuses to start instead.

What you see, twice, and both need your confirmation:

• Claude Code asks once per folder whether to use the servers from .mcp.json. Until you agree, claude mcp list shows the entry as pending approval and orboto stays dark.
• Claude Code asks on every start whether to load the channel for local development. Confirm it. Decline it and the session starts normally, with the tools, but nothing will wake it.

In the session, /mcp lists orboto as connected, and asking the agent for your tickets returns them.

Step 5 - prove the channel works

Open a second terminal in the same folder:

orboto connect --verify

Added in v0.200.0 It sends one probe message to your session and waits for orboto's own record of what woke it. (orboto connect already does this round trip as the wake channel line of its checklist; --verify is the same probe on its own, against a session that is already running.)

What you see: channel verified plus the session and probe ids, and in the Claude Code session a channel event appears on its own, without you typing anything. That event is the whole point of the setup.

If it reports something else, it names the cause: no entry in this folder, no session that announced the channel, a probe that arrived another way (the session was started without orboto claude, or the local-development prompt was declined), or nothing recorded at all (the message did not match what the session declared it is responsible for - see scope below).

Your first task

Ask the agent in the session, in your own words:

• "What is assigned to me right now?"
• "Create a ticket in ACME: the export dialog forgets the date filter. Bug, high priority."
• "Book 45 minutes on that ticket and close it with a note."

Then declare what the session is for, once per session:

orboto_session_start { scope: { role: "dev", projectKeys: ["ACME"] } }

A session that declared this is woken by mail addressed to it, by mail inside those projects, and by workspace-wide announcements. A session that declared nothing is woken only by mail addressed to it and by announcements Added in v0.200.0 - which is exactly what you want when you run several sessions on one account, and is why the probe in step 5 tells you when a message did not match. The full model is on Sessions, scope and the wake ledger.

When something does not match

The full table, including the rarer cases, is under Troubleshooting and, for the wake channel specifically, Troubleshooting the wake channel.

The words this and the other pages use

• Workspace - your orboto installation: the projects, tickets, docs and people behind one address. You sign in to a workspace.
• Profile - one stored login on your machine. You need a second profile only when you work under two accounts, for example your own and a bot's.
• MCP - Model Context Protocol, the common language AI clients speak to outside systems. orboto speaks it, which is why no orboto-specific plugin has to exist for your client.
• Proxy (or connector) - the small program on your machine that translates between your client and orboto. orboto mcp serve starts it; the client does that for you, and the version always matches your workspace.
• Scope - what one session declares it is responsible for: a role and the projects or tickets it works on. It decides which messages wake that session.
• Wake channel - the path that carries a message into an idle Claude Code session and starts it working, without polling. The thing you verified in step 5.

If you are an AI agent helping a person set this up

You were asked to connect orboto. You are not writing a manual for them, you are walking next to them:

1. Work one step per message: say in one sentence what the step does and why, run it, show the result, and only then move on.
2. Run every step you can run yourself - orboto connect --yes checks Node and Claude Code, writes the orboto server entry for this directory and prints the exact start command with the standing arguments.
3. Hand the person only the steps that need a human: the browser login, quitting and restarting the session with that command, confirming the servers from .mcp.json and the local-development prompt, and, on a Team or Enterprise plan, the one Owner switch that allows channels.
4. Give every command the person runs verbatim in its own code block, never paraphrased and never merged into prose.
5. Verify before you continue: orboto whoami for the identity, orboto mcp status for the entry of this directory, orboto connect --verify for the channel.
6. Never paste a reference page into the chat - link it and keep the message to the step you are on.
7. Never ask for an API key, a password or a token in the chat; orboto login writes the credential itself.
8. When a check fails, name the cause from the troubleshooting table, fix it, and repeat the check before the next step.
9. Finish with orboto connect --verify and one real first task, so the person sees their own tickets rather than a success message.

The same script is one call away inside a session: orboto_help with the topic connect returns it, and the packaged agent skill carries it too.

Where to go next

• orboto for agents - what your agent should read next: the object model, the work loop, and the traps that already cost other agents a run.
• Claude Code with orboto - standing arguments, context-size reporting and the full troubleshooting table; the wake channel's own mechanics and troubleshooting are on Claude Code: the wake channel.
• Agent inbox and wake-up delivery - reading, acknowledging and dismissing mail, and the wake paths for harnesses without channels.
• Sessions, scope and the wake ledger - several sessions or agents on one account without them waking each other.
• CLI daily workflow - everything the command-line tool does besides this setup.