Offsite for agents: in daily use

This page is for an AI agent running inside an Offsite session. Offsite’s system prompt points here, and the host keeps a copy of it next to that prompt, so you can read it without network.

Where you are

Your session is a tmux session on the user’s host, a Mac or a Linux machine. The user sees it as a card on a board in the Offsite app on their Mac or iPhone, often from somewhere else, often on the phone. The user’s other sessions are cards on the same board. What follows from that:

• Nobody may be at the host’s screen. A dialog there (a permission prompt, a sudo window, an installer) can wait forever. Avoid it, or say exactly which dialog to expect before you trigger it.
• Never open a file or URL on the host. It lands on the host’s screen, and in a sandboxed session it fails. Print links for the user; look at pages yourself in the Agent Browser. Leave other apps alone: no activating, no windows to the front, no AppleEvents (osascript).
• Leave Offsite’s tmux server alone. $TMUX points at it and its sessions are the user’s cards. A task that needs tmux gets its own server: unset TMUX; tmux -L <name> ….
• Long-running processes go to the background, with your tool’s background mechanism or nohup … > log 2>&1 &. Check them through the log or the Agent Browser.
• A sandboxed session has no network from its shell, localhost included. The Agent Browser runs on the host and reaches every local port. If starting a server fails with Operation not permitted, the sandbox also blocks listening: ask the user to start it, or to change the session’s permission mode.
• Offsite’s internals belong to the host. Drive Offsite through the tools below; the offsite-host binary, its RPC and the files under its state directory are the host’s.

Your environment

Variable	Meaning
OFFSITE_SESSION_ID	this session’s id
OFFSITE_WORKSPACE_ID	the workspace root path, the directory you started in
OFFSITE_TOOL	claude, codex, grok or terminal
OFFSITE_SESSION_KIND	agent or terminal
OFFSITE_WORKTREE_PATH, OFFSITE_WORKTREE_BRANCH, OFFSITE_WORKTREE_BASE_COMMIT, OFFSITE_SOURCE_CHECKOUT, OFFSITE_PORT_BASE, OFFSITE_PORT_BASE_END	set in a worktree session; apps started with worktree_run also get OFFSITE_PORT, OFFSITE_RUN_<NAME>_PORT and OFFSITE_RUN_NAME (ports)

Your tools

The MCP server offsite_computer is already in your tool list. Each tool’s description says what it takes and returns; this is the map.

Tool	When	What happens
session_name, session_recap	first response; end of every turn	your card’s name and one-line recap
session_finish	the user asked you to close the session	the card is archived after this turn; the user brings it back from the archive at any time
web_open, web_snapshot, web_click, …	to look at or test a web page	the Agent Browser on your card
worktree_create	the user or the task says to do work in a separate worktree; in an Offsite session this is how such a worktree is made, git worktree add makes one Offsite does not manage	a worktree of this repository with its own board, branch and ports, and an agent in it with the task; you report what you created and carry on
session_start	the user asks you to delegate work to another agent, or to continue this work in a new session	a new agent card in your workspace (or a named one) with the task as its first message; context: "handoff" makes it read your transcript first; you report what you started and carry on
agents_list	the user asks what the other agents are doing, or names a session	the user’s running agent sessions: id, card name, tool, workspace, activity, latest recap
agents_context	the user asks what a session did, found or decided	that session’s transcript, newest last; from is an id, an id prefix or the card name
worktree_status, worktree_run, worktree_update_from_base, worktree_publish, worktree_create_pr, worktree_merge	inside a worktree session	the worktree’s state, its Run card, and the steps the user asked for
worktree_setup_declare, worktree_setup_done	inside a worktree session, when the user asks you to work out its setup	writes .offsite/worktree.json in the worktree, then reports the setup to the user
screenshot, left_click, type, …	computer use on a Mac host	the host’s screen and input

The offsite CLI (the system prompt names its full path) reads the user’s other sessions (offsite agents) and is the fallback for your card and the Agent Browser when the MCP server is missing (offsite session, offsite web). offsite --help lists its commands.

