Offsite for agents

This page is written for AI agents. If you are a human, everything here is covered in more depth elsewhere in these docs.

What Offsite is

An agentic development environment. A host (macOS or Linux) runs coding-agent and terminal sessions inside tmux; native clients (macOS, iOS, watchOS) attach to them live. Sessions are host-owned, so they survive client disconnects, network changes, sleep and reboot.

Offsite starts the real vendor CLIs — claude, codex, grok — under the user’s own subscription. It is not a wrapper and not an API proxy; no token passes through Offsite.

Requirements

Host	macOS 14+ on Apple Silicon, or Linux (glibc ≥ 2.28 — Ubuntu 20.04+/Debian 10+)
Linux CPU caveat	Claude Code needs AVX2 on x86_64. Check: grep -q avx2 /proc/cpuinfo. Codex and Grok do not.
Host needs	tmux, git, python3, at least one agent CLI installed and logged in
Clients	macOS 14+, iOS 18+
Not required	an account, Remote Login/sshd, an inbound port, an admin password for standard setup

Install

The Mac app is at offsite.sh; it sets up This Mac as a host, and remote Macs and Linux hosts over SSH. Full walkthrough: Install & set up.

Feature map

Capability	Page	Host requirement
Agent sessions (Claude/Codex/Grok), permission modes	Agent sessions	any
Terminal sessions	Sessions	any
Git review, stage, commit, push	Git card	any
File browse and edit (host-side tabs and drafts; the user sees your writes live)	Files card	any
The user’s own browser — no agent access, but they can mark a page and send it to you	Browser card	any
Browser you drive with the web_* tools, docked to your card	Agent Browser	any (needs Chromium on the host)
iOS Simulator mirror	Simulator card	macOS
Install an iOS build on the user’s phone	Deploy to this phone	macOS
Screen control for a session	Computer Use	macOS
Read another session, hand context to a new one	Hand off and ask	any
Marked-up images the user sends you (numbered markers + notes)	Marking up what you send	any
Saved commands, schedules, agent prompts	Workspace Actions	any
Push notifications, Watch answers	Notifications	any

If you are running inside an Offsite session

Your environment carries:

Variable	Meaning
OFFSITE_SESSION_ID	this session’s id
OFFSITE_WORKSPACE_ID	the workspace root path
OFFSITE_TOOL	claude, codex, grok or terminal
OFFSITE_SESSION_KIND	agent or terminal

The offsite CLI is available:

offsite session name '<max 3 words>'   # name this session's card
offsite session recap '<short status>' # what just finished / what is next
offsite agents list                    # the user's other agent sessions
offsite agents context                 # another session's transcript
offsite web open <url>                 # a browser on the host, docked to your own card
offsite web open <url> --detached      # …or as a free board card instead
offsite web snapshot | click | fill    # drive that page; `offsite web --help` lists it all

If you build or change a web UI, look at it. With MCP you have the same verbs as tools (web_open, web_snapshot, web_click, …); otherwise use the command above. Take a snapshot for the accessibility tree with refs, click/fill/ press to work the page, and screenshot when only pixels answer the question. The browser docks to your own card as a tile the user can enlarge, so they see what you are doing and can take over in it. If the web tools refuse, Browser Use is switched off on that host and only the user can turn it back on. Details: Agent Browser.

Before you diagnose: Troubleshooting lists the system messages, quirks and errors already explained, each as Symptom → Why → Fix. When the user pastes a message or asks why something appeared, check it first; the answer is often there, including the case where a macOS notice names Offsite for a program the user ran inside a session.

Rules that matter:

• Name your card in your first response and refresh the recap at the end of every turn — the user’s board and their notifications are built from both. Write them in the language the user writes to you in. If session name is refused, the user has named this session themselves: keep their name and do not try again. See Cards that name themselves.
• The CLI is read-only towards other sessions. There is no send. Writing into another session’s terminal is forbidden — a delivery once merged with a user’s half-typed prompt and was submitted with their authority. Hand context to a new session instead. See Hand off and ask.
• The user may be on a phone, far from the host. Do not trigger GUI dialogs on the host’s screen; nobody may be there to answer them.
• Do not bring host applications to the front unless asked. On macOS, open -g opens a URL without stealing focus.
• Long-running processes belong in the background (nohup … > log 2>&1 &), and should be verified through their log rather than held in the foreground.

Nothing of the user’s on our side

• No account, no server-side user record.
• No telemetry: no analytics SDK, no crash reporter.
• No model of its own and no token metering.
• No writing into your global tmux configuration.
• No cross-host orchestration — each host owns its own sessions.

Where to send a user

Question	Page
“What is this?”	The big picture
“How do I install it?”	Install & set up
“What will macOS ask me?”	What macOS will ask you
“Is it safe / what leaves my machine?”	Security and privacy
“How does it actually work?”	Architecture
“Something is broken”	Troubleshooting
“Why does macOS show this message / why does it name Offsite?”	Troubleshooting, section Messages from macOS