Orpheus
Start free
Docs

Setup guide

Connect a machine, check it worked, choose what is shown, and remove it again.

Beta: the connector package is published to npm after its security review. Until then the commands below are the planned interface and may change.

What you need

  • A machine running macOS or Linux, with Node.js and tmux.
  • Claude Code or Codex running inside tmux on that machine.
  • An Orpheus account. Adding a server needs the admin role in the workspace.

1. Paste the prompt

In Orpheus, open Servers and click Add server. Give the machine a label such as laptop. You get a prompt like this one, with a real token in it:

Install the Orpheus connector on this machine so my agent sessions show up in Orpheus. Run `npx -y orpheus-connector@0.1.0 pair --url https://app.example.com --token oc_ct_EXAMPLE`, then `orpheus-connector install` to keep it running (launchd or systemd user service). Do not paste the token anywhere else. Afterwards run `orpheus-connector status` and tell me what it shows.

Paste it to an agent on that machine. The token works once and expires after 15 minutes. If it expires, click Add server again for a new one.

Prefer to run it yourself?

# swap the one-time token for this machine's credential npx -y orpheus-connector@0.1.0 pair --url https://app.example.com --token oc_ct_EXAMPLE # keep it running as a launchd or systemd user service orpheus-connector install

2. Verify

orpheus-connector status

It should report that the connector is connected, which workspace and server label it is paired to, and how many sessions are exposed. In Orpheus, the Add server screen changes from "waiting for your agent to connect" to connected, and your sessions appear in the sidebar.

3. Policy file

The connector creates ~/.config/orpheus-connector/policy.json with safe defaults. Edit it on the machine to change what is shown. Orpheus cannot change this file.

SettingDefault
Which tmux sessions are exposedAll Claude Code, Codex and OpenCode sessions. No plain shells.
Whether input is allowedOn for agent sessions, off for shells.
Whether transcripts are sharedOn.
Whether usage is readOff. Turn it on with "usage": true.

The default file. orpheus-connector policy shows it and what it means for each session right now; orpheus-connector policy edit opens it.

{ "expose": { "kinds": ["claude", "codex", "opencode"], "sessions": [], "hide": [] }, "input": { "kinds": ["claude", "codex", "opencode"], "sessions": [], "deny": [] }, "transcripts": true, "usage": false, "newSession": { "allowed": [] } }
  • expose.sessions shares extra sessions by name (* wildcards work), including shells. expose.hide hides some.
  • input.deny makes sessions read-only.
  • transcripts: false stops sharing transcripts. usage: true turns on the hourly usage reading.

Changes apply within 5 seconds. No restart needed.

Uninstall

  1. In Orpheus, open the server and click Revoke. Its connection closes at once and its credential stops working.
  2. On the machine, remove the service and the stored credential (--forget deletes the credential):
orpheus-connector uninstall --forget

Your agents and tmux sessions are not touched.

If it doesn't connect

What you seeWhat to do
Token expired or already usedTokens last 15 minutes and work once. Click Add server for a new prompt.
Still waitingRun orpheus-connector status on the machine. Check the machine can reach the Orpheus URL on port 443.
Server limit reachedFree allows 1 server. Revoke the other one or upgrade.
Connected, no sessionsAgents must run inside tmux. Check the policy file is not hiding them.