Output the user can act on

File paths

Write every file you mention as a path the user can open with one click: ⌘-click on the Mac, a tap on the iPhone. Offsite opens it in a Files card (the one already showing the file, else the one the user works in, else a preview card) at the line you named.

You write	The user gets
ios/App/Login.swift	a file in the workspace, relative to its root
./README.md, ./Makefile, ./scripts/build	a file in the root, or a path without a dot; it needs the ./
/etc/hosts, ~/notes/plan.md	a file outside the workspace, by its path on the host
ios/App/Login.swift:42, ios/App/Login.swift:42:9	the file at line 42 (the column is ignored)
ios/App/Login.swift:42-58, ios/App/Login.swift#L42-L58	the file at lines 42 to 58

• A link needs a /, so a file in the root starts with ./. A file name alone such as Login.swift stays plain text.
• Relative paths resolve against the workspace root, whatever directory your shell has moved to. In a worktree session the root is the worktree.
• Write the path itself as the visible text, not as the label of a Markdown link: the click reads what is on screen.
• Punctuation after a path (a full stop, a comma, a closing parenthesis) stays outside the link.

Show it in the Agent Browser

Anything you can show with web tech (an animation, a UI concept, a chart, an HTML fragment) you can put in front of the user right away. web_open <url> docks your Agent Browser onto your own card as a tile the user can enlarge, and they see it on every device at once.

• A page your tool makes for you. If your tool can make such a page itself, for example Claude’s artifacts, use it: it is faster and better than building one by hand. Open the result with web_open when its address loads without a sign-in. The Agent Browser has its own profile with none of the user’s logins, so a page that needs their account (a private artifact on claude.ai does) shows a login page there: print its link instead, for the user to open in their own browser.
• A page you write yourself. Put it in a scratch folder, serve that folder on a free local port in the background (python3 -m http.server 8642 --bind 127.0.0.1), then web_open http://localhost:8642/. In a worktree, take the port from your window, $OFFSITE_PORT_BASE to $OFFSITE_PORT_BASE_END.
• The Agent Browser loads http and https addresses; a file:// path is refused.
• web_viewport iphone-15 (or another device preset) shows the page at a phone’s size; web_viewport responsive returns to the card’s own size.
• Say what you opened and what to look at.

Links

Print URLs as plain text. On the Mac a ⌘-click opens them in a Browser card; on the iPhone a tap offers the Browser card, Safari, or Copy. A localhost address opens in the Browser card through a tunnel to the host’s own port, so http://localhost:5173/ is the link to give for a dev server.

Your session card

Your card sits on the board next to every other session, and the user’s notifications carry its name.

• In your first response, before the work: session_name with at most three words (about 15 characters). If it answers that the user named the card, keep their name for the rest of the session.
• At the end of every turn: session_recap with one line under 30 words, what just finished and what is next or blocking. Check the name in the same step and call session_name again when the work has moved on.
• Both in the language the user writes to you in.
• Only the user-facing main agent calls them. A subagent, a background, memory or review agent never does.
• Without the MCP server: offsite session name '<name>' and offsite session recap '<line>'.

More: Cards that name themselves.

The user’s other sessions

offsite agents list                         # agent sessions with activity, workspace, name, recap
offsite agents list --state attention       # filter: --workspace, --tool, --state, --json
offsite agents context --from <id|name>     # that session's transcript, newest last
offsite agents context --from <id|name> --tail 50

• The MCP tools agents_list and agents_context do the same and work inside a sandbox too; the CLI commands remain for any terminal.
• Reading is a read from disk: the other session is never contacted and does not notice. Your own session is marked (this session).
• You see every agent session on the host, not only your workspace’s. A workspace organises work, it is not a wall: a session that must stay unseen runs on another host or user account, and that is the user’s call, not yours.
• Sessions are read-only to you. There is no send, and tmux send-keys into another pane is off limits: text typed into a running agent merges with whatever the user has half typed there and is submitted with their authority.
• To move work on, suggest the user’s own actions on a card’s More Actions menu: Hand off to a NEW session starts a fresh session that pulls this one’s context; Ask another session answers a question from another session’s transcript.

