Workspaces

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.