# Offsite documentation

Complete contents of https://docs.offsite.sh, one page per section.

# Offsite for agents

Source: https://docs.offsite.sh/agents/for-agents/

A dense, single-page briefing for AI agents asked about Offsite or running inside it.

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](https://offsite.sh/download/macos); it sets up
This Mac as a host, and remote Macs and Linux hosts over SSH. Full walkthrough:
[Install & set up](/start/install/).

## Feature map

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

```bash
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](/cards/agent-browser/).

**Before you diagnose:** [Troubleshooting](/help/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](/work/self-naming/).
- 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](/work/handoff-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](/start/big-picture/) |
| "How do I install it?" | [Install & set up](/start/install/) |
| "What will macOS ask me?" | [What macOS will ask you](/start/what-macos-asks/) |
| "Is it safe / what leaves my machine?" | [Security and privacy](/reference/security/) |
| "How does it actually work?" | [Architecture](/reference/architecture/) |
| "Something is broken" | [Troubleshooting](/help/troubleshooting/) |
| "Why does macOS show this message / why does it name Offsite?" | [Troubleshooting](/help/troubleshooting/), section *Messages from macOS* |

---

# Marking up what you send

Source: https://docs.offsite.sh/board/annotate/

Circle it, number it, write one line per number. The agent gets the marked image and your notes as text, instead of guessing what "the blue one" meant.

"Make this bigger and the blue one darker" is a sentence an agent cannot act on.
So you write a paragraph describing where things are, or you send a screenshot
and hope the agent finds what you meant.

Offsite puts a small editor in front of every image you send. Draw a shape,
Offsite numbers it, you write one line per number. The agent gets the marked
picture **and** the notes as text ("1: make this bigger, 2: dark blue"), with
the numbers on the image matching the numbers in the list.

## Where it appears

The editor sits in front of the upload, on every path that sends an image:

| You do this | On |
|---|---|
| Drop images onto an agent card | macOS |
| **Upload Files** from the card's action pill | macOS |
| Upload from the command bar — photo library, camera, files | iPhone, iPad |
| **Mark** an area in a [Browser](/cards/browser/) or [Agent Browser](/cards/agent-browser/) card | macOS, iPhone, iPad |

Non-images skip it entirely and upload as before.

## Using it

Pick a tool (**circle, rectangle, arrow or freehand**) and drag it over the part
you mean. A click without dragging drops the shape at default size. Every
shape gets a numbered dot at its top-left corner, in the order you drew them;
delete one and the rest renumber, so the agent never reads a list with gaps.

Tap a dot to open the comments panel and write the line that belongs to it. A
dot with a comment turns black, so you can see at a glance what you have already
described.

The top row of the panel is **marker 0: the whole image**. Use it for the
sentence that applies to everything, like "home screen after login, dark mode",
with or without any shapes at all.

Sending several images at once puts a strip along the bottom. Each image keeps
its own shapes and its own comments; switching between them saves as you go.
Then **Upload** sends the batch.

On macOS: `V` for select, `1`–`4` for the tools, `⌘Z` / `⇧⌘Z`, `⌫` to delete the
selected shape, `←` / `→` to walk through them.

## What the agent receives

The shapes are burned into the image at full resolution, and the comments travel
as a plain block of text that is pasted into the session next to the file paths:

```
----- Attached images -----
A detail from a page in my browser, plus the page around it.
2 images; the numbered markers in each picture match the notes below it.

## Image 1: browser-mark-….png
/…/uploads/ab12-browser-mark-….png
- Overall: home screen after login, dark mode
- Marker 1: make this bigger
- Marker 2: dark blue
- Marker 3: (marked - see the picture)

## Where this comes from
- Page: Offsite — http://localhost:3000/
- Selector: main.site > div.page > section.bento
- To see it yourself: web_open http://localhost:3000/ in your Agent Browser.
----- end of attached images -----
```

The block is fenced so an agent reads it as an attachment rather than as a
truncated prompt. And when the image came from a browser card, it carries the
page it came from plus a line telling the agent how to open that page in its
[own browser](/cards/agent-browser/).

Nothing is submitted. The text lands in the session's prompt, and you press
Enter, as with every other upload.

If you add no comment anywhere in the batch, no text block is generated at all:
you get the plain paths, the way an upload has always worked. Your drawings are
still burned into the image.

## Turning it off

**Settings → Annotate images before sending**, on macOS and on iPhone. Off, every
entry point uploads directly again. The editor is also on the upload dialog
itself, so you can switch it off in the moment it gets in your way.

## Details

- Images are PNG, JPEG, HEIC, WebP or TIFF. Anything else never sees the editor.
- The marked image is the one that travels: what you see in the editor is the
  file the agent gets.
- Images larger than 2048 px on the long edge are scaled down after the shapes
  are burned in, so the numbers stay sharp while a 10 MB retina screenshot does
  not have to travel.
- Shapes are stored in normalized coordinates and rendered by the same code that
  draws the preview and the final file, so what you see is what the agent gets.
- Marker numbers are white dots with a black border, black once commented. The
  colors are fixed so they stay readable on any screenshot.

---

# The board

Source: https://docs.offsite.sh/board/board/

Why Offsite uses a grid instead of tabs, how cards move between board, tabs and Icebox, and what Tidy board does.

Tabs were designed for a world where you write every line yourself and jump
between files. With agents, that flips: several things run at once, most of them
without you, and the question is no longer "where am I?" but "who needs me?".

So Offsite gives you a **grid board** instead. Cards sit side by side, all live,
all visible at a glance.

## Cards

**New Card** adds one. Seven kinds:

| Card | What it is |
|---|---|
| Agent session | Claude, Codex or Grok |
| Terminal | a plain login shell |
| [Git](/cards/git/) | the workspace's changes |
| [Files](/cards/files/) | browse and edit files on the host, in tabs, live |
| [Browser](/cards/browser/) | your own browser on this device, pointed at the host |
| [Agent Browser](/cards/agent-browser/) | a browser on the host that your agent drives |
| [Simulator](/cards/simulator/) | a mirrored iOS Simulator |

Drag a card to move it, drag its edges to resize. The grid keeps itself fully
packed — there are no gaps and no overlaps, ever.

Cards shrunk past a certain size drop their live view for a compact one: name,
type, and — for agent sessions — the agent's own one-line recap of what it is
doing. That is why a dense board still reads at a glance; see
[Cards that name themselves](/work/self-naming/).

## Where a card can be

[Figure: A card lives on the board, in the tab bar, or in the Icebox. Focus mode is a presentation of a card, not a fourth place.]

## Tidy board

Dragging and resizing eventually produces a mess. **Tidy board** re-lays the
cards:

- **Equal** — every card the same size.
- **Hero left** — one large card on the left, the rest tiled beside it.

Reflow only touches unpinned cards, and needs at least three of them to be
useful.

[Figure: Tidy board has two layouts: equal, where every card is the same size, and hero left, where one large card sits on the left and the rest tile beside it.]

## Pinned cards

**Pin Card** freezes a card in place. Pinning never moves anything — it means
"leave this exactly here while I rearrange everything else".

A card can only be pinned when it forms a **full edge strip**: a full-height
column at the left or right edge, or a full-width row at the top or bottom. That
constraint is what keeps the rest of the board a clean rectangle that can still
be reflowed.

Pins nest: pin the outermost column, and the next column in becomes pinnable.
Dragging a pinned card unpins it, rather than refusing the drag.

## Search

`⌘K` opens search. It looks across your workspaces, sessions and cards and jumps
to the match.

Agent cards run their CLI in fullscreen mode, which means the CLI owns its own
scrollback — so search finds *sessions*, not text inside an agent's history.

## Details

- The board grid is quantized to at most 24 columns and rows on the host, so the
  same layout renders identically from a phone to a Studio Display.
- Reflow modes on the wire are `equal` and `hero_left`; the hero slot always
  goes to the first *unpinned* card in reading order.
- Pin semantics are evaluated against the **free region** (board minus pinned
  strips), which is what makes nesting work. Pins live on the edges, which is
  what keeps the rest of the board a clean rectangle.
- Cards that support hidden chrome (`terminal`, `browser`, `mirror`) can hide
  their controls entirely — **Hide card controls** on the card menu.
- **Add to Tabs** and **Move to Icebox** live on the card menu of a board
  card.

---

# Focus mode and the card strip

Source: https://docs.offsite.sh/board/fullscreen/

Giving one card the whole window without losing sight of the others.

Some work needs the whole window. **Focus mode** gives one card the full area
and moves everything else into a **strip** along the edge, so the board is still
there — small, live, one click away.

[Figure: Focus mode turns the grid into one large card with the remaining cards as a live strip along the edge; the same shortcut toggles back.]

## Entering and leaving

- Double-click a card, or **Focus Mode** on its menu.
- `⌘⌥Return` toggles focus for the selected card — in and out, the same
  shortcut.
- **Close Focus Mode** returns to the grid.

## The strip

The other cards become thumbnails along the side. They keep updating: an agent
that finishes while you are focused elsewhere shows it in the strip, and its
status badge changes.

`⌘⌥←` / `⌘⌥→` move along the strip, so you can walk through your sessions
without leaving focus mode.

## When to use it

- Reading a long agent turn, or a diff, where board-sized cards are too cramped.
- Typing a substantial prompt.
- Driving a Simulator or a browser target, where you want real pixels.

For everything else the grid wins: several agents at once, all visible.

## Details

- Focus mode is a presentation of a card, not a placement. The card stays where
  it was on the board or in the tabs, and the session is untouched.
- Focus is per device. Focusing a card on your Mac does not change what your
  iPhone shows.
- Agent CLIs render in fullscreen (alternate-screen) mode, so a focused agent
  card has no separate scrollback for Offsite to search — the CLI manages its
  own history, and that is why card search is not offered for those cards.
- Placement changes — **Add to Tabs**, **Move to Icebox** — are board moves:
  leave fullscreen and use the card menu on the board.

---

# Keyboard control

Source: https://docs.offsite.sh/board/keyboard/

Driving the board without the mouse — and why every Offsite shortcut contains Command.

The board is fully drivable from the keyboard on macOS.

## The shortcuts

| Keys | Does |
|---|---|
| `⌘⌥` + arrows | move between cards — 2D on the grid, left/right in the focus strip |
| `⌘⌥Return` | focus mode in and out |
| `⇧⌘⌥` + arrows | swap the selected card with its neighbour |
| `⌃⌘↑` / `⌃⌘↓` | cycle workspaces |
| `⌘K` | search |
| `⌥⌘C` | copy the last command's output |

[Figure: Board navigation is two-dimensional: Command-Option plus an arrow key moves the selection to the neighbouring card in that direction, and Command-Option-Return focuses the selected one.]

## The New Workspace panel

The stepper that opens from **+** next to *Workspaces* is fully keyboard-driven
with the same `⌘⌥` chords as the board — plain arrows, Return and Esc stay with
whatever card or field has them. A hint at its top-right names the chords of the
page you are on.

| Keys | Page | What happens |
|---|---|---|
| `⌘⌥↑` `⌘⌥↓` | every page | move the cursor: source tiles, folders, projects, repositories |
| `⌘⌥Return` or `⌘⌥→` | tiles, projects, repositories | open the tile, add the project, choose the repository |
| `⌘⌥Return` or `⌘⌥→` | folder browser | enter the highlighted folder |
| `⌘⌥←` | folder browser | go up one folder |
| `⇧⌘⌥Return` | File System, clone target | Create the workspace / start the clone |
| `⌘⌥Return` | failed clone | try again |
| `⌘⌥Delete` | every page | back one step; from the first page out of the panel |
| `Tab` | pages with a text field | into the name / filter / URL field as usual |

When the new workspace lands on its empty board, the cursor is already on the
start options: `⌘⌥↑` `⌘⌥↓` pick a tool, `⌘⌥Return` starts it — the whole way
from **+** to a running agent without touching the mouse.

## Why ⌘⌥ and not plain ⌘

Two rules shaped the layout, and they explain why the shortcuts run slightly
long:

**Every Offsite shortcut contains Command.** macOS reserves Command for the
application, so a combination containing it is never delivered to the terminal.
That means Offsite can never eat a keybinding your shell, your editor or your
agent CLI depends on. Bare `Esc`, `Ctrl-C`, `Ctrl-R` and friends always belong
to the session.

**Option is there because Command alone collided with the caret.** `⌘←` and
`⌘→` are line-start and line-end in any text field, so board navigation with
plain `⌘`+arrows did nothing while you were editing a commit message or a file.
Moving to `⌘⌥` fixed it: those are not caret commands, so Offsite can intercept
them even over a focused editor, and plain `⌘`+arrows fall through to the editor
untouched.

Arrows and Return are layout-independent, so the shortcuts work the same on a
Swiss or a German keyboard.

## Details

- Implemented as a local `NSEvent` monitor on the board, which sees the key
  before the first responder. That is what lets `⌘⌥` combos win over a focused
  text view by construction rather than by luck.
- `⌘⌥Esc` is deliberately never bound — that is macOS Force Quit.
- The old shell prompt-jump binding (`⌥⌘↑`/`⌥⌘↓`) was removed because it
  collided with navigation.
- Plain `↑`/`↓` navigation inside the Git card's file list is unchanged and does
  not need modifiers.
- iOS has no keyboard shortcut layer; use the
  [command bar](/mobile/command-bar/) instead.

---

# Tabs

Source: https://docs.offsite.sh/board/tabs/

The tab bar for cards you want reachable but not on screen.

Not every card deserves screen space all the time. The **tab bar** holds cards
you want one click away without them competing for board area.

## Using it

- **Add to Tabs** on a card moves it off the board into the tab bar.
- Clicking a tab shows that card large; clicking it again returns you to the
  board.
- **Move to Board** puts it back into the grid.
- **New Tab** creates a card directly in the bar.
- **Hide tabs** / **Show tabs** collapses the bar when you want the full height.

A tabbed card is still running. This is a presentation choice, not a lifecycle
one.

## Tabs versus Icebox

They look similar and mean different things:

| | Tabs | [Icebox](/work/icebox/) |
|---|---|---|
| For | cards you switch to often | sessions you are not working with now |
| Card types | any | agent sessions only |
| Lives in | the bar above the board | the sidebar |
| Coming back | click the tab | **Move to Board**, restored to its old slot |

Rule of thumb: tabs are for *attention*, the Icebox is for *storage*.

:::note
**Pin** means one thing: [freezing a card at a board edge](/board/board/). The
strip at the top is Tabs.
:::

## Details

- Tabs are per workspace and stored with the board, so they survive restarts and
  appear identically on every device.
- A card is either on the board or in the tabs, never both; the host rejects a
  board grid and tab list that name the same card twice.
- Tab order is the order you added them; drag to reorder.
- A card in the tab bar keeps running like any other; switching to its tab
  shows exactly what it did while you were elsewhere.

---

# Dark mode, light mode and themes

Source: https://docs.offsite.sh/board/themes/

Appearance, the built-in themes, and the difference between app colours and terminal colours.

## Appearance

Offsite follows the system by default and can be pinned:

| Mode | Behaviour |
|---|---|
| Automatic | follows macOS / iOS appearance |
| Light | always light |
| Dark | always dark |

The setting is per device, so your Mac can stay dark while your phone follows
the sun.

## Themes

Three themes ship with the app — **Classic**, **Blue** and **Her** — and you can
edit them in the **Command Center**.

A theme is two separate palettes, and the split matters:

| Palette | Controls | Example |
|---|---|---|
| **App theme** | cards, sidebar, dialogs, buttons, badges, dividers | the chrome around your work |
| **Terminal theme** | the terminal surface only — foreground, background, cursor, the 16 ANSI colours, dim opacity | what your CLI draws |

They are never mixed. Terminal colours are for terminal content; app colours are
for app chrome. That is why editing your terminal background does not tint the
sidebar, and why an app accent colour can be near-black without making text
disappear.

[Figure: A schematic card in light and dark appearance. The outer surface is painted by the app theme; the inner terminal surface, including the ANSI colours, is painted by the separate terminal theme.]

## The terminal palette matters more than it looks

Agent CLIs use indexed and dim ANSI colours heavily — Claude's question text is
a dim colour, not the default foreground. Offsite installs the full 16-colour
palette plus foreground, background and cursor into every live terminal, on both
platforms. If you edit those values, edit them for both appearances: a colour
that only reads on dark will be invisible in light mode.

## Details

- Appearance is stored per device under the key
  `offsite.client.theme_appearance_mode`; values `light`, `dark`, `automatic`.
- Theme profiles ship as JSON (`classic`, `blue`, `her`) and the Command Center
  writes your edits on top of the selected profile.
- App colours have roles that are enforced in the codebase: canvas colours are
  for backgrounds and fills, text colours for text, icons and carets. The caret
  and selection tint always come from the primary text colour, never the accent
  — the accent is a canvas-group colour and may legitimately be very dark.
- Diff and code surfaces resolve their own palette, with addition and deletion
  colours defined separately from the general UI.
- The docs site you are reading uses the same palette family, which is why lime
  appears as a darkened olive in light mode: raw lime fails contrast on paper.

---

# Sending files to a session

Source: https://docs.offsite.sh/board/upload/

Getting screenshots, logs and documents from your Mac or phone into an agent's hands.

Agents work with what they can see. Uploading puts a file on the **host**, next
to the session, and hands the agent its path — so "look at this screenshot" or
"here is the failing log" works from any device.

## On macOS

- **Drag and drop** files onto a session card. Several at once is fine.
- Or use **Upload Files** on the card menu.

An overlay shows progress with an `index/total` count while a batch runs.

## On iPhone and iPad

The [command bar](/mobile/command-bar/) has an upload button with three sources:

| Source | For |
|---|---|
| Files | anything already on the device or in iCloud Drive |
| Photo library | screenshots and images you already took |
| Camera | photograph something in front of you, right now |

The camera path takes about five seconds: a whiteboard, a device screen or a
sheet of paper, photographed straight into the agent's context.

## Images stop for a moment first

An image on its way to a session opens in the
[annotation editor](/board/annotate/): circle what you mean, number it, write a
line per number. The agent gets the marked picture and your notes as text.
Anything that is not an image uploads directly, and the editor can be switched
off in Settings.

## What the agent sees

Each session has its own upload directory on the host. Uploaded files land there
with a sanitized filename, and the path is handed to the session so the agent
can read it directly.

Because the file is on the host, the agent can do real work with it — open it,
diff it, run it through a tool — instead of only seeing an inlined image.

## Details

- Upload directory: `~/.offsite/uploads/<session-id>/` on the host.
- Filenames are sanitized to `A–Z a–z 0–9 . _ -`; a name that reduces to nothing
  becomes `upload`. Directory components are stripped, so an upload can never
  escape its session directory.
- Only regular files are accepted — no directories, no symlinks.
- Uploads are user-initiated only. An agent cannot pull a file off your device.
- The transport gives no per-byte progress, which is why a batch shows a
  spinner plus a file count rather than a percentage.
- Uploads are not cleaned up automatically; the directory is yours to prune.

---

# The Agent Browser card

Source: https://docs.offsite.sh/cards/agent-browser/

A real browser on your host that your agent drives directly, with no extension or automation stack to install. You can watch it work and take over whenever you want.

An agent that writes a web app cannot see it. It can read its own code, run its
own tests, and still ship a page with the submit button behind the keyboard,
because at no point did anything look at the rendered page.

The **Agent Browser** is a real browser, running on your host, that the agent
drives directly: it opens a URL, reads the page, clicks, types, and looks at the
result. No browser extension, no plugin, no separate automation stack to install
and keep alive. It is part of Offsite, and the agent already has it.

It is also a card. So while the agent works, you watch the page move on your
board, and you can reach in and take over at any point.

[Figure: The Browser card renders a tunnelled page separately on each device, so every device has its own private session. The Agent Browser runs one browser on the host that the agent drives, and streams the same picture to every device.]

## What it is good for

**The agent checks its own work.** It opens the dev server it just started,
reads the page, clicks through the form and looks at the result. The round trip
that used to need you, *look at this and tell me what broke*, runs without you.

**Nothing to install.** No Chrome extension, no signed-in browser profile handed
to a robot, no Playwright or Puppeteer setup that has to be maintained next to
your project. The browser and the tools that drive it ship with Offsite and run
on the host the agent is already working on.

**You watch, and you can take over.** The stream shows a pointer and a click
ripple wherever the agent acts, so the card tells you what is happening to your
app right now, not afterwards in a summary. Click into it and it is a browser:
scroll, type, navigate. The agent's next command continues in the same page.

**Every screen size, without the hardware.** **Responsive** is the default and
behaves like a browser window: the page reflows to whatever size the card has.
Or pick a device: iPhone SE, iPhone 15, 15 Pro Max, iPad mini, iPad, iPad Pro
11″ or 13″, Desktop 1280×800, Desktop HD, each with the touch and mobile
behaviour the real device has.

**One browser, all your devices.** Log into your staging environment on the Mac,
pick up your phone, and you are still logged in, on the same page, at the same
scroll position. Close the app entirely and come back: the page is where you
left it.

**It runs where there is no screen.** The browser is headless, so a Linux VPS
with no desktop is a perfectly good host.

## It lives on the agent's card

By default the Agent Browser is not a separate card at all: it docks to the card
of the agent that opened it, as a small picture-in-picture tile. Ten agent
sessions mean ten browsers, each on its own card, and you still know at a glance
which one belongs to whom.

The tile has a pill that switches how much room it gets:

| Mode | What you get |
|---|---|
| **PiP** | a small view-only tile, cheap to stream, enough to see that something is happening |
| **Dock Right** / **Dock Bottom** | the browser as its own card beside the agent's output, fully interactive |
| **Full** | the browser fills the session card |
| **Hide** | nothing, until you bring it back from the card's action pill |

The mode is yours, per device: your Mac can sit in Dock Right while your phone
keeps the same browser as a tile. Offsite suggests the edge that fits the card's
shape (wide cards dock right, tall cards dock bottom), and if a card gets too
small for the docked layout, the tile takes over until there is room again.

Shrink the card further and the browser becomes a small globe badge that pulses
when the agent is working. So a board full of agents costs one video stream, not
ten: the tile sends a couple of frames a second and only when the picture
changes, and the full stream runs for the browser you enlarged.

An agent's browser follows its agent. End the session and its docked browser
ends with it, profile included. Move the session to the Icebox and the browser
stops but keeps its profile, ready when you come back. Detach the browser into a
free board card from the same pill, and it outlives the session.

`offsite web open --detached` (or `web_open(detached: true)`) creates that free
card straight away, for the case where you want a browser that is not tied to
one agent.

## What the agent can do with it

The verbs reach the agent as tools, from Offsite's own MCP server, so an agent
that supports MCP has them directly, without a wrapper or a sandbox exception:

| Tool | What it does |
|---|---|
| `web_open` | open a URL in a card next to the agent's own |
| `web_snapshot` | the page as text — the accessibility tree, one line per element, with refs like `[e12]` |
| `web_click`, `web_fill`, `web_select`, `web_type`, `web_press` | work the page by ref, CSS selector or coordinates |
| `web_screenshot` | a PNG, when only pixels answer the question |
| `web_goto`, `web_back`, `web_forward`, `web_reload`, `web_url` | navigation |
| `web_eval`, `web_wait` | run JavaScript, wait for load or for a selector |
| `web_viewport`, `web_settings` | switch device, quality, frame rate, cursor |
| `web_close` | end the card and its browser |

`web_snapshot` is the one that matters most: a text tree with stable refs is far
cheaper and far more reliable than asking a model to find a button in a
screenshot. Screenshots are for the questions only pixels answer.

The same verbs exist as a command, for agents without MCP and for you:

```bash
offsite web open http://localhost:3000
offsite web snapshot
offsite web click e12
offsite web fill e3 "ada@example.com"
offsite web screenshot --full
```

Cards belong to a workspace, so an agent can only reach the Agent Browsers in
its own.

## Using it yourself

You do not have to wait for an agent: add an **Agent Browser** card yourself,
give it a URL and start with Responsive, Desktop or Mobile. The URL is resolved
**on the host**, so `http://localhost:3000` means the host's own port 3000, with
no tunnel and no exposed port involved. A card you made this way belongs to no
agent, and any agent in that workspace can drive it.

Whatever you see in the card, you can also mark: the **Mark** button captures the
page, opens the [annotation editor](/board/annotate/), and hands the marked
picture plus your notes to an agent session, on the same path the
[Browser card](/cards/browser/) uses.

The card carries a slim bar: back, forward, reload, and the address with the page
title. On iPhone there is a keyboard button for typing into the page, and an
enlarge button when the card is too small to work in.

The settings button opens four controls:

| Setting | Options | Why you would touch it |
|---|---|---|
| **Screen** | Responsive, or a device from the catalog | check a phone layout without a phone |
| **Quality** | HD, Balanced, Fast | Fast halves the resolution — the real lever over a slow link |
| **Frame rate** | 10, 24, 30, 60 fps | lower costs less bandwidth on a remote host |
| **Agent cursor** | on / off | show or hide the pointer and click ripple |

If nothing is listening on the URL yet, the card says so and offers a retry
instead of showing you a stale page from an hour ago.

## Agent Browser or Browser?

Two browser cards, two different jobs.

| | [Browser](/cards/browser/) | Agent Browser |
|---|---|---|
| Whose browser it is | yours | the agent's — you are welcome in it |
| Runs on | the device in your hand | the host |
| Reaches the dev server via | a tunnel over your existing connection | nothing — it is on the same machine |
| Cookies and logins | per device, yours | one profile on the host, shared by your devices |
| Your personal accounts | yes, this is where they belong | none |
| After a reconnect | reloads the page | the page is still there, scrolled where you left it |
| Device emulation | no | a catalog of phones and tablets |
| Agent access | never | full, through the web tools |

Use the Browser for documentation, a deployed site, anything you are personally
logged into. Use the Agent Browser for the app you are building, and let the
agent have that one instead of anything of yours.

## What it needs

- A Chromium-family browser on the host: Google Chrome, Chromium, Brave or
  Microsoft Edge. The card names the exact install command for that machine if
  it has to.
- **Browser Use** in Host Settings, which is on by default. It is the switch
  that decides whether agents get the web tools at all, and it can stay on
  because this browser holds none of your personal logins.

Each card owns its browser and its profile: a card is a clean session that
starts where you point it and ends when you close it, so an agent always works
in a known state. Give a second page its own card.
- Both apps need to be reasonably current: the card itself needs protocol 24,
  the docked browser needs 25. An older client does not show what it cannot
  render, rather than showing something broken.

## Details

- The host runs the browser with `--headless=new` and its own user data
  directory under the host's state directory, and talks to it over the Chrome
  DevTools Protocol. Nothing is bundled with Offsite and nothing is downloaded:
  it uses the browser already installed on that machine.
  `OFFSITE_WEBSIM_BROWSER` points at a specific binary if discovery picks the
  wrong one.
- The picture is a JPEG screencast on the same channel the
  [Simulator card](/cards/simulator/) uses; input travels back over a separate
  socket. Chromium only sends a frame when something changed, so an idle page
  costs nothing.
- **Responsive** means the client reports the card's real size in CSS points
  plus its pixel ratio, and the host applies that as the device metrics, so the
  page reflows the way a browser window does rather than zooming.
- The agent cursor and the click ripple are injected into the page for the
  stream only. They are marked `aria-hidden` and are not part of your app.
- Refs from `web_snapshot` stay valid until the next navigation or snapshot.
- The docked tile and the enlarged browser are two different streams: a scaled
  screenshot at about two frames a second that only sends when the picture
  changed, and the full screencast at the quality you picked.
- The dock mode is stored per device, not on the host, so it never travels to
  someone else's screen.
- Every action is written to the host's runtime log for that card.

---

# The Browser card

Source: https://docs.offsite.sh/cards/browser/

Your own browser, on the device in your hand, pointed at the dev server on your host, with tabs, dev tools, and a way to mark what is wrong and hand it to an agent.

Your agent starts a dev server. It listens on `localhost` **on the host**, which
is a machine you may not be sitting at. Normally that is where remote work
stops.

The **Browser** card forwards that loopback port over the connection you already
have and renders the page, on your Mac and on your phone. It is your browser:
your cookies, your logins, your session. No agent can see it or touch it.

## Using it

Add a Browser card and it opens straight away, on the last URL you used in a
browser card. No dialog, no setup step.

The bar across the top is a real browser bar:

| Control | |
|---|---|
| Back, forward, reload | `⌘[`, `⌘]`, `⌘R` — and `⇧⌘R` reloads past the cache, for dev servers that serve stale bundles. `Esc` stops a load |
| The address field | type a URL, or type words to search. `⌘L` focuses it |
| History | `⌘Y`; `⌘`-click an entry to open it in a new tab. Rows carry the site's icon |
| **+** | a new tab — `⌘T`, close with `⌘W`, switch with `⌃Tab` and `⌃⇧Tab`, `⌥⌘→` and `⌥⌘←`, or `⇧⌘]` and `⇧⌘[` on a US layout; jump with `⌘1` to `⌘8`, `⌘9` is the last tab |
| Camera | send the whole page to an agent — `⇧⌘S` |
| Marquee | mark an area of the page and send that |
| Wrench | Developer Tools — `⌥⌘I`, in their own window |

`⌘F` opens find-in-page. The ports menu next to the address lists what is
actually listening on the host for this workspace (`:3000 node · Claude`), so
you can jump to a dev server without remembering its port.

Typing a different loopback port reopens the card on a new tunnel; anything else
navigates in place. And when nothing is answering yet, the card says exactly
that and offers a retry, instead of turning into a broken card that stays broken
after the server comes up.

Shrink the card and it turns into a launchpad: the current page as a cover with
its title and an address box, then your tabs, the servers running in the
workspace and recent pages, each with the site's icon. Public pages show the
preview image the site publishes for links, the same one messaging apps show;
your dev servers show a live capture of the page instead.

## Mark what is wrong, hand it to an agent

You are looking at the page the agent just built, and something is off. Instead
of describing where it is:

1. Hit the marquee button and drag a rectangle around it, or `⇧⌘S` for the whole
   page.
2. The [annotation editor](/board/annotate/) opens: circle things, number them,
   write one line per number.
3. Pick the target session, an **intent** (fix, change, question or approve) and
   add a note.

Offsite uploads the marked image to the host and pastes a block into that
session: your notes, the page URL, the CSS selector of the element you marked,
its surrounding HTML, and in a dev build of a React app the component and the
`file:line` it came from. Plus a line telling the agent how to open the same page
in its [own browser](/cards/agent-browser/).

Nothing is submitted. The text sits in the prompt; you press Enter.

If no agent session is running, the target picker offers to start one.

## This one is yours

The Browser renders on **your** device, with your cookies and your logins, and
no agent can reach it — not through a tool, not through the CLI, not by asking.
Data moves in one direction only: from you to the agent, when you send it.

The [Agent Browser](/cards/agent-browser/) is the opposite: one browser on the
host that the agent drives, showing the same page on all your devices. One is
yours, the other is the agent's, and you are welcome to watch.

## On iPhone and iPad

The card is Safari, so it behaves like Safari, including your logins and the
share sheet. Marking up a page happens in the Agent Browser card: the card menu
has **Open in Agent Browser**, which opens the same URL host-side.

## Details

- macOS forwards with `ssh -L`; iOS opens a `direct-tcpip` channel natively over
  its own SSH implementation. Both ride the connection the app already has, so
  nothing new is authenticated, no port is opened on the host, and the dev
  server stays private to your own devices.
- Forwarding targets the host's loopback interface, so a server bound to
  `127.0.0.1` is enough.
- The macOS card renders in a bundled Chromium (CEF) rather than WKWebView,
  because third-party sign-in popups do not work reliably in the latter. Screen
  captures and page JavaScript run through the Chrome DevTools Protocol.
- The browser profile is per workspace and lives on your Mac, not on the host.
- A new card opens on the last URL used in a browser card on this device, else
  the newest browser session on the host, else the Offsite start page.
- Port discovery scans the host's socket table every few seconds and maps
  listeners to sessions through the process tree; servers started outside a
  session are listed for the workspace instead.
- Stale forwards from a previous run are cleaned up when the Mac app launches.

---

# Deploy to this phone

Source: https://docs.offsite.sh/cards/deploy-to-phone/

Building an iOS app on the host and installing it on the iPhone in your hand — no TestFlight, no cable.

Your agent just built an iOS app. It is sitting on a Mac somewhere. You are not.

**Deploy to this phone** builds the project on the host and installs the result
on the iPhone you are holding — over the network, with no cable, no TestFlight
round trip and no App Store review.

Available on **macOS hosts only**.

## Using it

From the iPhone app, pick the Xcode project in the workspace and start a deploy.
The host builds it, packages it, and your phone offers to install it.

The build runs on the host's Xcode with the host's signing setup. That is where
the requirements come from.

[Figure: The host builds and signs the app, publishes the package behind a short-lived signed URL with an install manifest, and the iPhone installs it through Apple's own install mechanism.]

## What you need

| | |
|---|---|
| An Apple developer account signed in to Xcode on the host | the build has to be signed |
| Your iPhone registered with that account | a provisioning profile has to include it |
| An Xcode project or workspace in the Offsite workspace | Offsite scans a few levels deep for it |
| Push notifications registered from this iPhone | the install link is delivered as a push; if the host reports no registration, reconnect or restart the app once |

A free personal team works, with Apple's usual limits: apps expire after seven
days and some capabilities are unavailable.

## When it fails

Signing is where deploys fail, and the failure is reported as a specific kind
rather than a wall of build log:

- **No signing account** — Xcode on the host has no Apple ID.
- **Free team limitation** — the project uses a capability a personal team
  cannot sign.
- **Device not registered** — this iPhone is not in the provisioning profile.
- **Generic signing failure** — everything else, with the tail of the log.

## Details

- Deploy state lives in `~/.offsite/deploys/` on the host. Builds use a private
  derived-data directory (`~/.offsite/xcode-derived-data`) rather than the
  shared Xcode one, both to avoid macOS App Management restrictions and to keep
  your own Xcode caches untouched.
- Install path: the IPA is uploaded to a short-lived signed URL, a manifest is
  published and verified, and the phone installs through
  `itms-services://?action=download-manifest`. Apple's own mechanism, no
  sideloading tricks.
- Limits: IPA up to **500 MB**, artefacts expire after **48 hours**, the last
  **10** deploy jobs are retained.
- Project discovery scans up to 3 directory levels and skips `.git`,
  `node_modules`, `Pods`, `DerivedData`, `Carthage`, `.build` and `.swiftpm`.
- Deploys preserve the installed app's container — Offsite does not uninstall
  first, so your app's data survives a redeploy.
- A failed deploy keeps its log and a retry control at the end of the card, so
  a second attempt is one tap once you have fixed the cause.

---

# The Files card

Source: https://docs.offsite.sh/cards/files/

Browsing and editing files on the host, with tabs, live updates when the agent writes, and a real diff when your edit and the agent's collide.

The **Files** card is a file browser and editor for the workspace, running
against the host's filesystem.

It exists for the small interventions: fix a typo the agent introduced, read a
config it keeps getting wrong, check what a generated file actually contains,
without switching to a terminal card and without being at the machine.

## What it does

- Browse the workspace tree, with hidden files on or off.
- Open files in **tabs**. A path an agent mentions in its terminal
  (`docs/PLAN.md`, `Foo.swift:42`) is one click away and opens at that line.
- Edit in a syntax-highlighted editor. Unsaved work is a **draft**, marked with a
  dot on the tab.
- **Star** files you keep coming back to, and filter the tree down to starred
  files or to files with drafts.
- Search for a file by name.
- Create files and folders, delete entries, and **Open in Finder** on macOS
  hosts when you happen to be at the machine.

Tabs, drafts and stars live on the **host**, not in the app. Open three files on
the Mac, pick up your phone, and the same three tabs are there — with your
unsaved edits.

## It keeps up with the agent

The card watches the folders it is showing. When the agent, a terminal, or
anything else on that machine creates, renames or deletes a file in one of them,
it appears in the tree within a second or two. No refresh button, no wondering
whether what you see is current.

The file you have open is checked the same way, but cheaply: the card asks "has
this changed since version X?", and an unchanged file answers in a few hundred
bytes instead of resending itself.

## When you and the agent edit the same file

The draft remembers which version of the file it started from. If the file
changed on disk before you save, the card stops and shows you a **diff of the
host's version against yours**, with two explicit choices:

- **Keep my draft (overwrite host)**
- **Take host version (discard my draft)**

Nothing is decided for you, and nothing is merged behind your back.

## Speed

The card was rebuilt around the fact that its host may be a VPS on the other
side of a relay:

- Opening a file is **one round trip** instead of four.
- Directory listings and file contents are fetched **conditionally**: unchanged
  means "not modified" instead of a resend.
- Expanded folders load in parallel, and only the folders that actually changed
  reload.
- File search skips the places nobody means (`.git`, `node_modules`,
  `DerivedData`, `.build`, `Pods`, `__pycache__`), and stops after about a
  second rather than walking a monorepo to the end.
- Images over ~1 MB are scaled down **on the host** and arrive as a preview, with
  the original one button away, so a 12 MB screenshot no longer blocks the rest
  of your board.
- Typing in the editor no longer makes every other device reload its tree.

## Where it fits

Use it for the quick, surgical edit — the typo, the config value, the file you
want to read before you answer the agent. Structural work belongs in the card
next to it: describing the refactor to an agent that has the whole repository in
its head beats doing it by hand on a phone.

## Details

- All paths are resolved inside the workspace root, so the card always shows
  the project you are in.
- Saving writes through a temporary file and an atomic replace, so a failed save
  cannot leave a half-written file.
- Drafts live in the host's state database with the file version they started
  from, which is what makes both cross-device editing and the conflict check
  possible.
- The host watches at most 48 directories per connection, polling their
  modification times about once a second, and pushes only the paths that
  changed. Content changes inside the file you have open are caught by the
  versioned refresh instead.
- Image previews cap at 2048 px on the long edge; GIFs are always sent as-is so
  they keep animating.
- Files are classified from their first few kilobytes: text is editable, images
  preview, anything else is listed but not opened.
- File contents travel over the same connection as everything else; there is no
  separate file service and no port to open.
- Live updates and conditional fetches need host and app on protocol 28 or
  newer, which is anything current.

---

# The Git card

Source: https://docs.offsite.sh/cards/git/

Reviewing what your agent changed, staging it, committing and pushing — from any device.

An agent that works unattended produces a diff you did not write. Reviewing that
diff is the job, and it is the job you most want to do from the couch.

The **Git card** shows the workspace's repository: changed files, the diff for
the selected file, history and branches.

## What you can do

| | |
|---|---|
| Review | per-file diff with additions and deletions highlighted |
| Stage / unstage | per file |
| Commit | with a message you type in the card |
| Push / pull | push to the tracked remote, pull fast-forward only |
| Undo last commit | soft reset, changes stay in your tree |
| Discard changes | restore a tracked file, or delete an untracked one |
| Branches | list and switch, including tracking a remote branch |
| History | recent commits |

Everything runs `git` on the host, in the repository, as you. There is no
Offsite-specific git state and nothing to clean up if you stop using the card.

## Reading a diff on a phone

The card is built to be readable at phone width: file list first, then the diff
for the file you pick, with line numbers and hunk headers in the muted colour
and additions and deletions in their own palette.

## If the workspace is not a repository

The card offers to run `git init`. A [workspace](/work/workspaces/) does not
have to be a repository — if it is not, the card has nothing to show
until you initialise one.

## Details

Actions map to exactly these commands, run in the repository root:

| Action | Command |
|---|---|
| stage | `git add -- <paths>` |
| unstage | `git restore --staged -- <paths>` |
| discard tracked | `git restore --worktree -- <paths>` |
| delete untracked | `git clean -f -d -- <paths>` |
| commit | `git commit -m <message>` |
| undo last commit | `git reset --soft HEAD~1` |
| switch branch | `git switch <branch>`, or `git switch --track origin/<branch>` when only a remote exists |
| pull | `git pull --ff-only` |
| push | `git push` |

- Pull is **fast-forward only**: a merge that needs a decision should
  not happen behind a tap on a phone.
- Undo requires `HEAD` to have a parent; on a repository with a single commit it
  refuses rather than doing something surprising.
- Branch names starting with `-` are rejected, and every path is passed after
  `--`, so a filename can never be read as a flag.
- The workspace root is resolved to the repository root, so a workspace pointing
  at a subfolder still shows the whole repository.
- Anything beyond review, stage, commit, push and switching branches is a
  sentence to the agent in the next card — it has the repository open anyway.

---

# The Simulator card

Source: https://docs.offsite.sh/cards/simulator/

A live iOS Simulator from the host, mirrored onto your board and driven with your taps.

If your agent is building an iOS app, the fastest feedback loop is watching it
run. The **Simulator** card mirrors a Simulator running on the host onto your
board — and your taps and typing go back into it.

Available on **macOS hosts only**; a Linux host has no Simulator to mirror.

## Using it

Add a Simulator card and pick a device. The card streams the Simulator's screen
live and forwards your input:

- Tap and drag with mouse or finger.
- Type with your keyboard, or the phone's.
- **High Definition** trades bandwidth for a sharper image — worth it on a fast
  local network, less so over the relay.

Because the Simulator runs on the host, the build the agent just produced is the
build you are looking at. There is no upload step and no separate device.

## From the phone

An iOS Simulator running on your Mac at home, mirrored onto the iPhone in your
hand, driven by your thumb. Good for "does the layout break on this screen?",
and for marking what to fix instead of describing it.

## Details

- The Simulator is driven by a small broker that Offsite installs as a LaunchAgent
  in the host's **GUI login session**. That is a requirement, not an
  implementation detail: `simctl` and the Simulator app need a real window
  server, so a host that never logs in graphically cannot mirror.
- The screen arrives as an AVCC video stream; input goes back over a separate
  channel, so a slow frame never delays a tap.
- Only `simulator` is a valid mirror target today. The card type on the wire is
  `mirror`.
- If the card says *Simulator unavailable*, the usual causes are: no Simulator
  runtime installed, the host is not logged in graphically, or the broker has
  not been installed yet.
- Related: [Deploy to this phone](/cards/deploy-to-phone/) puts the same build on
  real hardware, and [Testing what you build](/testing/testing/) ties both
  together.

---

# Workspace Actions

Source: https://docs.offsite.sh/cards/workspace-actions/

Saved commands and agent prompts per workspace — run them by tap, on a schedule, or when the host restarts.

Every project has commands you run over and over: the test suite, the dev
server, the deploy script, the "check what broke overnight" prompt.

**Workspace Actions** are those commands, saved per workspace and startable with
one tap — including from your phone, where typing them would be miserable.

## Two kinds

| Kind | Runs | Good for |
|---|---|---|
| **Terminal** | a shell command in a terminal card | tests, builds, dev servers, scripts |
| **Agent** | a prompt in an agent session | recurring review, triage, summaries |

An agent action can pin the tool, the model and the
[permission mode](/work/agent-sessions/), so "run the nightly cleanup in YOLO
with Codex" is one saved thing.

## When they run

Four triggers:

- **Manual** — you tap it.
- **Schedule** — every *N* minutes, or daily at a fixed time.
- **Restart** — when the host comes back up.
- **Card** — from the card the action belongs to.

The scheduler runs on the host, so scheduled actions fire whether or not any
device is connected.

[Figure: Four triggers can start the same saved action: a tap, a schedule, a host restart, or its own card. The action carries its command or prompt plus its tool, model and permission mode, and every run lands in the run log.]

## The rerun loop

A terminal action does not just run and die. When it finishes, the card waits at
a rerun prompt: press Enter and it runs again, in the same card, with the same
scrollback above it.

That turns "run the tests" into a loop you can drive with one key, and it is why
a live action card is reused instead of piling up new cards.

## Action memory

Every action has a memory file on the host. An agent action is told to read it
before starting and may write durable learnings back into it.

This is what makes a recurring agent action get *better*: the third nightly run
knows what the first two discovered, without you re-explaining it.

## Run log

Each run is recorded with what triggered it, when it started and finished, and
its exit status. That log is how you find out that the scheduled job has been
failing since Tuesday.

## Details

- Triggers on the wire: `manual`, `schedule`, `restart`, `card`.
- Schedules are either `{kind: interval, minutes: N}` (N ≥ 1) or
  `{kind: daily, at: "HH:MM"}` in 24-hour form. Anything else is rejected.
- Action memory lives at `~/.offsite/action-memory/<action_id>.md` and is seeded
  with a short header. Deleting the action deletes its memory file.
- The scheduler holds a lock file (`~/.offsite/action-scheduler.lock`) so two
  host processes cannot double-fire an action.
- Run mode `rerun_on_enter` requires a command; the loop is only re-triggered
  while its prompt is actually up, so a busy card is never interrupted.
- A terminal action can choose what happens when it completes — keep the card,
  or close it.
- An empty Actions list opens straight into **New Action…**, so the first
  action is one dialog away.

---

# Computer Use

Source: https://docs.offsite.sh/computer-use/computer-use/

Letting an agent see and drive the host's screen — off by default, locked per session, revocable.

Some tasks need eyes. An agent that just built a Mac app cannot verify it from a
terminal; it needs to look at the window and click things.

**Computer Use** gives a session screenshots of the host's screen and the
ability to click, type and scroll on it — through a signed helper called the
**Offsite Agent Bridge**.

Available on **macOS hosts only**.

## Off by default, twice

This is the widest access Offsite can hand an agent, so it is gated twice:

1. **The feature is off** until you enable it, which requires granting macOS
   Screen Recording and Accessibility to the Agent Bridge.
2. **Every session starts locked**, even with the feature enabled. You unlock
   one specific session when you want it to have the screen.

Switching a session on or off applies to the **next** session you start, and the
card's pill shows the live state — you can always see which sessions can touch
your screen.

[Figure: Two independent gates stand between a session and your screen: Computer Use must be enabled for the host, and that specific session must be unlocked. Failing either one refuses the request.]

## The two macOS grants

| Grant | Why |
|---|---|
| Screen Recording | to take screenshots |
| Accessibility | to move the pointer, click and type |

macOS attributes both to *Offsite Agent Bridge*, the signed helper that holds
them, so the dialog names something you can recognise and check.

Offsite asks for these while you are **setting computer use up**, not in the
middle of a session, so the prompt never arrives on a screen nobody is watching.

## Automation prompts

The first time an agent scripts a specific application, macOS asks once per
target app: *"Offsite Agent Bridge wants to control …"*. The grant covers that
app and nothing else.

## Revoking

System Settings › Privacy & Security › Screen Recording / Accessibility, and
remove the Agent Bridge. Nothing else in Offsite depends on those grants.

## Details

- The Bridge is a separately signed helper with its own identity; the host pins
  that identity and refuses to talk to a binary whose signature changed
  unexpectedly.
- Communication is token-authenticated over a local channel; the token lives in
  `~/.offsite/agent-bridge/`.
- The tool surface is the standard computer-use set plus a zoom tool — screenshot,
  click, type, key, scroll, drag, cursor position and friends.
- Computer use runs on macOS hosts, through the signed Agent Bridge.
- Capture needs a screen the Mac is actually driving: a display attached, or
  the built-in one open.
- The lock is per session: if a call reports that computer use is locked,
  unlock that session from its card.

---

# Pairing devices

Source: https://docs.offsite.sh/connect/pairing/

How a device is authorised to reach a host — the QR code, the one-time token, and why one code pairs one device.

Offsite has no account, so there is nothing to log in to. A device gets access
to a host by being **authorised on that host**, once, by you.

## Pairing an iPhone

1. In the Mac app, open the host's **⋯** menu and choose **Show iPhone QR**.
2. Point the iPhone's Offsite app at the code on the *Scan on iPhone* sheet.

That transfers the host's address and its pairing material. From then on the
phone connects on its own, over whichever path is reachable.

**Passwords are never in the QR code.** What it carries is the host's address
and a one-time enrolment token; the device's own key is what authorises it
afterwards.

## One code, one device

QR tokens are **single-use**. A code that already paired one device will not
pair a second one — show a fresh QR for each device.

They are also invalidated when the host's agent restarts, so a screenshot of a
QR code from last week is not a credential lying around.

## If pairing fails

The usual cause is an already-used code. Show a fresh one from the Mac app
(the host's **⋯** menu → *Show iPhone QR*) and scan that.

:::note[Older versions]
Up to 0.1.64, the enrolment token could only be redeemed when the first
connection went through the relay. If your iPhone was on the same Wi-Fi as the
host, the app preferred the direct path, the token was never redeemed, and the
connection failed silently.

Current versions redeem the token on **every** path — local network, Tailscale
and relay — so the first connect works no matter which one wins. Hosts with the
relay switched off can pair too. If you are on an older build, update both the
host and the app.
:::

An error mentioning **Remote Login** is misleading on a current host: Remote
Login is not involved in normal operation, and the message almost always means
this device is not authorised yet.

## Per host, not per fleet

Each device pairs with each host separately. Pairing your iPhone with the Mac at
home says nothing about the VPS — scan that host's QR too.

## Details

- Enrolment is redeemed by the host's own agent, on-device, whichever path the
  connection arrived on. Authorisation no longer depends on the relay being
  enabled.
- Devices are recorded in `~/.offsite/devices.json` on the host, together with
  their per-device [notification settings](/mobile/notifications/).
- Pairing material is pinned per host on the client; a host key that changes —
  for example after a VPS rebuild — is a deliberate re-confirmation, not a
  silent reconnect.
- Scan the QR from inside the Offsite app, which reads the pairing payload
  directly.

---

# How your devices reach your host

Source: https://docs.offsite.sh/connect/paths/

Three possible paths, raced against each other, switched live — and a pill that always names the winner.

Your host is sometimes on the same Wi-Fi as you, sometimes behind a router in
another country, and sometimes both within the same hour. Offsite does not ask
you to know which.

## The three paths

| Path | When it works | Typical latency |
|---|---|---|
| **Local network** | your device and the host share a network | single-digit milliseconds |
| **Tailscale** | both machines are on the same tailnet | tens of milliseconds |
| **Relay** | always, as long as both sides can reach the internet | a hundred milliseconds and up |

[Figure: The client tries the local network, Tailscale and the relay at the same time and uses whichever answers first; when a better path appears later it switches live.]

## Racing, not configuring

The client attempts every path it knows at the same time and uses whichever
answers first. There is no "connection type" for you to pick and no wrong
choice to make.

When a better path becomes available later — you walk back into your own network
— Offsite switches to it **live**, without dropping your session.

## The pill never lies

The connection pill in the app names the path actually in use and its latency.
If it says relay, you are on the relay; if it says LAN at 7 ms, that is a
measurement, not a label.

So when something feels slow, the pill tells you whether the network or the
agent is responsible.

## Turning the relay off

The relay is optional and switchable **per host**. Switch it off and that host
is reachable only on your own network and your tailnet. Nothing else changes.

See [The relay](/connect/relay/) for what it can and cannot see.

## Details

- Endpoint kinds on the wire are `lan`, `tailscale` and `relay`; a host profile
  additionally records how it authenticates (`relay`, `directSSH`, `tailscale`).
- LAN endpoints are discovered with Bonjour, which is why macOS asks for local
  network permission on first launch. Decline it and everything still works —
  connections take a slower path.
- Every path terminates in the same place: Offsite's embedded agent on the host,
  over an SSH-backed RPC channel. There is no separate "relay mode" protocol,
  which is why a path switch does not reset your session.
- Both clients enforce connect deadlines (15 s and 30 s) so a black-holed socket
  fails instead of hanging forever.
- macOS localhost connections use the same architecture — the local host is not
  a special case.

---

# The relay

Source: https://docs.offsite.sh/connect/relay/

What the relay is, exactly what it can and cannot see, and how to switch it off.

Sometimes neither your local network nor a tailnet connects you to your host —
a hotel network, a locked-down office, cellular behind carrier NAT. The
**relay** is the path that works anyway.

It is optional, switchable per host, and deliberately built so that switching it
on does not require trusting us with your work.

## What it is

A thin pipe. Both your device and your host make an **outbound** connection to
it on port 443, and it forwards bytes between them.

That is the whole job. It does not terminate your session, does not run
anything, and does not store your work.

[Figure: Your device and your host both dial outbound to the relay on port 443, so no inbound port is open on the host. The SSH session runs end to end between device and host; the relay only forwards ciphertext it cannot decrypt.]

## What runs inside it

**Unmodified SSH.** The relay carries an SSH connection between your device and
your host's agent, exactly the same connection that runs over your local network
— the transport underneath is the only thing that changed.

So the relay sees SSH ciphertext. It cannot read your terminal, your prompts,
your code or your keys, because it never holds the keys that would decrypt them.

Your clients additionally **pin the host key**. A compromised relay could not
impersonate your host even if it tried: the pin would not match and the client
would refuse.

## What it can see

Being precise about this is more useful than reassurance:

| Can see | Cannot see |
|---|---|
| That a pairing connected, and when | Anything inside the session |
| How many bytes flowed | What those bytes are |
| The IP addresses of both ends | Your code, prompts, output or credentials |

The realistic worst case for a compromised relay is **denial of service and
connection metadata** — never content.

## No open port on your host

Because both sides dial out, your host does not need an inbound port. `sshd`
stays unreachable from the internet, your router needs no forwarding rule, and
there is no public endpoint to find or attack.

## Switching it off

Per host, in the host's settings. With the relay off, that host is reachable on
your local network and over Tailscale only — everything else works unchanged,
including [pairing](/connect/pairing/).

## Details

- Implementation: Cloudflare Workers plus one Durable Object per pairing
  (`idFromName(pairingId)`), acting as a byte pipe with a small buffer for
  whichever side arrives first.
- Access requires pairing authentication — challenge/response against the
  Ed25519 device keys your devices already use, with the registry in the Durable
  Object's storage. An unknown device cannot open a pipe.
- Latency through the relay is roughly 90 ms in a worst-case measurement with
  both ends on the same machine (four legs). Real phone-to-Mac paths tend to be
  better. The [connection pill](/connect/paths/) shows the real number.
- The relay is transport-neutral by design — the protocol is trivial enough that
  moving it onto our own servers later would change nothing for your clients.
- Push notifications are a separate channel (Firebase) and, unlike the relay,
  not end-to-end blind: they carry readable text — the session and workspace
  names — because a lock screen has to display it. Never session content. See
  [Notifications](/mobile/notifications/).
- Offsite runs **no analytics SDK and no crash reporter**. See
  [Security and privacy](/reference/security/).

---

# FAQ

Source: https://docs.offsite.sh/help/faq/

Short answers to the questions people ask before and just after installing.

## Do I need an account?

No. There is no sign-up and no server-side user. Devices are authorised against
your host by scanning a [QR code](/connect/pairing/).

## Does Offsite charge for tokens?

No, and it could not. The agent CLIs call your provider directly from your host
under your own subscription — Offsite is not in that path. See
[The big picture](/start/big-picture/).

## Is my code sent anywhere?

No. Session traffic goes between your own devices, encrypted; if it takes the
relay, the relay sees ciphertext only. The one exception is a push
notification: it carries readable text — the session and workspace names, so
your lock screen can show which agent wants you — through Firebase and Apple.
Never code, prompts or output. Full list:
[Security and privacy](/reference/security/).

## Do I have to enable Remote Login / SSH?

Not for [This Mac](/hosts/this-mac/) and not for normal operation. A
[remote Mac](/hosts/remote-mac/) needs it once, for the initial install.

## Does it work when my Mac is closed or asleep?

Sessions survive sleep and continue on wake. If you need the host to keep
working with the lid closed, use [Keep the host awake](/hosts/keep-awake/); if
you need it to come back after a restart, use
[Always reachable](/hosts/always-reachable/).

## What happens if I lose connection mid-turn?

Nothing, to the agent. It runs on the host and keeps going; you reconnect and
find the output waiting. See [Sessions](/work/sessions/).

## Can I use several agents at once?

Yes — Claude, Codex and Grok side by side on one board, each in its own card and
its own [permission mode](/work/agent-sessions/).

## Does my `AGENTS.md` / MCP setup / skills work?

Yes. Offsite starts the real CLI in your workspace folder with your shell
environment, so everything the CLI would find on its own, it finds.

## Can I run it on Linux?

As a **host**, yes — see [A Linux host](/hosts/linux/). There is no Linux client;
you drive a Linux host from the Mac, iPhone and Watch apps. Note that Claude
Code needs AVX2 on x86_64.

## Can an agent see my screen?

Only if you turn on [Computer Use](/computer-use/computer-use/) *and* unlock a
specific session for it. Off by default, macOS hosts only, revocable in System
Settings.

## Can one agent message another?

It can *read* another session and it can hand context to a **new** session, but
it can never type into a running one. The reason is a real incident, described
in [Hand off and ask](/work/handoff-and-ask/).

## Can I test what the agent built, from my phone?

Yes: a tunnelled dev server, a mirrored iOS Simulator, or the build installed
on the phone in your hand — see
[Testing what you build](/testing/testing/).

## Which machines can be a host?

Apple Silicon Macs, and Linux on `x86_64` or `arm64` — your own box, a machine
in the other room, or a VPS. See [A Linux host](/hosts/linux/).

## Is there telemetry?

No analytics SDK and no crash reporter. Feedback reaches us only when you send
it from the app.

## Something is broken

[Troubleshooting](/help/troubleshooting/) first, then
[Get help](/help/get-help/).

---

# Get help

Source: https://docs.offsite.sh/help/get-help/

Where to send a problem, and what to include so it can actually be fixed.

Offsite is in beta and the fastest fixes come from reports that contain enough
to reproduce the problem.

## Send feedback from the app

The in-app feedback form is the direct line. It reaches us with what you wrote —
and nothing else, because there is no telemetry attached to it.

Use it for bugs, confusing behaviour, and things that should exist and do not.

## What to include

A report that contains these gets fixed much faster than one that does not:

| | |
|---|---|
| App and host version | both, from the host row in the sidebar |
| Host type | This Mac, a remote Mac, or Linux |
| Which device | Mac, iPhone, Watch |
| Connection path | what the [pill](/connect/paths/) said — LAN, Tailscale or relay |
| What you did | the click path, not the conclusion |
| What happened | including the exact message, if there was one |

The version pair matters more than it looks: several symptoms that read like
network bugs are really an app and host that no longer speak the same protocol.
See [Updating Offsite](/start/updating/).

## Before you send

Two checks that resolve a good share of reports on their own:

1. **Are the app and the host on the same release?** If not, update both and
   fully restart the app — a running app keeps its old protocol even after the
   bundle on disk was replaced.
2. **Is it in [Troubleshooting](/help/troubleshooting/)?** Known issues are
   listed there with what actually fixes them.

## Release notes

Every version is described at
[offsite.sh/releases](https://offsite.sh/releases). If something changed under
you, that is where it is written down.

---

# Troubleshooting

Source: https://docs.offsite.sh/help/troubleshooting/

Known messages, quirks and errors around Offsite, each with the reason and what fixes it.

Everything on this page is a symptom we have seen, with the reason behind it
and the step that resolves it. It grows with what we find and what you report.

Your agent knows this page. Paste a message into a session and ask why it
appeared; the agent finds the entry and walks you through the fix. If a symptom
is missing here, [send it in](/help/get-help/) with the exact text.

## Messages from macOS

### "Support Ending for Intel-based Apps" names Offsite Host Service

![macOS notification titled Support Ending for Intel-based Apps. It reads: This version of "Offsite Host Service" includes a component that will not work with a future release of macOS.](../../../assets/help/macos-intel-apps-notice.png)

**Symptom:** macOS Tahoe shows this notification, and the app it names is
*Offsite Host Service*.

**Why:** Apple is retiring Rosetta, the layer that runs Intel-only programs on
Apple silicon. Since macOS Tahoe, the system posts this notice whenever an
Intel-only program starts, and it credits the notice to the process responsible
for that program. Everything you run inside an Offsite session (a terminal
command, an agent, a tool the agent calls) runs under the Offsite Host Service,
so when one of those programs is Intel-only, the notice names Offsite. The host
service itself is an Apple silicon build.

The usual culprits are tools installed years ago as standalone Intel binaries:
a CLI downloaded from a vendor's installer, an old Homebrew under
`/usr/local`, a Node package that shipped a prebuilt Intel binary, a project
toolchain fetched for the wrong architecture.

**Fix:** find the Intel-only program and replace it with an Apple silicon
build. Package managers ship the right architecture, so `brew install …` or
`npm install -g …` over the old copy resolves it. To check a single tool:

```bash
file "$(which firebase)"
# "Mach-O 64-bit executable x86_64"        → Intel-only, runs under Rosetta
# "Mach-O universal binary … x86_64 arm64" → fine
```

To list every Intel-only tool on the paths a session uses:

```bash
for f in /usr/local/bin/* ~/.local/bin/*; do
  [ -x "$f" ] && lipo -archs "$f" 2>/dev/null | grep -qv arm64 && echo "$f"
done
```

The notice is informational. Until Apple removes Rosetta, the Intel-only tool
keeps working exactly as before.

## Setup and pairing

### Pairing the iPhone fails while on the same Wi-Fi

**Symptom:** you scan the QR code, the app shows the host, but **Connect** does
nothing: no error, no connection.

**Why:** on the first connection, your iPhone still has to be authorized on the
host (that is what the QR code's one-time token is for). Today that
authorization only happens when the connection goes through the Offsite relay,
but when your iPhone and the host share a network, the app prefers the direct
local path, where the token is never redeemed. The host then rejects the
unknown device, and the app currently stays silent about it.

**Fixed in current versions:** the host now redeems the QR token on every
connection path (local network, Tailscale, and relay), so the first connect
works no matter which path wins. If you are on an older version: turn Wi-Fi
off on the iPhone for the very first connect (so it uses the relay once and
gets authorized), then turn Wi-Fi back on. All later connections work
normally. Update both the host and the iPhone app to get the fix.

### "Check that Remote Login is healthy on the Mac"

This older error text can appear when a connection is rejected during login.
On hosts set up with current Offsite versions, Remote Login is **not** involved.
The message usually means your device is not authorized yet (see above: scan a
fresh QR from the Mac app, ⋯ menu → *Show iPhone QR*). QR tokens are
single-use: a QR that already paired one device will not pair a second one.

---

# Uninstalling and resetting

Source: https://docs.offsite.sh/help/uninstall/

Removing Offsite from a host and from a device, in the order that leaves nothing behind.

Offsite keeps itself in one directory plus a few named services, so removing it
is short. Do it in this order — stopping the services after deleting their files
leaves orphaned jobs behind.

## Remove a host

### 1. End your sessions

From the app, end the sessions you care about cleanly. Anything still running in
tmux will otherwise be killed with the agent.

### 2. Turn the opt-in services back off

In the app, switch off [always reachable](/hosts/always-reachable/) and hand
sleep control back with **Allow host sleep**. That is the supported path and it
removes the services properly.

If the app is already gone, clean up by hand. Find what is actually installed
rather than guessing at names — Offsite installs several helpers and their
labels differ between builds:

```bash
# macOS — what is registered
launchctl list | grep -i offsite
ls ~/Library/LaunchAgents  | grep -i offsite
ls /Library/LaunchDaemons  | grep -i offsite
```

Then unload and delete what you found:

```bash
# user agents
launchctl bootout "gui/$(id -u)/<label>"
rm ~/Library/LaunchAgents/<label>.plist

# the privileged sleep helper, if you installed it
sudo launchctl bootout system/com.rapidrocket.offsite.power-helper
sudo rm -f /Library/LaunchDaemons/com.rapidrocket.offsite.power-helper.plist
sudo rm -f /Library/PrivilegedHelperTools/com.rapidrocket.offsite.power-helper
```

```bash
# Linux
systemctl --user list-units | grep -i offsite
systemctl --user disable --now <unit>
loginctl disable-linger "$USER"     # only if you enabled it for Offsite
```

### 3. Delete the state directory

```bash
rm -rf ~/.offsite
```

That removes the host agent, session state, uploads, archives, action memory,
deploy artefacts and Offsite's tmux config in one go. See
[What Offsite puts on your machine](/reference/on-your-machine/) for what each
of those was.

Your repositories are untouched — Offsite never wrote into them.

## Remove the app

- **macOS**: quit Offsite and delete it from Applications.
- **iOS**: delete the app.

### Revoke macOS permissions

If you used [Computer Use](/computer-use/computer-use/), remove the Agent Bridge
from System Settings › Privacy & Security › **Screen Recording** and
**Accessibility**. Local Network permission for the app lives under Privacy &
Security › Local Network.

## Just starting over

You do not need to uninstall to get a clean host. Deleting `~/.offsite` and
running setup again rebuilds everything; the app reinstalls the host components.

Deleting a **workspace** in the app removes only Offsite's record of it — the
folder on disk stays.

## Details

- Paired devices live in the host's `devices.json`; deleting the state directory
  de-authorises every device, and they will need a fresh
  [QR code](/connect/pairing/) afterwards.
- Client-side host profiles and credentials are in the system keychain and are
  removed with the app.
- Offsite never modified your `~/.tmux.conf`, your `~/.ssh` or your shell
  configuration, so there is nothing to undo there.
- Remote Login, if you enabled it to set up a
  [remote Mac](/hosts/remote-mac/), was your change — turn it off in System
  Settings › General › Sharing if you no longer want it.

---

# Always reachable

Source: https://docs.offsite.sh/hosts/always-reachable/

Making a host survive a reboot and answer before anyone logs in — what it installs and what it costs.

By default the Offsite agent runs in your login session. That is enough for
most days: the host answers while you are logged in, and sessions survive the
app closing, the network dropping and the lid closing.

It is *not* enough for one case: the machine restarts while you are away, and
nobody logs in. **Always reachable** fixes that case.

## What it does

Offsite registers its agent as a system service, so the host comes back on its
own after a restart, before any user logs in.

| Platform | Mechanism |
|---|---|
| macOS | a LaunchDaemon, installed once with your administrator password |
| Linux | a systemd user service plus `loginctl enable-linger <user>` |

You can switch it on during setup or later from the host's settings.

## What it costs

- **One administrator prompt on macOS**, at the moment you enable it. macOS
  shows it as *"Offsite wants to make changes."*
- **A background item.** macOS will notify you that software from
  "RapidRocket GmbH" can run in the background — that is the certificate holder,
  which is Offsite's publisher. You can review it under System Settings ›
  General › Login Items & Extensions.

Declining costs you nothing else: the rest of Offsite keeps working and the host
stays reachable while you are logged in.

## What it pairs with

Always reachable covers the login: the host answers even when nobody is signed
in at that machine. Two companions complete the picture:

- [Keep the host awake](/hosts/keep-awake/) — so a laptop with the lid closed
  stays available instead of sleeping.
- [How your devices reach your host](/connect/paths/) — the path your devices
  take to get there, from the same LAN to the relay.

## Details

- Sessions survive a host restart in two steps: tmux sessions are recreated from
  Offsite's own session state, and each agent is resumed with its own CLI
  mechanism (`claude --resume`, `codex resume`), wired per tool. Offsite keeps
  an archive copy of the resume artefacts so a transcript cleanup on the CLI
  side cannot orphan a session.
- Reboot restore is Offsite's own, rather than global tmux tooling
  (`tmux-resurrect`, `tmux-continuum`) — restore is owned by Offsite's own state,
  so it never depends on your tmux configuration.
- On Linux, a user service without lingering stops at logout. `loginctl
  enable-linger` is the whole difference between "survives reboot" and "survives
  until you log out".

---

# Managing several hosts

Source: https://docs.offsite.sh/hosts/fleet/

Running more than one host, switching between them, and what "warm" means in the host list.

Nothing stops at one host. A laptop, a desktop and a VPS can all be hosts at the
same time, and one app switches between them.

What Offsite does **not** do is orchestrate across them. Each host owns its own
workspaces, sessions and boards; switching hosts switches which machine you are
looking at. There is no cross-host scheduler and no shared session pool.

## The host list

Every host in the sidebar shows:

- its **name** — the machine's own name, not a role,
- the **path** currently in use (local network, Tailscale or relay) with its
  latency,
- a **warmth badge**.

| Badge | Meaning |
|---|---|
| Warm | a connection is established and ready |
| Warming | connecting, or reconnecting after a drop |
| Cold | no connection right now |

Offsite keeps hosts you use warm so switching is instant rather than a fresh
login every time.

## Adding hosts

- **Set Up This Mac…** — the machine you are on. See [This Mac](/hosts/this-mac/).
- **Add Remote Host…** — another Mac or a Linux box over SSH. See
  [A second Mac](/hosts/remote-mac/) and [A Linux host](/hosts/linux/).

Each host is set up individually and holds its own copy of the host components.

## Choosing what runs where

A rough guide that holds up in practice:

| You want | Put the host on |
|---|---|
| iOS work — Simulator, deploy to phone, Computer Use | a Mac |
| Long unattended runs | a machine that never travels |
| Web/backend work only | anything, including a cheap VPS |
| Work on the repo you are editing locally | the machine that has the repo |

Sessions do not move between hosts. Your repository lives on one machine, and
the agents that work on it live there too.

## Details

- Host connection profiles carry endpoint kinds `lan`, `tailscale` and `relay`;
  the client races them and uses the winner. See
  [How your devices reach your host](/connect/paths/).
- Each device pairs with each host separately. Pairing your iPhone with host A
  says nothing about host B.
- Host settings — relay on/off, always reachable, sleep control, version and
  update — are per host, not global.
- Known limitation: adding a host on iOS can displace an existing one. If you
  run several hosts, add them on the Mac.

---

# Keep the host awake

Source: https://docs.offsite.sh/hosts/keep-awake/

Stopping a Mac host from sleeping while your agents work — timed, reversible, and visible in the toolbar.

A MacBook that goes to sleep takes your agents with it. Nothing crashes — the
sessions are still there when it wakes — but nothing progresses either, and your
phone shows a host that stopped answering.

Offsite can hold the host awake for a bounded stretch of time.

## Using it

The host toolbar has a power control:

- **Disable host sleep** — pick how long. The button then reads
  **Host sleep disabled** for as long as it is active.
- **Allow host sleep** — hand control back immediately.

Durations are fixed and always finite:

| | | | | | |
|---|---|---|---|---|---|
| 15 min | 30 min | 1 h | 3 h | 6 h | 12 h |

There is no "forever". A window that always expires is the point: forget about
it and the Mac goes back to normal power behaviour on its own, instead of
quietly staying awake in a bag.

## The one-time install

Changing the system sleep setting needs root, so the first use installs a small
privileged helper and asks for your administrator password once. After that,
switching sleep on and off needs no further prompts.

If you would rather not install it, **Install power helper** is the only thing
that stops working — the rest of Offsite is untouched.

:::note[Closing the lid]
Disabling sleep keeps the machine running with the lid closed on power. On
battery, macOS still has the last word. If a MacBook is your permanent host,
leave it plugged in.
:::

## Linux hosts

Not applicable — a Linux host stays up. The control does not appear.

## Details

- Implementation: `pmset SleepDisabled`, set through a LaunchDaemon-installed
  privileged helper (`com.rapidrocket.offsite.power-helper`) over a local
  socket. The app never runs `sudo pmset` itself.
- Allowed durations in seconds: `900, 1800, 3600, 10800, 21600, 43200`.
- The current state is read back from `pmset -g`, so a value changed outside
  Offsite is reflected rather than overwritten.
- This is about the *host's* sleep, not your client's. Your Mac or iPhone can
  sleep freely — sessions are host-owned.
- Related but different: [Always reachable](/hosts/always-reachable/) covers the
  machine coming back after a restart, not staying awake now.

---

# A Linux host

Source: https://docs.offsite.sh/hosts/linux/

Running Offsite on a Linux box or VPS — requirements, the CPU check that keeps Claude happy, and what a Linux host carries.

Linux is a first-class **host**. A VPS, a box under the desk, a workstation in
the office — anything you can SSH into can run your agents. There is no Linux
*client*; you drive a Linux host from the Mac, iPhone and Watch apps.

## Requirements

| What | Detail |
|---|---|
| SSH access | key or password, for the initial install |
| `python3` | present on essentially every distribution |
| `curl` or `wget` | minimal Debian images may need `apt-get install curl` |
| `tmux`, `git` | installed for you via `apt`/`dnf`/`yum`/`pacman` (needs sudo) |
| systemd user session | for the Offsite agent |
| An agent CLI | Claude Code, Codex or Grok, installed and logged in |

## The CPU trap

Check these two before you rent a VPS:

- **glibc ≥ 2.28** — that is Ubuntu 20.04+ or Debian 10+.
- **Claude Code additionally needs AVX2 on x86_64.** Budget KVM hosts often
  expose a generic QEMU CPU without it, and Claude's installer then spins
  forever instead of failing. Codex and Grok run without AVX2.

Offsite preflights both before installing, so a machine that cannot work says so
up front. You can check yourself:

```bash
grep -q avx2 /proc/cpuinfo && echo "AVX2 ok" || echo "no AVX2 — Claude will not run"
ldd --version | head -1
```

## Always reachable on Linux

The agent runs as a systemd **user** service. For it to survive logout and
reboot, the user needs lingering:

```bash
loginctl enable-linger <user>
```

See [Always reachable](/hosts/always-reachable/).

## What runs on it

Everything the work itself needs: agent sessions, terminals, git, files, the
[Browser](/cards/browser/) and [Agent Browser](/cards/agent-browser/) cards,
notifications, and resume after a reboot — identical to a Mac host.

The Apple-specific cards stay with Apple hardware: the iOS Simulator, deploy to
your phone and Computer Use need macOS, so keep a Mac in your fleet for iOS work
and let the Linux box carry everything else. Both can be hosts at the same time;
the app switches between them in a tap.

## Details

- Distribution support: Ubuntu and Debian on `x86_64` and `arm64` are the
  tested targets. Others generally work if the package manager is one of
  `apt`/`dnf`/`yum`/`pacman`.
- Bootstrap runs from the Mac app over SSH; the host components land in the
  connecting user's `~/.offsite`, exactly as on macOS.
- Host-only install (no Mac app on hand): on the server run
  `curl -fsSL https://get.offsite.sh/setup.sh | sh`. It installs the host and
  opens the terminal setup wizard (agents, reachability, connect QR); then use
  **Connect to existing host** in the Mac or iOS app.
- A systemd unit that reports `inactive` while the process is clearly running
  has been seen after a manual install; re-running setup from the app fixes the
  unit registration.
- Sleep/wake is a macOS concern — [Keep the host awake](/hosts/keep-awake/) does
  not apply to Linux hosts, which stay up.

---

# A second Mac as a host

Source: https://docs.offsite.sh/hosts/remote-mac/

Setting up another Mac over SSH — what that machine needs, and why Remote Login is only needed once.

A second Mac — the desktop under your desk, a Mac mini in a cupboard, a machine
at the office — makes a good host. It has the horsepower, it never travels, and
its lid is never closed on it.

Unlike [This Mac](/hosts/this-mac/), this path starts over SSH, so the remote
machine has to let you in **once**.

## On the remote Mac

1. **Enable Remote Login**: System Settings › General › Sharing › Remote Login.
2. Make sure it is reachable from your Mac — same network, a tailnet, or a
   routable address.
3. Everything from [Prerequisites](/start/prerequisites/) applies to it:
   Apple Silicon, macOS 14+, Command Line Tools, tmux, at least one agent CLI
   installed **and logged in** under the user you will connect as.

## In the app

**Add Remote Host…**, then give the address and the user. You can authenticate
with a password or an SSH key.

Offsite probes the machine, installs its host components into that user's
`~/.offsite`, and starts the agent. From then on your devices talk to the
embedded agent, not to the system `sshd` — the initial Remote Login was for the
install.

:::caution
The agent CLIs must be logged in **as the host user**, not as you on your
laptop. A `claude` that is authenticated in your local terminal tells you
nothing about the remote machine. This is the single most common reason a fresh
remote host has a healthy tmux and no working agent.
:::

## Root versus a normal user

Prefer a normal user account with sudo over `root`:

- Claude Code refuses `--dangerously-skip-permissions` when running as root, so
  the YOLO permission mode is unavailable there.
- Everything Offsite installs lands in that user's home directory, which keeps
  the blast radius small.

## Details

- All bootstrap probes run with `BatchMode=yes` and short connect timeouts, so a
  machine that wants an interactive password fails fast instead of hanging.
- Probe output is parsed as `key=value`, never as prose — a noisy login shell
  that prints a banner does not break setup. One known exception is the
  architecture probe; a `.zprofile` that echoes before returning can confuse it.
- Sessions on a remote Mac behave exactly like local ones: host-owned tmux,
  survive disconnect and reboot, restored with the CLI's own resume.
- Deploy-to-phone and Computer Use are tied to the *host* machine: an iOS build
  runs on the host's Xcode, and Computer Use drives the host's screen.

---

# This Mac as a host

Source: https://docs.offsite.sh/hosts/this-mac/

Turning the Mac you are sitting at into a host — what the setup does, what it does not touch, and what the name means.

**Set Up This Mac…** turns the machine you are sitting at into a host. It is the
shortest path to a working Offsite, and it is the one most people should start
with.

:::note[About the name]
"This Mac" means *the Mac the app is running on right now*. Once it is a host it
appears in your host list under its own machine name, like every other host — so
from your iPhone you never see "This Mac", you see the machine. The phrase only
exists on the setup screen, where "this" is unambiguous.
:::

## What setup does

The setup screen runs a health check, then installs the host components into
`~/.offsite`. Each row is either already green or carries the button that fixes
it:

| Row | Checks | If it is red |
|---|---|---|
| Developer Tools | Apple Command Line Tools — the real `git` and `python3` | **Install…** starts Apple's own installer; setup waits and continues by itself |
| Homebrew & tmux | sessions run inside tmux | one click copies the official Homebrew command and opens Terminal; tmux itself is installed for you |
| Offsite Host | the host runtime in `~/.offsite` | installed for you |
| Update Server | `get.offsite.sh` is reachable and the build is published | check your network, then **Check Again** |
| Agents | at least one agent CLI is installed and on `PATH` | install one yourself, then **Refresh Agents** |
| macOS Prompts | nothing — it announces which system dialogs are coming | — |

## What it does not touch

This is the part worth stating plainly, because most remote-development tools
need all of it:

- **No Remote Login.** Setting up This Mac does not enable System Settings ›
  Sharing › Remote Login and does not open port 22.
- **No SSH configuration.** No keys in `~/.ssh`, no `authorized_keys` edits, no
  `sshd_config`.
- **No admin password** — unless you opt into
  [always reachable](/hosts/always-reachable/) or the
  [sleep helper](/hosts/keep-awake/), which say so before they ask.
- **No account.** There is no sign-up and no user record anywhere.
- **No global tmux config.** Offsite never writes `~/.tmux.conf` and never
  installs tmux plugins; its sessions run on their own tmux sockets with their
  own config file.

Offsite reaches the local host through its own embedded agent, over the same
SSH-backed RPC path it uses for every other host, so this Mac behaves like any
other host in your fleet.

## After setup

The host appears in the sidebar. From there:

- The host's **⋯** menu → **Show iPhone QR** starts pairing — see
  [Pairing devices](/connect/pairing/).
- The host row carries its version and an **Update** button — see
  [Updating Offsite](/start/updating/).
- The connection pill names the path in use, which for This Mac is loopback.

## Details

- Host components install to `~/.offsite`: `bin/` (agent and helpers),
  `sessions/`, `state.db`, `workspaces.json`, `devices.json`, `settings.json`,
  `tmux/`. Full map: [What Offsite puts on your machine](/reference/on-your-machine/).
- The health check is a *preflight report*; each row maps to a component the
  bootstrap service probes independently, so a red row never blocks the rows
  below it.
- Agent CLI detection reports three states per tool — found, not found, or not
  verified. "Not verified" means the binary exists but did not answer a version
  probe; that is usually a CLI that wants a login first.
- Host artifacts are published for Apple Silicon (`macos-arm64`).

---

# The iOS command bar

Source: https://docs.offsite.sh/mobile/command-bar/

The row above the keyboard that makes a terminal usable with thumbs.

A touch keyboard has no `Esc`, no `Ctrl`, no arrow keys and no `Tab`. A terminal
needs all four. The **command bar** is the row above the keyboard that puts them
back, plus the things you actually reach for on a phone.

## What is on it

| | |
|---|---|
| Keys | `Esc`, `Ctrl`, `Tab`, arrows and the other keys the touch keyboard lacks |
| Upload | files, photo library, or the camera — see [Sending files](/board/upload/) |
| Paste | the clipboard into the session |
| Mic | [voice input](/mobile/voice/) |
| Keyboard | show and hide the keyboard without losing your place |
| Clear | wipe a half-typed prompt |

## It is configurable, per tool

The rows are not fixed. Open the **Command Center** editor from the bar and
build the layout you want — and it is stored *per tool*, because what you need
in Claude is not what you need in a shell.

Typical use: put the approve and deny keys for your agent's permission prompts
on the first row, so answering from a lock screen is one tap rather than a hunt.

**Compact mode** shrinks the buttons when you would rather have more terminal
than more bar.

## Why not just the keyboard

Because the most common mobile interaction with an agent is not typing a
paragraph. It is answering: *yes*, *no*, *option 2*, `Esc`, `Ctrl-C`. Those are
single taps if the bar is set up, and a fight with a touch keyboard if it is
not.

## Details

- Button rows are stored per tool on the device
  (`IOSCommandCenterStorage`), and compact mode under
  `ios_command_bar_compact_mode`.
- Every button in a mode shares one height, so no row is visually taller than
  another.
- The mic button lives in the bar, but the transcript bubble renders at card
  level so it can overlay the terminal without resizing it — the terminal never
  reflows mid-dictation.
- Voice needs your own OpenAI key; the bar offers the setup sheet when it is
  missing.
- macOS has no command bar; it has [keyboard control](/board/keyboard/) instead.

---

# The iPhone and iPad app

Source: https://docs.offsite.sh/mobile/iphone/

The same sessions, the same board, sized for a device you hold.

The iOS app is not a companion, a viewer or a cut-down remote. It attaches to
the same host-owned sessions your Mac does, with the same input.

What you see on the phone is the terminal running on your Mac, right now.

## What it does

- Every workspace and every card on the host.
- Full terminal input — type, scroll, select, paste.
- [Upload files](/board/upload/) from Files, the photo library or the camera.
- The [command bar](/mobile/command-bar/) for keys a touch keyboard does not
  have.
- [Voice input](/mobile/voice/) when typing is not practical.
- [Notifications](/mobile/notifications/), with a tap straight into the session.
- [Testing](/testing/testing/): tunnelled dev servers, mirrored Simulator, and
  installing an iOS build on the phone itself.

## Getting started

Install the app, then scan the pairing QR code shown by the Mac app. See
[Pairing devices](/connect/pairing/).

No account, no sign-up. The phone talks to your host directly — over the local
network, Tailscale, or the relay, whichever is reachable. See
[How your devices reach your host](/connect/paths/).

## Working on a small screen

- Tap a card to bring it up large; the rest stay live behind it.
- The command bar sits above the keyboard and is configurable per tool.
- Sessions keep running when the app goes to the background, because they were
  never running in the app to begin with.

## Details

- iOS 18 or newer.
- The app reconnects with exponential backoff, capped at 30 s in the foreground
  and 120 s in the background, and resets the backoff when the network path
  changes — so walking from cellular into Wi-Fi reconnects immediately instead
  of waiting out a timer.
- Live cards revive after a long background stretch by comparing connection
  epochs, so a frozen stream is detected rather than displayed.
- The Watch app talks to the host **through** the paired iPhone. See
  [Apple Watch](/mobile/watch/).

---

# Notifications

Source: https://docs.offsite.sh/mobile/notifications/

What Offsite tells you about, on which device, and why it is not screen scraping.

An agent that finished four minutes ago while you were looking elsewhere has
cost you four minutes. Notifications are how Offsite gives that time back.

## What fires

Four events, each switchable **per device**:

| Event | Default | Fires when |
|---|---|---|
| Turn completed | on | the agent finished and is idle again |
| Input requested | on | the agent is waiting for you — a question, a permission prompt |
| Session ended | off | the session's process exited |
| Errors | off | something went wrong |

The two events that mean *you are now the bottleneck* are on by default; the
noisier two wait until you ask for them.

## Per device, not per account

Every device you have paired carries its own settings. Your Watch can tap you
while your phone stays silent, or the Mac can stay quiet while you are sitting
in front of it.

## They name the session

A notification carries the session's name, so you know *which* agent wants you
before you unlock anything. Tapping one opens exactly that session.

"waiting for input" is noise; "api-refactor is waiting for input" is
information. You do not have to arrange that yourself — agent sessions
[name their own cards](/work/self-naming/), and your own rename overrides
theirs.

## Not screen scraping

Offsite does not watch the terminal for phrases like "waiting for input". It
subscribes to the CLIs' own lifecycle interfaces — hooks, where the CLI has them
— so the signal is the agent actually reporting its state.

A CLI update changes its wording all the time. Its hook contract stays put, so
the signal survives the next release.

[Figure: The agent CLI reports lifecycle events through its own hooks; the host decides whether an event is worth a notification and fans it out to each device according to that device's own settings.]

## What a push actually contains

A lock-screen notification has to be readable text, so this part is not
encrypted end-to-end. When your device is not currently attached, the host sends
the event to a Firebase function we run, which hands it to Firebase Cloud
Messaging and Apple's push service:

| Travels | Example |
|---|---|
| The session's name | `api-refactor needs your input` |
| The workspace's name | `…is waiting for approval or instructions in offsite.` |
| Event type, timestamp, and ids for host, workspace and session | — |

Nothing else does: no prompt, no agent output, no file, no diff, no path, no
command.

Two things keep this small by default. A push is only sent to a device that is
**not connected in the foreground** — with the app open, the same event arrives
over your own encrypted connection and Firebase is not involved. And with
notifications off for a device, nothing leaves the host for it at all.

Since agent sessions [name themselves](/work/self-naming/), that name is usually
a description of the work — which is exactly what makes the notification useful,
and something to keep in mind if a project name is sensitive. The full picture
is in
[Security and privacy](/reference/security/).

## Details

- For Claude, Offsite registers hooks for `SessionStart`, `UserPromptSubmit`,
  `Stop`, `Notification` matching `permission_prompt`, and `PreToolUse` matching
  `AskUserQuestion|ExitPlanMode`. Each one reports the event back to the host,
  which decides whether it is worth a notification.
- For Codex, Offsite uses Codex's `notify` command plus its lifecycle hooks
  (`SessionStart`, `UserPromptSubmit`, `PermissionRequest`, `Stop`). Codex only
  runs a hook it has been told to trust; Offsite normally passes the hook and
  its trust to each session it starts, so nothing is written to your Codex
  configuration and Codex never asks. If that per-session path is unavailable
  on a host, a Codex card shows a **Codex hook** chip: allow it, and Offsite adds
  one entry to `~/.codex/hooks.json` — Codex then asks you once, on its next
  start, to trust it ("Trust all and continue"). Decline, and Codex sessions keep
  working on the `notify` signal alone. `offsite-host codex-hooks uninstall`
  removes the entry; resetting the host removes it too.
- Push delivery to phones and Watch rides Firebase Cloud Messaging, via a
  function we run. The payload is the event, the session and workspace names,
  and the ready-made title and body built from them — never the content of your
  session.
- The title and body are templates, not anything the agent wrote:
  "*name* needs your input" / "*name* is waiting for approval or instructions in
  *workspace*". The agent's recap is not part of them.
- Our function stores no notification text; it logs a push-token id, a status,
  a hashed IP and a timestamp. Transport past that point is Google's and
  Apple's.
- The Watch complication is refreshed by a separate *silent* push that carries
  no text — it only prompts the app to fetch state over your own connection.
- Attention resolves when a device that is actually looking at the session acks
  it; a background app does not silently clear a notification you never saw.
- Notification settings live per registered device in the host's `devices.json`.
- Attention is per session, so a busy board still resolves to one tap on the
  card that actually wants you.

---

# Voice input

Source: https://docs.offsite.sh/mobile/voice/

Dictating prompts on iPhone and Watch, with live transcription and a fallback for bad networks.

Typing a paragraph of context on a phone is unpleasant enough that you write
less than you mean to. Dictation fixes that, and the prompts get better because
you stop economising.

## On the iPhone

Tap the mic in the [command bar](/mobile/command-bar/) and talk. The transcript
appears live while you speak, in a bubble over the terminal — you can see the
words landing and stop when you have said enough.

Review it, edit if needed, then send.

## On the Watch

The Watch can answer an agent's question by dictation, straight from the
notification. For the common case — an agent asking something while you are away
from both your Mac and your phone — this is the shortest path from question to
answer that exists here.

## Your key, your account

Transcription uses **your own OpenAI API key**, entered once in the app. Offsite
does not run a speech service and does not proxy your audio.

One setup step, and your recordings go to a provider you already have an
account with.

## When the network is bad

Live transcription streams while you talk. If the connection is not good enough
for that, Offsite falls back to recording the clip and transcribing it in one
request — slower to appear, but it does not lose what you said.

## Details

- Live mode streams PCM audio to a realtime transcription session; the fallback
  posts the finished recording to the REST transcription endpoint.
- The transcript bubble is rendered at card level, not inside the command bar,
  so the terminal does not resize while you dictate.
- The Watch path runs through the paired iPhone, like everything else on the
  Watch.
- Words land in the prompt as you speak them, so you can see and edit the text
  before it goes anywhere.

---

# Apple Watch

Source: https://docs.offsite.sh/mobile/watch/

Answering an agent from your wrist — notifications, tap answers, dictation and a live complication.

The Watch answers one question well: **does anything need me right now?**

## What it does

- **Notifications** on your wrist when a turn finishes or an agent is waiting.
- **Tap answers** for structured questions — an agent asking "1, 2 or 3?" is
  three taps, not a trip to a laptop.
- **Dictated replies** for anything longer. See [Voice input](/mobile/voice/).
- **A live tail** of a session, so you can see what is happening without opening
  anything else.
- **A complication and Smart Stack widget** showing agent status and how many
  sessions need you.

## How it connects

The Watch talks to your host **through the paired iPhone**, over
WatchConnectivity.

So the iPhone has to be reachable — on your wrist's
Bluetooth range or the same network. A Watch alone on a mountain will not drive
your agents.

We state this plainly rather than implying the Watch talks to the host
directly, because knowing it changes what you can rely on.

## Why it is useful

Not for doing work on a watch — for *not having to check*. An agent that runs
for twenty minutes taps you when it is your turn.

## Details

- Message payloads between phone and Watch are bounded (WatchConnectivity caps a
  single message at 64 KB), so the Watch receives status and short content, not
  full transcripts.
- The complication updates from pushed state, not by polling the host.
- Watch delivery depends on the notification category being right; a
  notification that arrives on the phone but not the Watch is almost always a
  category mismatch rather than a network problem.
- Notification routing is per device, so the Watch can be the only thing that
  taps you. See [Notifications](/mobile/notifications/).

---

# Architecture

Source: https://docs.offsite.sh/reference/architecture/

What runs where, how clients and host talk, and why the design has the properties it has.

Enough detail to judge whether the design is sound, without a tour of the source
tree.

## The shape

[Figure: Thin clients talk to a host agent over an SSH-backed RPC channel. The agent owns session state and supervises tmux sessions, which run the agent CLIs and shells.]

## The host agent

One process per host owns everything: session records, board layout, workspace
list, device registry, notification routing, and supervision of the tmux
sessions.

Clients are deliberately thin. They render host state and send input. This is
why two devices showing the same session cannot disagree — there is only one
copy of the truth, and it is not on either of them.

## The RPC channel

All clients talk to the host over an **SSH-backed RPC channel** — including the
macOS app talking to a host on the same machine.

There is no localhost fast path. That is a design rule, not an oversight: a
special case for the most-used configuration would be the one code path with its
own bugs, exercised most and tested least. Localhost gets the same architecture
as a VPS in another country, so a fix for one is a fix for both.

The transport underneath can be your local network, Tailscale or the relay. See
[How your devices reach your host](/connect/paths/).

## Sessions in tmux

Every session runs in tmux, on its **own socket**, with Offsite's own config
file. Offsite never touches your `~/.tmux.conf` and never requires tmux plugins.

tmux is what makes a session outlive the app, the network and the host agent
itself: updating the host restarts the agent, and the sessions do not notice.

Restore after reboot is owned by Offsite's own session state plus each CLI's
resume mechanism — never by global tmux tooling like `tmux-resurrect`.

## State

Host state lives in `~/.offsite`: a SQLite database for session and board state,
JSON files for workspaces, devices and settings, and directories for uploads,
session archives and helper installs. See
[What Offsite puts on your machine](/reference/on-your-machine/).

## What this buys you

| Property | Because |
|---|---|
| Sessions survive everything | they belong to host-owned tmux, not to a client |
| Devices never disagree | one authoritative state, on the host |
| No vendor in your loop | the CLIs call your provider directly |
| Localhost is not a special case | one connection architecture for every host |
| Your tmux stays yours | Offsite-owned sockets and config, always |

## What we do not detail here

Sync and revision semantics, the rendering and snapshot pipeline, connection
racing heuristics and the notification state machine are deliberately out of
scope. They are the parts most likely to change, and knowing them does not help
you decide whether Offsite fits your work.

## Details

- Host and clients negotiate a **protocol version**, with a documented minimum
  on both sides. See [Updating Offsite](/start/updating/).
- Compatibility policy: additive fields only unless the protocol version
  changes; host state migrates forward; a schema mismatch must never silently
  delete data; destructive resets are explicit user actions.
- Notifications are driven by CLI hook events reported back to the host, not by
  reading the screen.
- The macOS app bundles Chromium (CEF) for browser cards; third-party sign-in
  popups do not work reliably in WKWebView.
- Host components are published per version and pulled over HTTPS from
  `get.offsite.sh`.

---

# What Offsite puts on your machine

Source: https://docs.offsite.sh/reference/on-your-machine/

Every directory, process and helper Offsite installs on a host — and how to remove them.

Everything Offsite installs on a host lives under one directory, plus a small
number of named helpers you opt into. This page lists them so you can check
rather than trust.

## The state directory

Everything host-side is under `~/.offsite`:

| Path | Contains |
|---|---|
| `bin/` | the host agent, the relay agent and helper binaries |
| `sessions/` | per-session records |
| `state.db` | session and board state (SQLite) |
| `workspaces.json` | your workspaces |
| `workspace-discovery.json` | the cached folder-suggestion list |
| `devices.json` | paired devices and their notification settings |
| `settings.json` | host settings |
| `tmux/` | Offsite's own tmux config — never your `~/.tmux.conf` |
| `uploads/<session-id>/` | files you sent to a session |
| `session-archives/` | resume artefacts, so a CLI cleanup cannot orphan a session |
| `action-memory/<action-id>.md` | [Workspace Action](/cards/workspace-actions/) memory |
| `deploys/`, `xcode-derived-data/` | [deploy-to-phone](/cards/deploy-to-phone/) jobs and a private build cache |
| `shell-wrappers/` | per-session shell shims |
| `agent-bridge/` | [Computer Use](/computer-use/computer-use/) helper and its token |
| `*.log` | timing and delivery logs |

Nothing is written into your repositories. A [workspace](/work/workspaces/) is a
path Offsite remembers, not a folder it modifies.

## Processes

| Process | When |
|---|---|
| Host agent | whenever the host is running |
| One tmux server per session | while that session exists |
| Relay agent | only if the relay is enabled for this host |
| Simulator broker | macOS, only if you use Simulator cards |
| Agent Bridge | macOS, only if you enabled Computer Use |

## Things that need root

Two, both opt-in, both announced before they ask:

| Helper | For |
|---|---|
| `com.rapidrocket.offsite.power-helper` (LaunchDaemon) | [keeping the host awake](/hosts/keep-awake/) |
| The always-reachable service (LaunchDaemon / systemd) | [surviving a reboot](/hosts/always-reachable/) |

The standard setup needs neither.

## Ports

None, inbound. Offsite does not open a listening port on your host and does not
require Remote Login. Every connection is outbound from both ends. See
[How your devices reach your host](/connect/paths/).

## Removing it

See [Uninstalling](/help/uninstall/).

## Details

- The state directory can be relocated with `OFFSITE_STATE_DIR`, which is mostly
  useful for testing against a throwaway state.
- Directories and files are created with restrictive permissions.
- The `.offsite` directory itself is refused as a workspace root.
- On Linux the same layout applies under the connecting user's home directory.
- Client-side, the macOS and iOS apps keep host profiles and credentials in the
  system keychain, not in the state directory.

---

# Security and privacy

Source: https://docs.offsite.sh/reference/security/

What leaves your machine, what does not, and where the sharp edges are.

Offsite runs on machines you own and talks to services you already pay for. This
page states exactly what that means, including the parts that are not
comfortable.

## No account

There is no sign-up, no user record and no server-side identity. Devices are
authorised against your host by [pairing](/connect/pairing/) with it.

Nothing to breach, because there is nothing stored.

## No telemetry

No analytics SDK. No crash reporter. We removed the one we had.

Feedback reaches us only when you send it from the app, deliberately, with
whatever you chose to write in it.

## Your tokens are yours

The agent CLIs call Anthropic, OpenAI or xAI **directly from your host**, under
your own subscription and your own credentials. Offsite never sees an API key,
never proxies a request, and cannot meter your usage because it is not in the
path.

## What leaves your machine

| What | Where | Content |
|---|---|---|
| Session traffic | between your devices, direct or via the relay | encrypted SSH; the relay sees ciphertext only |
| Push notifications | our Firebase function → FCM → Apple | readable text: the **session name** and the **workspace name** — see below |
| Update checks | `get.offsite.sh`, `offsite.sh` | version queries and downloads |
| Deploy artefacts | a signed short-lived URL, only when you deploy | the IPA you asked to install, expiring after 48 h |
| Feedback | our feedback endpoint, only when you send it | what you typed |

Your code, your prompts and your agent output are not in that table, because
they do not leave your machines.

## Notifications are the one readable thing

Worth being blunt about, because it is the only place where words describing
your work leave your machine.

A push notification is not encrypted end-to-end. It travels from your host to a
Firebase function we run, on to Firebase Cloud Messaging and Apple's push
service, and then to your device — and it has to be readable text, or your phone
could not display it on the lock screen. What it carries:

- the **session name** — "api-refactor needs your input"
- the **workspace name** — "…is waiting for approval in offsite"
- ids for the host, workspace and session, the event type and a timestamp

The session name deserves a second look: agent sessions
[name themselves](/work/self-naming/), and a good self-chosen name says what the
work is. "auth-migration" on a lock screen is a small but real disclosure. If a
project's *name* is sensitive, rename the card yourself — your name always wins —
or turn notifications off for that device.

The agent's one-line recap stays on your machine today. If it ever moves into
the notification, it would be the same class of information as the name: a
sentence the agent wrote about your work, readable in transit.

What is *not* in a push: your prompts, the agent's output, file contents, diffs,
commands, paths. And two things reduce the exposure by default:

- A push is only sent to a device that is **not currently connected in the
  foreground**. When the app is open and attached, the same event arrives over
  your own encrypted connection and never touches Firebase at all.
- Notifications are per device and per event type. Turn them off and nothing
  goes out — see [Notifications](/mobile/notifications/).

The function we run logs only a push-token id, a status, a hashed IP and a
timestamp; the notification text is not stored on our side. But Google and Apple
transport it, and their handling is theirs, not ours.

## The relay

Optional, per host, and end-to-end blind: it forwards SSH ciphertext between two
outbound connections and holds no key that could decrypt it. Clients pin the
host key, so a compromised relay cannot impersonate your host. Worst case is
denial of service and connection metadata.

Full detail: [The relay](/connect/relay/).

## Your host is not exposed

Setting up [This Mac](/hosts/this-mac/) does not enable Remote Login, does not
open port 22, and does not touch your SSH configuration. Both ends of every path
dial outbound.

## The sharp edges

An honest list, because pretending these away would be worse:

- **YOLO permission mode** lets an agent run anything in that workspace without
  asking. That is the point of it, and it is a real risk. Bound the blast
  radius: a workspace you can restore, a host user that is not root.
- **Computer Use** gives a session your host's screen and input. Off by default,
  locked per session, and revocable in System Settings — but while it is on, it
  is real control of a real machine.
- **Uploads go to the host**, in cleartext on that filesystem, and are not
  cleaned up automatically.
- **Anything an agent reads can influence it.** A file, a web page or a
  repository can contain text aimed at your agent. That is a property of agents,
  not of Offsite, and Offsite does not filter it.
- **The clipboard**: Offsite gates terminal-driven clipboard writes (OSC 52) so
  a session cannot silently overwrite what you are about to paste.

## Details

- Offsite never writes `~/.tmux.conf`, never installs tmux plugins, and never
  depends on your global tmux state — its sessions run on Offsite-owned sockets
  with an Offsite-owned config file.
- Host state is stored with restrictive permissions under `~/.offsite`.
- The Agent Bridge is a separately signed helper whose identity the host pins; a
  binary whose signature changed unexpectedly is refused rather than trusted.
- Deploy artefacts expire after 48 hours and the last 10 jobs are retained.
- The Watch complication and widget are refreshed by a *silent* push that
  carries no text at all — it only tells the app to fetch fresh state from your
  host over your own connection.
- Bootstrapping a remote host asks for that machine's credentials once, over
  SSH, in batch mode — no credential is stored on our side, because there is no
  our side.
- The macOS app and its helpers are signed and notarised by RapidRocket GmbH,
  which is the name macOS shows you in background-item and permission dialogs.

---

# The big picture

Source: https://docs.offsite.sh/start/big-picture/

Why Offsite exists, what runs where, and how the loop from prompt to test closes on the device in your hand.

Offsite is an agentic development environment built on the CLI. Your coding
agents run on a real machine that you own. Your Mac, iPhone and Watch are live
surfaces onto that machine.

Nothing sits between the agent and its provider. Nothing sits between you and
the agent.

[Figure: Your host runs the real agent CLIs, which call the frontier providers directly with your own keys. Your Mac, iPhone and Watch are live mirrors of that host over LAN, Tailscale or the relay.]

## Why the CLI is the harness

The labs that build the frontier models also build the best harness for them,
and they ship it as a command-line tool. `claude`, `codex` and `grok` are where
new capabilities land first: new models, new tools, MCP servers, skills, hooks.
A third-party wrapper is always a release behind, and always a subset.

So Offsite does not wrap them. It starts the real binaries, with your config,
your MCP servers, your skills, your subscription and your keys. When a CLI ships
something new, you have it the same day — on your Mac and on your phone.

That is also why Offsite never touches your tokens. The CLI talks to Anthropic,
OpenAI or xAI straight from your machine. Offsite resells no compute and meters
nothing.

## Your machine, from anywhere

An agent session is a long-running program. It should not die because you closed
a laptop.

So sessions belong to the host, not to the app. They run in host-owned tmux:
close the lid, lose Wi-Fi, quit the app, reboot the machine — the work carries
on, and Offsite brings the conversation back through the CLI's own resume.

Your devices reach the host over whichever path is fastest and actually
reachable: direct on the local network, over Tailscale, or through an
end-to-end-blind relay that you can switch off per host. The path switches live
when a better one appears, and the connection pill always names the one in use.

The point is not remote access. The point is that it stops mattering which
device you are holding. Same board, same sessions, same input, same moment — as
if you were sitting in front of the machine.

## Your agents tell you when they need you

An agent that finished four minutes ago while you were looking elsewhere has
cost you four minutes.

Offsite notifies you when a turn finishes and when an agent is waiting for your
input. Both are on by default; session ended and errors are off. Every device
you have paired carries its own settings, so your phone can stay quiet while
your Watch taps you.

Notifications name the session, so you know which agent wants you, and tapping
one opens exactly that session. They are built on the CLIs' own hook and
notification interfaces rather than on scraping the screen, which is why a CLI
update does not quietly break them.

## The loop closes on the device in your hand

Prompting from a phone is table stakes. Testing is not — and testing is where
remote work usually breaks down and sends you back to the desk.

[Figure: You prompt from any device, the agent works on the host, and the result comes back to the device in your hand as a tunnelled dev server, a mirrored Simulator or an installed build — so you can test it and prompt again without returning to the Mac.]

There are three ways back to you, depending on what you are building:

- **A web app.** The dev server your agent just started listens on the host.
  Offsite tunnels it to the device in your hand, so you open the app and tap
  through it for real.
- **An iOS app in the Simulator.** The host's Simulator runs as a card on your
  board, mirrored live, with your taps and typing going back into it.
- **An iOS app on the actual phone.** *Deploy to this phone* builds on the host
  and installs the result on the iPhone you are holding. No TestFlight detour,
  no Mac in sight.

Then you say what is wrong, from the same device. Prompt, work, test, prompt.

## Next

[Hosts, sessions and clients](/start/overview/) names the three pieces the rest
of these docs use. After that, [Prerequisites](/start/prerequisites/) and
[Install & set up](/start/install/) get you running.

---

# Your first session

Source: https://docs.offsite.sh/start/first-session/

From a paired host to a working agent, through workspaces, the board, and what happens when you walk away.

Your host is set up and your phone is paired. This page gets you from there to
an agent that is actually working.

## 1. Pick a workspace

A **workspace** is one folder on the host, with its own board and its own
sessions. Press **+** next to *Workspaces* in the sidebar and choose one of
three doors: browse the host's **File System**, pick an **Existing Project**
your agents already touched, or clone a **Remote Repository** onto the host.

It does not have to be a git repository. If the folder you pick happens to sit
inside one, Offsite snaps the workspace to the repository root, because that is
almost always what you meant. Otherwise the folder itself is the workspace. See
[Workspaces](/work/workspaces/).

## 2. Start a session

On an empty board, **Start a new session…**. Pick a tool:

| Tool | What you get |
|---|---|
| Claude | the real `claude` CLI |
| Codex | the real `codex` CLI |
| Grok | the real `grok` CLI |
| Terminal | a plain login shell |

The session opens as a card. It runs on the host, in the workspace folder, with
your shell environment: the same `PATH`, the same config, the same MCP servers
and skills the CLI would find if you had typed the command yourself.

If a tool is missing from the list, its CLI is not installed on that host. See
[Install & set up](/start/install/), step 3.

## 3. Work

Type into the card. There is no send button and no separate prompt
box, because the card *is* the terminal.

While the agent runs, the card shows what it is doing. When it stops, you get a
notification on whichever devices you allowed. See
[Notifications](/mobile/notifications/).

## 4. Add the cards you actually want

Use **New Card** to put more on the board. Beyond sessions there are four
built-in card types:

- **Git** — the workspace's changes, stage, commit, push.
- **Files** — browse and edit files on the host.
- **Browser** — a tunnelled web target, usually your dev server.
- **Simulator** — a mirrored iOS Simulator running on the host.

Drag cards to move them, drag their edges to resize. **Tidy board** puts
everything back into an even grid.

## 5. Walk away

Close the app. Shut the lid. Get on a train.

The session belongs to the host, not to the app, and it runs in
tmux there. When you open Offsite again, on the Mac or on the phone, the card is
where you left it and the output arrived while you were gone.

Try it once on purpose: start something long, quit the app, come back.

## Next

- [Workspaces](/work/workspaces/) — what a workspace is and is not
- [The board](/board/board/) — cards, tabs, focus mode, keyboard control
- [Agent sessions](/work/agent-sessions/) — permission modes, models, resume

## Details

- Workspaces are stored per host in `~/.offsite/workspaces.json`; the workspace
  id *is* its absolute root path.
- *Existing Projects* lists folders your agents already ran in plus git
  repositories under your home directory. That is only a suggestion list —
  **File System** accepts any directory, and **Remote Repository** clones one
  onto the host (see [Workspaces](/work/workspaces/)).
- Card types on the wire are `terminal`, `browser`, `mirror`, `diff` and
  `files`. Session tools are `claude`, `codex`, `grok`, `terminal`, `browser`
  and `mirror`.
- A session gets `OFFSITE_SESSION_ID`, `OFFSITE_WORKSPACE_ID` and
  `OFFSITE_TOOL` in its environment. Agents can read those and call the
  [`offsite` CLI](/agents/for-agents/) with them.

---

# Install & set up

Source: https://docs.offsite.sh/start/install/

Download the Mac app, set up This Mac as your first host, and pair your iPhone by scanning a QR code.

Setting up Offsite is three moves: install the Mac app, let it set up This Mac
as a host, then pair your phone. Nothing here needs an account.

Before you start, skim [Prerequisites](/start/prerequisites/), especially if
this is a fresh Mac.

## 1. Install the Mac app

Download the app from [offsite.sh](https://offsite.sh/download/macos), open the
DMG and drag **Offsite** into your Applications folder. The app is signed and
notarised by RapidRocket GmbH, so macOS opens it without a Gatekeeper detour.

## 2. Set up This Mac

On first launch, choose **Set up This Mac**. The setup screen runs a health
check and then installs the host components into `~/.offsite`. Each row is
either already green or carries the button that fixes it:

| Row | What it checks | If it is red |
|---|---|---|
| Developer Tools | Apple Command Line Tools — the real `git` and `python3` | **Install…** starts Apple's own installer. Setup waits and continues by itself. |
| Homebrew & tmux | Sessions run inside tmux | One click copies the official Homebrew command and opens Terminal. Paste, run, and setup picks up from there. tmux itself is installed for you. |
| Update Server | `get.offsite.sh` is reachable and the host build is published | Check your network, then **Check Again**. |
| macOS Prompts | Nothing — it announces which system dialogs are coming | — |

Two things on this screen:

- **Always reachable** is optional. Switch it on and Offsite installs its agent
  as a system service, so this Mac is reachable from your phone after a restart,
  before anyone logs in. macOS asks for your administrator password once. Leave
  it off and the host runs while you are logged in.
- **Remote Login stays off.** Setting up This Mac does not need SSH, does not
  need port 22, and does not change your Sharing settings.

[What macOS will ask you](/start/what-macos-asks/) lists every system dialog in
the order it appears, and why each one is there.

## 3. Install at least one agent CLI

Offsite runs the real agent binaries; it does not ship its own. Install and log
in to at least one of:

- **Claude Code** — `claude`
- **Codex CLI** — `codex`
- **Grok CLI** — `grok`

Use each vendor's own installer and log in once in a terminal. Offsite then
finds them and offers them when you create a session; **Refresh Agents**
re-scans after you install one.

:::note
On a fresh Mac this is the step people forget. Host and tmux can be perfectly
healthy while the Agents row stays empty: that row waits for an agent CLI
yet.
:::

## 4. Pair your iPhone

Install the Offsite app on your iPhone (iOS 18 or newer), then, in the Mac app,
open the host's **⋯** menu and choose **Show iPhone QR**. Point the phone at the
code.

That transfers the host's address and its pairing material. Passwords are never
part of the code. From then on the phone connects on its own, directly on your
network, over Tailscale, or through the relay, whichever is reachable.

## 5. Open your first session

Create a session on the host, pick a working directory and an agent, and start
typing. The session runs on the Mac inside tmux: close the lid, lose Wi-Fi, quit
the app — the agent keeps going, and the output is waiting when you come back.

## Adding more hosts

The same app sets up other machines too — another Mac over SSH, or a Linux
server. Those paths need a bit more of the machine up front; see
[Prerequisites](/start/prerequisites/).

---

# Hosts, sessions and clients

Source: https://docs.offsite.sh/start/overview/

The three pieces every other page in these docs builds on.

[The big picture](/start/big-picture/) explains why Offsite works the way it
does. This page names its three pieces, which the rest of the docs assume you
know.

## The three pieces

### Hosts

A **host** is a machine that runs your work: This Mac, another Mac, or a Linux
server. It holds your repositories, runs the agent CLIs, and keeps every session
alive whether or not a client is connected.

You can have several hosts at once and switch between them. Each one is set up
individually — see [Prerequisites](/start/prerequisites/) for what a machine
needs.

### Sessions

A **session** is one long-running program on a host, shown as a card:

- an agent CLI (Claude Code, Codex, Grok),
- a plain terminal,
- or one of the built-in tools — the iOS Simulator, your own browser, and the
  Agent Browser that runs on the host for your agent.

Sessions live in tmux on the host, so closing the app, losing Wi-Fi or putting
your Mac to sleep does not stop them. Your agents keep working; you reconnect
and find the output waiting.

### Clients

The **clients** are how you see and drive those sessions:

- **macOS app** — the full board, with cards you can drag, resize and focus.
- **iPhone / iPad app** — the same sessions, live, with the same input.
- **Apple Watch** — notifications, agent questions you can answer by tap or
  dictation, and a live status complication. It works through your paired
  iPhone.

All clients show the same host-owned session. There is no separate mobile
version of your work: what you see on the phone is the terminal that is running
on your Mac, in real time.

## How your devices reach the host

Offsite tries every available path and uses the fastest one that works:

- **Direct** on the local network,
- **Tailscale**, if the machines share a tailnet,
- **Relay** — an optional, end-to-end-blind path for when neither of the above
  is reachable. It can be switched off per host.

The connection pill in the app always names the path actually in use, and
switches live when a better one appears — for example when you walk back into
your own network.

## Nothing of yours on our side

- **No account.** There is no sign-up and no user record on our side. Devices
  pair with your host by scanning a QR code.
- **No telemetry.** No analytics SDK, no crash reporter. Feedback reaches us
  only when you send it from the app.
- **No model of its own.** Offsite bills you nothing for tokens because it never
  touches them; the agent CLIs talk to your provider directly.

## Next

Start with [Prerequisites](/start/prerequisites/), then
[Install & set up](/start/install/).

---

# Prerequisites

Source: https://docs.offsite.sh/start/prerequisites/

What you need before installing Offsite, per platform, with what Offsite sets up for you automatically.

Offsite checks most of this for you: the **Set up This Mac** screen shows a
health check with one-click fixes. This page is the reference for what those
checks expect, and for setting up remote hosts, where you prepare the machine
yourself.

## Mac as host ("This Mac")

| Requirement | Details | Offsite helps |
|---|---|---|
| Apple Silicon Mac | M1 or newer; host artifacts ship for `macos-arm64` | — |
| macOS 14 (Sonoma) or newer | App and host helpers target macOS 14.0 | — |
| Command Line Developer Tools | Provide real `git` and `python3` (a bare Mac only has stubs). Roughly 2–3 GB | Health check row with an **Install…** button; setup continues automatically |
| Homebrew — or tmux installed any other way | Sessions run inside tmux; Offsite installs tmux via `brew` automatically | Health check row: one click copies the official brew.sh command, opens Terminal, and setup continues once done |
| At least one agent CLI | Claude Code, Codex CLI, or Grok CLI — installed and logged in | Setup shows an Agents row with guidance |
| Network access | `offsite.sh` (app download + updates) and `get.offsite.sh` (host components) over HTTPS | Health check row verifies the update server |

**Explicitly NOT required:** macOS Remote Login (System Settings → Sharing),
SSH configuration of any kind, an admin password for the standard setup.
Offsite runs the local host directly and connects through its own embedded
agent, so port 22 can stay closed.

**Optional (asks for admin once):** "Always reachable" installs the agent as a
LaunchDaemon so the host survives reboots and runs before login.

## Remote Mac as host

Everything from the table above, plus:

- **Remote Login enabled** (System Settings → General → Sharing → Remote
  Login) — the initial install runs over SSH. After setup, sessions use
  Offsite's embedded agent.
- Reachable from your Mac via SSH (LAN, Tailscale, or public address).

## Linux as host

- SSH access (key or password) to the machine.
- `python3`, plus `curl` or `wget` (present on almost every distribution;
  minimal Debian images may need `apt-get install curl`).
- `tmux` and `git` — installed automatically via `apt`/`dnf`/`yum`/`pacman`
  (needs sudo) if missing.
- systemd user session for the Offsite agent; for "always reachable" also
  `loginctl enable-linger <user>`.
- At least one agent CLI (Claude Code, Codex CLI, or Grok CLI), logged in.

## iPhone / iPad app

- iOS 18 or newer.
- Pairing happens by scanning the QR code shown during host setup, with no
  account required.

## Disk space (rule of thumb)

| What | Size |
|---|---|
| Offsite app (DMG) | ~160 MB |
| Host components (runtime, agent, helpers) | ~120 MB installed |
| Apple Command Line Tools (if missing) | ~2–3 GB |
| Homebrew + tmux (if missing) | ~1 GB |

## Next

[Install & set up](/start/install/) walks through the actual setup, and
[What macOS will ask you](/start/what-macos-asks/) lists every system dialog you
may see along the way.

---

# Updating Offsite

Source: https://docs.offsite.sh/start/updating/

How the app and the host update, why their versions have to match, and what a mismatch looks like.

Offsite ships as **two** things that update separately: the app on your device,
and the host components on each machine that runs your sessions. They speak a
versioned protocol to each other, so they have to stay compatible.

## The app

The Mac app checks for updates on its own and offers **Update Offsite** when one
is available. It downloads the new build, verifies its signature, and swaps
itself.

The iPhone app updates through the channel you installed it from.

## The host

Host components live in `~/.offsite` on the host machine and are updated from
the app: open the host's settings and use **Update** next to the host version.
**Refresh versions** re-checks both without changing anything.

Updating the host restarts its agent. Your sessions are **not** killed by this —
they live in tmux, which outlives the agent process. Connected clients drop and
reconnect.

## Why the versions matter

Each release carries a protocol version, plus the oldest protocol it still
accepts:

| Field | Meaning |
|---|---|
| `protocol_version` | what this build speaks |
| `minimum_supported_client_protocol_version` | oldest app a host will serve |
| `minimum_supported_host_protocol_version` | oldest host an app will talk to |

If your app is older than a host's minimum, the host refuses it. The failure is
not always loud: the symptom people hit is **"my typing does nothing"** or
"an update seems to fail" against a host that is otherwise healthy.

Before assuming a transport bug, check the two version numbers. If they are
incompatible, fully quit and restart the app — a running app keeps its old
protocol even after the bundle on disk was replaced.

:::note
Update the host **and** the app together when you update either. They are
released as a pair, and the release notes for a version describe both.
:::

## Release notes

Every version has an entry on [offsite.sh/releases](https://offsite.sh/releases).
The in-app update prompt links to the same anchor.

## Details

- Current release: app `0.1.66`, runtime `0.1.66`, protocol `23`, minimum
  supported client and host protocol `19`.
- Compatibility policy (`UPGRADE_PATH.md`): new fields may only be added when
  older clients and hosts keep working; existing field meanings never change
  without a protocol bump; host state migrates forward and a schema mismatch
  must never silently delete data; destructive resets are always an explicit
  user action, never an upgrade side effect.
- Host artifacts are pulled from `get.offsite.sh` over HTTPS. The setup health
  check has an **Update Server** row that verifies exactly that reachability.
- If an update download fails immediately after a release is announced, the
  binaries may not have finished publishing. Retrying a minute later is the fix.

---

# What macOS will ask you

Source: https://docs.offsite.sh/start/what-macos-asks/

Every system prompt and notification you may see while setting up Offsite on a Mac, in order, with the reason and what you get for it.

macOS is deliberately noisy about apps that install background services or need
system access. Everything below is expected during Offsite setup: the setup
screen announces each one before it appears.

## During "Set up This Mac"

### 1. Apple's Command Line Tools installer

Appears when you click **Install…** in the Developer Tools row.

**Why:** a bare Mac ships only stubs for `git` and `python3`. The Offsite host
needs the real ones. **What you get:** the same toolchain any local development
needs — this is Apple's own installer, not ours. Offsite waits and continues
automatically when it finishes.

### 2. Administrator password: "Offsite wants to make changes."

Appears once, and only if you enable **always reachable**.

**Why:** Offsite registers its host agent as a system service. **What you get:**
this Mac stays reachable from your phone after a restart, before anyone logs
in. Cancelling skips only this option; everything else keeps working, and the
host is then reachable while you are logged in.

### 3. Notification: "App Background Activity"

> Software from "RapidRocket GmbH" can run in the background.

**Why:** macOS names the certificate holder, not the app. RapidRocket GmbH is
Offsite's publisher. **What the items are:** the Offsite agent and its session
helpers — the processes that keep your sessions alive when the app is closed.
You can review them anytime under System Settings › General › Login Items &
Extensions.

### 4. "Allow 'Offsite' to find devices on local networks?"

Appears right after **Launch Host**, when the app looks for its host the first
time.

**Why:** Offsite discovers your host on the local network (Bonjour) so devices
on the same network can connect directly. **What you get:** the fast LAN path,
lower latency and no detour through the relay, whenever your Mac and your phone
share a network. If you decline, everything still works; connections simply
always take the relay path.

## Later, only if you enable Computer Use

### 5. Screen Recording and Accessibility for "Offsite Agent Bridge"

**Why:** the Agent Bridge is the signed helper that takes screenshots and
performs clicks for agent sessions; macOS gates both capabilities behind these
two switches. **What you get:** agents can see and drive the screen — for
example to test an app they just built. Off by default, and every session
additionally starts locked until you unlock it.

### 6. "Offsite Agent Bridge is requesting to bypass the system private window picker…"

Appears on the first screenshot after you grant Screen Recording — Offsite
triggers it right in the settings moment so it does not interrupt your first
agent session — and macOS repeats it periodically (roughly monthly, and after
restarts).

**Why:** since macOS 15, apps that capture the screen programmatically (without
the interactive window picker — which is the only way an agent can take
screenshots) get this extra, recurring confirmation on top of the Screen
Recording permission. Every screen-capture tool gets it; it cannot be turned
off. **What you get:** confirmation that agents can keep taking screenshots;
clicking *Allow* is all that is needed.

### 7. Automation prompts per app

> "Offsite Agent Bridge wants to control …"

**Why:** macOS asks once per target app the first time an agent runs AppleScript
against it. **What you get:** scripted control of that specific app, and nothing
else — the grant does not extend to other apps.

## Later, during everyday use

### 8. Folder access: "'offsite-relay-agent' would like to access files in your Documents folder."

Appears the first time a session, the workspace file browser, or any host
process reads a macOS-protected folder (Documents, Desktop, Downloads — also
network volumes and removable drives, each asked separately).

**Why:** everything you run through Offsite executes under Offsite's background
agent, so macOS attributes the file access to that agent — that is why the
prompt names the raw binary `offsite-relay-agent` instead of "Offsite".
**What you get:** sessions and the file browser can work with projects inside
that folder. If you keep your code elsewhere (for example `~/git`), you can
decline — macOS asks again on the next real access.

## What you will NOT be asked

- No Apple ID, no account.
- No Remote Login / SSH activation for "This Mac".
- No admin password for the standard setup (only for the optional
  *always reachable* service).

---

# Testing what you build

Source: https://docs.offsite.sh/testing/testing/

Three ways the thing your agent just built reaches the device in your hand.

Prompting from a phone is table stakes. **Testing** is where remote development
usually gives up and sends you back to the desk.

Offsite closes that loop four ways, depending on what you are building. One of
them lets the agent close it without you.

[Figure: Three paths carry what the host built back to the device in your hand: a tunnelled dev server, a mirrored iOS Simulator, or the build installed on the phone itself.]

## Which one

| You are building | Use | Works from | Host |
|---|---|---|---|
| A web app you want to tap through yourself | [Browser card](/cards/browser/) | Mac, iPhone, iPad | macOS or Linux |
| A web app your **agent** should check, or a layout on a device you do not own | [Agent Browser](/cards/agent-browser/) | Mac, iPhone, iPad | macOS or Linux |
| An iOS app, quick layout and flow checks | [Simulator card](/cards/simulator/) | Mac, iPhone, iPad | macOS only |
| An iOS app, on real hardware | [Deploy to this phone](/cards/deploy-to-phone/) | iPhone | macOS only |

## A web app

Your agent starts the dev server. It listens on the host's loopback interface —
a machine you may be nowhere near.

The Browser card forwards that port over the connection you already have and
renders the page. You tap through the app for real, on the device you are
holding. When something is wrong, mark the area,
[annotate it](/board/annotate/), and it lands in the agent's prompt with the
URL, the selector and your notes.

Nothing is exposed to the internet: the forward is point-to-point inside your
existing authenticated connection.

## A web app, checked by the agent

The step before that one: the agent should not hand you a page it never looked
at. The [Agent Browser](/cards/agent-browser/) is a browser on the host that the
agent drives itself, with no extension and nothing to install. It opens its own dev
server, reads the page as text, clicks through a form, screenshots the result
and fixes what it finds, while you watch the pointer move in a card on your
board and take over whenever you want.

The same card emulates an iPhone SE or an iPad Pro when you want to see what a
layout does at that size, and because the browser lives on the host, the login
you did on your Mac is still there when you pick up your phone.

## An iOS app, in the Simulator

The host runs the Simulator; the card mirrors it live and sends your taps back.
The build the agent just made is the build on your screen: no upload, no device
provisioning, no cable.

This is the fast loop: rebuild, look, complain, repeat.

## An iOS app, on the phone itself

Some things only show up on hardware — real touch targets, real performance,
real notifications. **Deploy to this phone** builds on the host and installs the
result on the iPhone in your hand, through Apple's own install mechanism.

Slower than the Simulator, and it needs a signing setup. Worth it when the
Simulator is lying to you.

## Why it changes the prompt

All four paths end with you having seen the thing, from wherever you are. "The
submit button is under the keyboard on a small screen" is a prompt an agent can
act on; "check the layout" is not.

## Details

- The Browser card forwards with `ssh -L` on macOS and a native `direct-tcpip`
  channel on iOS. A server bound to `127.0.0.1` on the host is reachable; it
  does not need to listen on all interfaces.
- The Simulator needs the host to be logged in graphically — its broker runs in
  the GUI session because `simctl` needs a window server.
- Deploys cap the IPA at 500 MB, expire after 48 hours, and keep the last 10
  jobs. The installed app's container is preserved across redeploys.
- Neither the Simulator nor deploys exist on Linux hosts. The Browser card and
  the Agent Browser work on both — the Agent Browser needs a Chromium-family
  browser installed on the host.
- The host tracks which ports are listening for a workspace, so the browser
  cards offer them in a menu (`:3000 node · Claude`) instead of asking you to
  remember.

---

# Agent sessions

Source: https://docs.offsite.sh/work/agent-sessions/

Running the real Claude, Codex and Grok CLIs — permission modes, models, and how a card follows the CLI's own session commands.

Offsite does not implement an agent. It starts the CLI you already have
installed, in a tmux session on the host, and streams it to your devices.

That means your `~/.claude`, your `AGENTS.md`, your MCP servers, your skills,
your hooks and your subscription all apply exactly as they do in your own
terminal. Nothing is proxied and no token passes through Offsite.

## Permission mode

You pick it when starting a session, and it maps onto each CLI's native flags:

| Mode | Meaning | What it does |
|---|---|---|
| **Auto** (default) | Works in the workspace, asks only for risky actions | the CLI's own automatic approval mode: edits and commands inside the workspace run without a prompt; network access, writes outside the workspace and destructive commands still ask |
| **YOLO** | Maximum permissions for unattended work | approvals and sandbox bypassed |

Both modes are built for a session that runs while you are elsewhere: Auto keeps
the agent inside the workspace, YOLO takes the brakes off. Codex dropped its own
prompt-on-everything mode (`--ask-for-approval untrusted`) in 0.149 for the same
reason.

YOLO is what makes overnight work possible, and it is exactly as dangerous as it
sounds — the agent can run anything in that workspace without asking. Use it
where the blast radius is bounded, and prefer a host user that is not root.

**YOLO for this start** lets you take a session into YOLO once without making it
the session's permanent mode.

:::caution
Claude Code refuses to bypass permissions when running as `root`. If YOLO is
greyed out or the session refuses to start in it, check which user your host
runs as. See [A second Mac as a host](/hosts/remote-mac/).
:::

## Model and effort

A session can pin a **model** and, where the CLI supports it, an **effort**
level. Both are optional; left empty, the CLI's own default applies.

Both are re-applied when a session is restored after a reboot, so a resumed
conversation keeps the configuration it was started with.

## Naming sessions

You rarely have to. Every agent session names its own card in its first
response and keeps a one-line recap current after that, so a board full of
agents stays readable and a notification says *which* agent is waiting. Rename
a card yourself and your name is final — see
[Cards that name themselves](/work/self-naming/).

## Several agents at once

Different providers side by side is a normal way to work here: Claude for the
refactor, Codex for the tests, Grok for the odd bug. They are separate cards in
one workspace, each in its native CLI, each with its own permission mode.

## Offsite and the CLI's own session commands

A card is a window onto one native conversation, and the CLIs have their own
ways of changing which conversation that is: `/resume`, `/clear`, `/new`,
`/fork`, `/cd` in Claude Code and Codex, plus `/archive` and `/delete` in
Codex. You can use all of them. Offsite follows the change instead of fighting
it: the card keeps tracking the conversation it actually shows, so notifications,
the resume archive and a restore after a reboot all refer to the right one.

When that happens, the card gets a small chip in its chrome; tap it for the
details (origin, old and new ID).

| Chip | What happened | Anything to do? |
|---|---|---|
| **Resumed** | The conversation continues under a new native session ID — `/resume`, `/clear`, `/new`, `/fork`. | No. Everything keeps working. |
| **Other workspace** | The conversation moved to a different directory (`/cd`). The card stays on its workspace, so the Git and Files cards next to it no longer match what the agent works on. | Fine for a quick detour. For real work in the other repo, start a card on that workspace. |
| **New thread** | You archived or deleted the previous conversation in the CLI (`/archive`, `/delete`) and the card was restored afterwards. Offsite honours that and starts fresh instead of resurrecting it. | No. Offsite's own safety copy is removed on `/delete` too. |
| **Broken** | The pane shows another session's conversation, or the conversation moved into the CLI's background daemon. | The session works, but parts of Offsite's functionality may be limited. The chip offers the command that returns the pane to its own conversation. |

A few things that follow from this:

- **Restore resumes what you last saw.** After `/new` or `/cd`, a reboot
  restore brings back *that* conversation, in its own directory.
- **`/permissions` in Codex sticks.** Changing the permission profile inside
  the Codex TUI updates the card's permission mode, so the next restore
  relaunches with the profile you chose.
- **Questions reach you.** A Codex plan-mode question (`request_user_input`)
  shows up as "needs your input" with its options, like Claude's.
- **Subagents stay quiet.** A Codex subagent finishing its task is not your
  turn ending; the card waits for the root agent.
- **`codex agents` does not see Offsite sessions**, and `/agents` inside a card
  reports that the session is not connected to a shared background server.
  That is intended: the board is the session model; Codex's shared daemon would
  let sessions be opened, renamed and stopped behind the cards' back.

## Details

The exact flags Offsite passes, per tool and mode:

| Mode | Claude | Codex | Grok |
|---|---|---|---|
| Auto | `--permission-mode auto` | `--ask-for-approval on-request --sandbox workspace-write` | `--permission-mode auto` |
| YOLO | `--permission-mode bypassPermissions` | `--dangerously-bypass-approvals-and-sandbox` | `--permission-mode bypassPermissions` |

- Claude and Grok sessions are started with an explicit `--session-id` so
  Offsite can later `--resume` exactly that conversation. Codex resumes through
  its own thread discovery.
- Offsite injects a `--settings` block for Claude containing only hook commands
  that report session lifecycle events back to the host (`SessionStart`,
  `UserPromptSubmit`, `Stop`, permission-prompt `Notification`, and
  `PreToolUse` for question/plan tools). Those hooks are what make
  notifications deterministic instead of screen-scraped.
- Offsite also appends a short system-prompt block describing the Offsite
  environment, so an agent knows it may be driven from a phone and should not
  open GUI dialogs on the host's screen.
- `CLAUDE_CODE_NO_FLICKER=1` is set on Claude sessions. It keeps the CLI in its
  fullscreen renderer, which is what the card is built to display.
- Grok sessions get their own `GROK_HOME` per session.

---

# Hand off and ask

Source: https://docs.offsite.sh/work/handoff-and-ask/

Moving context between agent sessions — and why one session can never type into another.

Two sessions often need each other. One has read the whole subsystem; the other
is about to change it. Offsite has two moves for that, both on the card's
**More Actions** menu.

## Ask another session

**Ask another session** asks a question *about* another session: Offsite reads
that session's transcript and answers from it.

Use it for "what did the other agent conclude about the migration?" without
switching cards, re-reading a long scrollback, or interrupting anything. The
other session is not touched — it does not even know it was read.

## Hand off to a NEW session

**Hand off to a NEW session** ends the handover the other way round: it starts a
**fresh** session that pulls the current session's context and continues from
there.

Use it when a conversation has grown long, or when the next phase of work
deserves a clean slate that still knows what happened. You can add a note
describing what the new session should focus on.

## Why handoffs go to a *new* session

Offsite deliberately cannot deliver a message into an existing session.

That capability existed and was removed in August 2026, for a concrete reason:
delivering text into a running agent means typing into its terminal, and a
terminal is a shared channel. A delivery arriving while the user had a
half-written prompt in the same input **merged with that draft and was submitted
as one prompt, with the user's authority.** No amount of care at the sending end
fixes that; the channel itself is the problem.

So the rule is now structural: **a session may read another session, never write
into one.** Handoffs create a new session that pulls context, which has no
shared input to collide with.

## For agents

An agent running inside an Offsite session can do the read side itself:

```bash
offsite agents list       # the user's other agent sessions, with activity
offsite agents context    # another session's transcript, normalized
```

There is no `send`. See [Offsite for agents](/agents/for-agents/).

## Details

- `agents list` reports each visible agent session with an activity of `busy`,
  `attention` or `idle`, derived from the same turn state that drives
  notifications.
- Session selectors resolve by id, id prefix, then name; running sessions are
  matched before stopped ones so a dead session cannot shadow a live one.
- Transcript reads are capped (4 MB tail, blocks trimmed to 2000 characters,
  tool output to 300) so a huge conversation cannot blow up the caller's
  context.
- Reads act as the *calling session's agent*, identified by `OFFSITE_SESSION_ID`
  — never as one of your paired devices. That keeps a read from being mistaken
  for you looking at a card, which matters for
  [attention handling](/mobile/notifications/).

---

# The Icebox

Source: https://docs.offsite.sh/work/icebox/

Parking an agent session off the board without ending it — and getting it back where it was.

Eleven cards on one board is a board you stop reading. The **Icebox** parks the
agent sessions you are not working with right now and keeps their
conversations.

## What it does

**Move to Icebox** on a card takes it off the board. The session keeps running
on the host — this is parking, not stopping.

**Move to Board** brings it back, and it returns to the position it had before,
not to the end of the queue. Offsite remembers each iceboxed card's previous
board slot.

The Icebox itself lives in the sidebar and lists everything parked in the
current workspace.

## When to use it

- A long unattended run you do not want to watch — park it, let notifications
  tell you when it needs you.
- A session you will come back to tomorrow.
- Reclaiming board space without the decision of "do I still need this?".

If you *are* done with a session, end it instead. The Icebox is not a graveyard;
a parked agent still holds its context, its resume state and, if it is mid-turn,
its work.

## What can be parked

Agent sessions that are on the board and belong to you: Claude, Codex and Grok
cards, with their conversation. Bring a card back from the tab bar first, and
the Icebox takes it.

## Details

- Iceboxing is a placement change, not a lifecycle change: the record's
  `placement` becomes `icebox` and the previous board geometry is stored as
  `icebox_previous_board_item`.
- The host enforces the agent-only rule
  (`workspace_card_capabilities(...).can_icebox`), so the same restriction holds
  on every client and over the CLI.
- CLI equivalent on the host:
  `offsite-host sessions icebox --session-id <id> --iceboxed/--no-iceboxed`.
- Restoring a card whose old slot is now occupied places it on the suggested
  board edge instead of overlapping.
- **Move to Icebox** lives on the card menu of a board card, on both
  platforms.

---

# Cards that name themselves

Source: https://docs.offsite.sh/work/self-naming/

Every agent session names its own card and keeps a one-line recap current, so the board stays readable and a notification tells you which agent wants you.

Five agent cards all labelled "Claude" are five cards you have to open to tell
apart. A board only saves you time if you can read it at a glance.

So Offsite asks the agent to do the labelling. Every agent session starts with a
short briefing from Offsite, and the agent uses it to **name its own card** in
its first response and to keep a **one-line recap** current at the end of every
turn.

[Figure: Left: three cards all carrying their tool's default name, indistinguishable. Right: the same cards after the agents named themselves, each with a short name and a one-line recap of what it is doing.]

## Your name always wins

Rename a card yourself and that name is final: Offsite marks it as yours, and
from then on the agent's own rename command is refused — it is told to keep your
name and not to rename.

Only *your* rename locks the name. The label a session is born with ("Claude",
"Codex", or whatever you typed when starting it) does not, which is why the
agent can replace it in its first response.

## Where the recap shows up

The recap answers "what was this one about again?" — the question you have after
lunch, after a flight, or after looking at another card for an hour.

- **Small cards** show it under the name. Shrink a card, or look at the board
  overview on iPhone, and the card still says what it is doing.
- **A card that needs you wins over the recap.** If the session is waiting for a
  decision, the line reads *Needs attention* instead — the more urgent fact.
- **Full-size cards** keep it one tap away: an **ⓘ pill** sits in the card's
  bottom-right corner, next to the turn spinner, whenever the session has a
  recap. Click it on the Mac for a small popover; tap it on the iPhone for a
  bottom sheet you swipe away. Nothing pops up on its own.

## Why notifications get better

A notification carries the session's name. With default names, "waiting for
input" tells you that *something* wants you. With self-named sessions,
"api-refactor is waiting for input" tells you whether it is worth unlocking your
phone.

The name is short for the same reason: it has to fit a push notification title
on a Watch. See [Notifications](/mobile/notifications/).

:::note
When a push goes out, that name goes with it — readable text, through Firebase
and Apple, onto a lock screen. It is the one piece of work-context that leaves
your machine, and a self-chosen name like "auth-migration" says more than
"Claude" ever did. If a project name is sensitive, rename the card yourself or
turn notifications off for that device; the recap stays on your machine. Full
detail: [Security and privacy](/reference/security/).
:::

## Details

- The briefing reaches each CLI through its own supported channel: Claude via
  `--append-system-prompt`, Codex via `developer_instructions`, Grok via
  `--rules`. Nothing is patched into your global config.
- The agent writes both through the `offsite` CLI:
  `offsite session name '<name>'` and `offsite session recap '<line>'`. See
  [Offsite for agents](/agents/for-agents/).
- Names and recaps are asked for in the language *you* write in, not the
  agent's default.
- Limits: a name is guided at 3 words / ~15 characters and hard-capped at 30;
  a recap is guided at under 30 words and hard-capped at 200. Both are
  collapsed to a single line of printable characters.
- Each session record carries a `name_source` stamp: `auto` at creation,
  `agent` after the agent names it, `user` after you rename it. Only `user`
  blocks further agent renames.
- The recap is stored with a timestamp, and the popup shows its age ("3h ago")
  so an old recap never reads as the current state.
- Mac cards switch to the compact presentation below roughly 300 × 160 points;
  on the iPhone board overview every card uses it.
- Cards without an agent — Terminal, Git, Files, Browser, Simulator — carry the
  name you give them.

---

# Sessions and why they survive

Source: https://docs.offsite.sh/work/sessions/

What a session actually is on the host, what kills it, and what does not.

A **session** is one long-running program on a host, shown to you as a card. It
can be an agent CLI, a plain shell, a browser target or a mirrored Simulator.

The important part is where it lives. A session belongs to the **host**, not to
the app you are looking at it with. Offsite starts it inside tmux on the host
machine and then streams that terminal to every device you have connected.

[Figure: A session runs in host-owned tmux. The Mac app, the iPhone app and the Watch attach to the same session; closing any of them leaves the session running.]

## What does not stop a session

- Closing the app, on any device
- Losing Wi-Fi, switching networks, going through a tunnel
- Putting your **client** to sleep
- Putting the **host** to sleep (it continues on wake — see
  [Keep the host awake](/hosts/keep-awake/) if you would rather it did not sleep)
- Updating the host components

## What does stop one

- Ending it yourself (**End Session**)
- The program exiting on its own
- The host machine powering off — and even then, see below

## After a host reboot

Offsite recreates the tmux session and then resumes the *conversation* using
each CLI's own mechanism: `claude --resume`, `codex resume`, wired in per tool.
You come back to the agent's history, not to a fresh prompt.

To make that reliable, Offsite keeps its own archive copy of the resume
artefacts, so a transcript cleanup on the CLI's side cannot orphan your session.

## Session states

The card and the sidebar show what a session is doing:

| State | Meaning |
|---|---|
| Working | a turn is running |
| Needs input | the agent is waiting for you |
| Needs attention | something wants a decision — a permission prompt, a question |
| Ready | idle at the prompt |

These drive [notifications](/mobile/notifications/) too.

## Details

- Each Offsite session runs on its **own tmux socket** (`tmux -L
  offsite-<tool>-<session-id>`) with Offsite's own config file. Offsite never
  writes `~/.tmux.conf`, never requires tmux plugins, and never changes your
  global tmux setup — a hard rule, not a default.
- Session records live in `~/.offsite/sessions/` and `~/.offsite/state.db`;
  resume artefacts are archived to `~/.offsite/session-archives`.
- Sessions receive `OFFSITE_SESSION_ID`, `OFFSITE_WORKSPACE_ID`, `OFFSITE_TOOL`
  and `OFFSITE_SESSION_KIND` in their environment.
- Agent CLIs run in their fullscreen (alternate-screen) mode, which is why the
  card has no scrollback to search — the CLI owns the viewport and manages its
  own history.
- Scrollback limit for shell sessions is set on Offsite's own tmux config, not
  on yours.

---

# Workspaces

Source: https://docs.offsite.sh/work/workspaces/

One folder, one board, its own sessions — and why a workspace does not need to be a git repository.

A **workspace** is one folder on a host, with its own board, its own cards and
its own sessions. Switching workspaces switches all of that at once.

It is a focus container, not a project format. Offsite writes nothing into your
folder — no dotfile, no manifest, no lock. A workspace is just a path Offsite
remembers.

## Adding a workspace

Press **+** next to *Workspaces* in the sidebar (on iPhone: the workspace menu
at the top, then **New Workspace**). Instead of a dialog you get a small
stepper in the middle of the window with three doors:

| Door | What it does |
|---|---|
| **File System** | Browse the host's folders, create one if you like, and pick the workspace root. |
| **Existing Projects** | Folders where Claude, Codex or Grok already ran on this host, plus git repositories under your home directory. Filter by name or path, or by the tool that found them. One tap adds the folder. |
| **Remote Repository** | Clone a repository *onto the host*. Pick one of your GitHub repositories, or paste any Git URL (`https://`, `ssh://`, `git@host:owner/repo`, or the GitHub shorthand `owner/repo`). |

The remote door is the one that matters for a host you have never touched: a
fresh Linux box, a Mac in the other room, a VPS. Nothing has to be on it yet.

- **GitHub sign-in happens in the panel.** If `gh` (GitHub CLI) is installed on
  the host but not signed in, **Connect GitHub** shows a one-time code and the
  `github.com/login/device` link. Enter the code on whatever device you are
  holding; the token is stored by `gh` on the host, never by Offsite. If git on
  you also want git itself on that login, a **Set up** button runs
  `gh auth setup-git` for you — that is what private repositories over https
  use.
- **You choose where the clone goes.** After picking a repository you get the
  same folder browser as the File System door, with the repository name
  prefilled as the folder. The browser starts where your last clone went.
- **The clone runs on the host**, with git's own progress shown in the panel.
  Close the app mid-clone and the job finishes anyway; the next time you open
  the stepper it shows the running clone and picks it up. When git is done the
  folder becomes a workspace and is selected.
- Without `gh` on the host only the URL path is available; private repositories
  then need an SSH key on the host.

Leaving the stepper is a click on any workspace in the sidebar (or Esc).

## It does not need to be a git repository

This surprises people, because *Existing Projects* is full of repositories.

- The **Existing Projects** list is built from where your agents already ran
  and from a scan of your home directory for folders that contain a `.git`
  directory. That is a convenience, nothing more.
- **File System** accepts any directory that exists.
- If the folder you pick sits *inside* a git repository, Offsite snaps the
  workspace to the **repository root**, because that is almost always what you
  meant and it makes the Git card useful.
- If it is not in a repository, the folder itself becomes the workspace root.
  Everything works except the Git card, which has nothing to show.

So: notes folders, scratch directories, a server's `/srv/app`, a monorepo
subfolder — all valid.

## What a workspace holds

| | |
|---|---|
| Board | the grid of cards, their positions and sizes |
| Tabs | cards parked in the tab bar |
| Icebox | agent sessions parked off the board |
| Sessions | every agent and terminal started in this folder |
| Actions | saved commands for this workspace |

Sessions inherit the workspace folder as their working directory, so an agent
starts where you would have started it.

## Several workspaces at once

Add as many as you like per host. They are independent: an agent in one
workspace knows nothing about another, and cycling between them (`⌃⌘↑` / `⌃⌘↓`
on macOS) is instant because sessions stay alive in the background.

Right-click a workspace in the sidebar (long-press on iPhone) to **rename** it,
**hide it from the sidebar**, or **delete** it; hovering a sidebar row on macOS
also shows a trash icon. Hidden workspaces come back through *Existing
Projects*. Deleting a workspace removes Offsite's record of it and its board —
your folder on disk is untouched.

## Details

- Resolution is literally `git_root_for_path(directory) or directory.resolve()`.
- The workspace **id is its absolute root path**, so moving a folder creates a
  new workspace rather than renaming the old one.
- Workspace records live in `~/.offsite/workspaces.json` on the host; the
  discovery cache is `~/.offsite/workspace-discovery.json`.
- Clones are host jobs under `~/.offsite/git-remote/clones/<job>/` (status,
  git's log); `~/.offsite/git-remote/prefs.json` remembers the last clone
  parent. The host CLI mirrors it all: `offsite-host git-remote status|repos|
  auth-start|clone|clone-status|clone-list|repair --json`.
- The remote door needs host protocol 26 or newer; on older hosts the tile says
  "Needs a host update".
- Each workspace gets a stable colour derived from a hash of its path — the same
  folder is always the same colour on every device.
- A workspace named `.offsite` is refused; the state directory is never a
  workspace.
- Board geometry is quantized to a 24-column grid on the host, so the same board
  lays out identically on a Studio Display and a phone.

---

# Worktrees

Source: https://docs.offsite.sh/work/worktrees/

One branch, one folder, one agent per task — worktrees let several agents work on the same repository at the same time.

A worktree is a second checkout of your repository: its own branch, its own folder under
`~/.offsite-worktrees`, its own agent. Your repository stays untouched while the agent
works, and you can run three worktrees on three tasks side by side.

Two words come up everywhere: the **base** is the branch a worktree starts from
(`origin/main` by default), the **repository** is your own checkout, the workspace the
worktree was created from.

Every repository workspace gets a **Worktrees** column right of the board. Click a card to
open the worktree as a board over the repository; click it again, the repository or any
other card to get back.

## Create a worktree

Press **+** in the Worktrees column.

- **Task** — explain what you want to fix or build. It becomes the agent's first prompt.
  Without a task the agent waits for your first message.
- **Name** — derived from the task, editable. The branch is `offsite/<name>`.
- **Base** — the branch the worktree starts from, fetched first. Default: `origin/HEAD`.
- **Agent** — Claude, Codex or Grok, with model and effort if you want them. **YOLO** lets
  the agent run without permission prompts.

The agent starts with a preamble that says where it is and what it may do: work only in
its worktree, never touch your repository, never commit, push or merge unless the task
says so. You review and commit through the Git card, and you finish from Offsite.

## Repository Worktree Setup

A worktree starts as a plain checkout. Everything git ignores is missing: `node_modules`,
`.env`, build caches. Set up once what every worktree of this repository gets, in three
stages: **Prepare** (copy and install before the agent starts), **Run** (what starts the
app or tool of a worktree) and **Clean up** (free what a worktree created before it is
deleted). The first
time you press **+** in a repository without a setup, Offsite asks whether to set it up
now; **Not now** keeps worktrees as plain checkouts, and the dialog keeps offering
**Set it up now…** until you do. Later, **Edit setup…** in the dialog or
**Repository setup…** in a worktree card's menu opens the same editor.

The setup lives in two places. The **host** keeps a copy per repository: that is what
runs, on every device connected to this host, and it works before anything is committed.
The **repository file** `.offsite/worktree.json` is the shared copy: write it from the
editor so teammates and a new machine start with the same setup. When both exist and
differ, the host's copy runs and the editor shows **Compare…** to take either side.

### Host Settings › Worktrees

Every repository's host copy at one place: **Host Settings › Worktrees** lists the
repositories with a setup, a branch prefix or a "Not now", with what each one copies and
runs, how many worktrees it has and how much disk they take. **Edit…** opens the same
editor, **Forget** drops the host copy, the prefix and the "Not now" answer. The card at
the top shows the worktrees folder and its size; **Leftovers** lists folders in it that
no workspace uses any more, each with **Remove…**.

### Copy from repository

Paths git ignores that a fresh worktree needs. Each one is copied from your repository
into the new worktree (a reflink clone on APFS, so it takes no time and no space).
Click the tag on a row to switch between **copy** and **link**: a link points at the
repository's file, the right choice for `.env` and other secrets you never want
duplicated.

### Setup commands

Commands that run in order in a visible **Setup** card before the agent starts, for
example `npm ci`. The card shows every step; if one fails, press **Enter** in the card to
run the setup again. The agent starts only after the setup succeeded, and Offsite
notifies you when a long setup finishes while you work elsewhere.

### Run

The steps that start what you work on in a worktree, in order; the last one keeps
running: `nvm use 22` then `npm run dev -- --port $OFFSITE_PORT_BASE`, a mobile app
(`flutter run`, a build plus `xcrun simctl launch`), a CLI or TUI (`cargo run`), a watcher
(`npm test -- --watch`). **Run** in the worktree header runs them on a **Run** card on the
worktree's board, in your login shell with the worktree's environment, so shell functions
like `nvm` work; a server takes its port from the worktree's own window, so three
worktrees serve side by side. **Stop** ends it, Enter in the card starts it again after
it exits. The column card says **Running** while it goes. The worktree's agent uses the
same card: when it wants to try its work it starts the app through its `worktree_run`
tool, on the worktree's port, visible to you, and stops it when done.

### Clean up

Commands that run before a worktree is deleted: drop the database it created, stop its
container, remove its build output or emulator snapshot. **Delete worktree** ends the Run
card, runs the steps in the worktree with the same environment, then removes the folder.
A step that fails keeps the worktree; the sheet shows the step, its exit code and the last
lines of its output, and offers **Delete anyway**.

### Set it up with an agent

Not sure what the project needs? Press **Set it up with an agent…** in the editor, pick
the agent, model and effort, and press **Start**. The agent gets a scratch worktree of the
repository, works out how the project installs, runs the setup there and proposes all three stages:
the paths and commands appear in the form under the terminal as it declares them. Ask
for changes in the terminal, edit the lists yourself, then **Save**. The scratch worktree
is removed, the setup is saved on this host, and the next page offers to write it to the
repository. The agent has one job: it answers anything else with a pointer to the
setup and never touches your repository.

### Write to repository

**Write to repository…** shows what goes into `.offsite/worktree.json` and marks lines
that probably work only on this machine: absolute paths, home paths, version-manager
commands like `nvm use`, `sudo`. Keep those on the host or change them, then write. The
file lands uncommitted in your repository; the Git card shows it, commit it with your
next change.

### For agents

The agent in a worktree has its own tools for all of this: it can read where the
worktree stands, update from the base, publish, open a pull request, merge when you
asked for it, and declare the setup it worked out. Say "publish and open a pull request"
or "finish this" in the task or the chat and it uses those tools instead of raw git
commands. Deleting a worktree stays with you.

### Branch prefix

Agent branches carry a prefix, `offsite` by default, so they stay recognizable on the
remote and apart from yours. Change it in the setup; it is remembered per repository.

Setup commands and the agent get these variables: `OFFSITE_WORKTREE_PATH`,
`OFFSITE_WORKTREE_BRANCH`, `OFFSITE_SOURCE_CHECKOUT` and a private port window
`OFFSITE_PORT_BASE` … `OFFSITE_PORT_BASE_END`, so parallel dev servers never collide.

## Work in a worktree

The overlay board has its own **+**: add terminals, browsers, a simulator, Git and Files
cards; they land on the worktree's board. Notifications from a worktree's agent open the
worktree directly. The column card shows the agent's state, the branch's state and what
happens next: **Working**, **Needs you**, **Setup done**, **Ready to clean up**.

## Finish a worktree

**Finish worktree** opens the checklist: uncommitted changes, commits ahead of the base,
whether the base moved, conflicts, the pull request and its checks. Every row that has a
remedy carries it, and one button does the finishing:

- **Pull request** — publishes the branch, opens the request on GitHub and merges it from
  Offsite once checks pass (squash, merge commit or rebase, as the repository allows).
- **Merge directly** — fast-forwards the base branch to the worktree and pushes, when
  nothing diverged and your repository is clean.

If the base moved, **Update from base** merges it into the worktree. Conflicts go to the
worktree's agent with one click: it resolves them in place and commits the merge. A
running agent is a warning to confirm, never a block. When the work is in the base, the
checklist says **Merged** and offers **Delete worktree**.

## Delete a worktree

**Delete worktree** in the overlay header or the card's menu shows what would go:
uncommitted changes, unpushed commits, whether the branch's work is in the base, running
sessions. The folder and the workspace are removed. The local branch is deleted when its
work is proven to be in the base (a squash merge counts). **Also delete it on origin**
removes the remote copy in the same step; it is pre-ticked only when the work is in the
base and never touches a branch with commits the base lacks.

---