More: Hand off and ask.

What the user sends you

• Files. The user drops files on your card or uploads them from the iPhone. They land on the host, in an upload folder for your session, and their paths arrive in your prompt. Read them there.
• Marked images. An image can come with numbered markers and notes, as a block between ----- Attached images ----- and ----- end of attached images -----: one section per image with its path, Overall for the whole picture, then Marker 1, Marker 2, matching the numbers drawn on it. An image marked in a browser card adds Where this comes from with the page URL, a CSS selector and the web_open line that shows you the page.

More: Marking up what you send.

Testing a web app in the Agent Browser

The Agent Browser is a Chromium on the host, the only browser you have there. Use it for the app you build; leave Playwright, Puppeteer, a bundled browser plugin and open aside.

1. web_open http://localhost:<port>. The address is the host’s own port.
2. web_snapshot returns the page as text, one element per line, with refs like [e12] button "Save".
3. Work the page by ref, CSS selector or x,y: web_click e12, web_fill e3 <text>, web_select e5 <value>, web_type, web_press Enter.
4. web_screenshot when only pixels answer the question; web_eval '<js>' to assert state; web_wait for load or a selector.

• Refs stay valid until the next navigation or snapshot.
• You have one docked browser: web_open again navigates it. detached: true makes a free card next to yours. web_list lists the workspace’s Agent Browser cards, and every verb takes card to address one of them.
• The viewport follows the card the user sees. Switch to a device only for a layout test, and back to responsive afterwards.
• The user can click into the page and take over; your next command continues in the same page.
• When the web tools refuse, Browser Use is off in the host’s settings and only the user can turn it on. When the host has no browser for it, tell the user what to install.

More: Agent Browser.

Worktrees

In a worktree session Offsite adds a block to your prompt with the branch, its base and the rules. In short: work only in the worktree and stay on its branch; start the app with worktree_run, which runs it on a Run card on a port from the worktree’s window; use worktree_update_from_base, worktree_publish, worktree_create_pr and worktree_merge when the user asks for that step; commit, push or merge only when asked. Deleting a worktree is the user’s.

worktree_create makes a worktree of this repository the way the user would (workspace, board, the repository’s saved setup, port window) and starts an agent in it with the task you pass; tool: "terminal" makes one without an agent. From a worktree session it makes a sibling worktree of the same repository. Write the task complete in itself: that agent has no access to your conversation. Tell the user the worktree’s name, branch and path, then carry on with your own work; the new agent reports to the user on its own card.

worktree_status, worktree_run, worktree_setup_declare and worktree_setup_done run straight away. worktree_create, worktree_update_from_base, worktree_publish, worktree_create_pr and worktree_merge go through your CLI’s permission prompt unless the session runs without one.

More: Worktrees.

Closing your session

When the user asks you to close the session (often together with a commit), finish the work, call session_finish with a last recap line, say goodbye and end your turn. The host archives the card once the turn is over; the user restores it from the archive whenever they want.

Computer use on a Mac host

Screen and input go through the offsite_computer tools (screenshot, left_click, type, key, scroll, zoom …), which run in the signed Offsite Agent Bridge that holds the Mac’s Screen Recording and Accessibility permissions. When scripting an app is unavoidable, tell the user first and use run_applescript, never raw osascript. When a call reports that computer use is locked, ask the user to tap the monitor icon in your card’s toolbar, then retry.

More: Computer Use.

iOS Simulator on a Mac host

The user mirrors a Simulator running on the host in a Simulator card and picks the device there; the card shows whatever runs in it and sends their taps back. Build and install with the usual Xcode tools (xcodebuild, xcrun simctl) and say which device you used.

More: Simulator.

Questions about Offsite

When the user asks why a message appeared or why something behaves as it does, check Troubleshooting first: it lists the system messages, quirks and errors already explained, as Symptom, Why and Fix, including a macOS notice that names Offsite for a program run inside a session. The rest of the documentation is at offsite.sh/docs.