All pages

Docs · AI features

Cloud workspace

Availability: cloud workspace. Reachable from a browser at trmnly.dev, from the Mac app's Settings, and from any MCP client — see Platforms.

Your account gets one Linux sandbox: a real box with a shell, your checkouts, a browser, and the same shape of agent tool surface the Mac app exposes. It is where work happens when the Mac is asleep, when you are on a phone, or when an agent should run somewhere that is not your machine.

Connecting an MCP client to it is covered in MCP server, and how the cloud sits beside the other hosts in Platforms. This page is the workspace itself.

Starting, stopping, and what it costs

The box starts on the first call that needs it — opening the terminal page, or an MCP client's first box tool — and takes about a minute from cold. Using it keeps it alive: every call counts as a heartbeat, minutes accrue, and the box's deadline is pushed out. After the last call it stops itself within about 10 minutes. Something left running in a pane with no tab open and no client calling gets those same 10 minutes; to run unattended for longer, make it a scheduled job, which keeps the box up for its own run and is billed for exactly that span.

Minutes bill against Cred credits, one credit a minute, and the credit balance is the ceiling: a start is refused when the balance is empty. There are two ways to fill it, and they mix. Pro is $50 a month for 7,500 credits (125 hours), granted each time the month renews; manage or cancel it from Credits → Manage plan on the dashboard. Credit packs — $5 for 600 credits (10 hours), $20 for 2,700 (45 hours), $50 for 7,500 (125 hours) — are one-off and need no plan. Credits from either never expire, and a new account starts with 100 (about an hour and a half). Charges round down: a session of 41 minutes 50 seconds costs 41 credits. See trmnly.dev/pricing.

A tab left open in the background keeps a running box alive; it does not provision one. A workspace that was stopped from another device, or by an empty balance, stays stopped until you start it deliberately — a heartbeat is not a place to spend money.

The same goes for everything that reads in the background. The web panes' polls (files, prompts, queue, tasks, chat, the terminal), autosave, and the iPhone app's terminal poll, pane list and tool list all ask not to wake the box: against a stopped box they get "The workspace is not running." instead of starting it. Stopping the workspace from the web used to restart it through autosave; it no longer does.

The window

Shells run down the left, one row each. A row carries the pane's title, a status dot, a progress bar, and any flags the pane has raised; clicking a flag lowers it, the same as typing into a flagged pane on the Mac. The bell in the rail collects box events — a notification an agent posted, a monitor rule firing, a job ending, an approval waiting — and raises a desktop notification for anything that lands while the tab is in the background.

The panel on the right holds the tabs, in four groups:

Group Tab What it is
Code Files The box's file tree, with preview, inline edit, upload and download
Projects Git repositories in the workspace, and worktrees of them
Git Working-tree changes, history, branches, and pull requests
Search Grep across the workspace
Ports The box's preview ports, each with a public URL when something is listening on it
Web Chromium running on the box, rendered as screenshots
Run Prompts Saved prompts, stored on the box — see Prompts
Queue Commands staged to run in order, optionally at a time
Background Commands the box runs with no pane, read back as a digest
Jobs Scheduled jobs, which run whether or not a tab is open
Flows Runbooks, monitor rules, and layouts
SSH Saved hosts, reached over the box's own network
Agents Agent Claude Code, in the box, in a conversation
Plans Ordered prose steps with a cursor, plus the fleet working the board
Tasks The board — see Kanban
Chat The box's message room — see Chat
Notes Markdown scratchpad — see Notes
Remote Browse a remote SSH host over SFTP and copy files between it and the workspace
Box Keys Credentials injected into the box — see Access keys — and the Agents card that signs Claude Code and Codex in
Activity Processes on the box by CPU and memory, with load and free memory; a row can be ended
Help These pages, in the workspace

The preview ports are fixed when the box is created — 3000, 5173, 8080 and 8000 — which is why that tab is a list rather than a field: start a dev server on one and it is reachable from any browser. Web is not an iframe — the page loads in a browser on the box's own network, so it can reach a localhost dev server your laptop cannot.

Getting work in and out

  • Clone a repository. The project rail's repo picker (or Clone a repo… in the command palette) lists the GitHub repositories the TRMNLY GitHub App is installed on and clones one into ~/workspace, adding it to the rail. The credential reaches git through a credential helper, never the remote URL, so a later push or a copy of the repo does not carry it. An MCP client does the same with project_list_github and project_link_github, which also takes a pasted github.com URL or owner/repo.
  • Files. The Files tab uploads a file into the box (up to 25 MB) and downloads one (up to 10 MB); past that, use git. Remote copies between the box and an SSH host.
  • Saving. The workspace is saved for you — see Saving a workspace — so the next box starts where this one stopped.

Git

The Git tab is the working tree without a shell. Changed files list staged and unstaged separately, each expanding to its own diff. Stage / Unstage move a file, Discard throws its changes away behind a confirm, Commit all stages everything first and Commit staged commits exactly what is staged. Push sets an upstream when the branch has none and never forces; Pull fast-forwards and refuses a pull that would need a merge. There is a stash with an optional message, a history list, and a branch list that switches or creates.

Pull requests live in the same tab: list them by state, read one with its files, diff, and comments, add a comment, and merge it.

To leave notes on diff lines rather than post them to GitHub, the diff_comment_* tools work here exactly as they do on the Mac — see Review.

Moving a session from your Mac

A terminal pane on the Mac can hand its work to the cloud workspace: the + menu under the pane → Move to Cloud…. The sheet lists what will happen before anything does:

  1. The pane's repository — committed, uncommitted and untracked work — is pushed to a new branch trmnly/handoff/<id> on its GitHub origin, using your own git credentials. Your branch, index and files are not touched.
  2. The box clones that branch into ~/workspace/<repo>-<id>, unwinds the snapshot commit so the changes read as uncommitted again, and switches to a branch with the same name as the one on the Mac.
  3. If Claude Code is running in the pane, it is stopped on the Mac, its transcript is copied into the box's ~/.claude/projects/, and claude --resume starts in a pane named claude (from Mac) — the same conversation, with its history. A pane without Claude Code gets a shell.

Then Open in Browser takes you to trmnly.dev/trmnly, and the Mac can sleep. Requirements: the Mac is paired (Settings → AI Agent → Remote Control), the repo's origin is on GitHub, and Claude Code is connected in the workspace's Agents card.

What gets pushed. The snapshot is your tracked changes plus the untracked files the sheet lists — nothing else. Untracked files that look like secrets (.env files other than templates, *.pem, *.key, *.p12, SSH keys such as id_rsa, credentials*, .netrc, .npmrc, secrets.*, service-account* and the like) are listed separately and left out, even if they were already staged. When GitHub reports the repository as public, the sheet warns you before you move.

The branch is temporary. Once the box has cloned it, the handoff branch is deleted from GitHub — also when the clone fails or you cancel. If deleting it fails, the done screen shows the command to run yourself.

Safety checks.

  • When you press Move, the plan is worked out again. If anything changed since the sheet opened — the branch, uncommitted work, new files, whether Claude is running — the sheet shows the new plan and why, and waits.
  • If Claude Code doesn't exit within ten seconds, the handoff stops before anything is copied, so two sessions never share one transcript.
  • Cancel works through the long steps (push, clone, upload) until Claude is being stopped; after that it's disabled. Git never stops to prompt for a password — it fails instead.
  • If a step fails after Claude was stopped on the Mac, claude --resume <id> is typed back into the pane so nothing is lost — unless the cloud pane may already have started, in which case the sheet tells you to check the cloud first.

Agent

The Agent tab runs Claude Code in the box and streams the turn into a transcript. It runs on the Claude credential from the Keys tab's Agents card — the same one scheduled jobs use. (Codex runs in a pane: type codex in a shell, or have an MCP client call agent_start — see Driving the box from outside.) It has three modes:

  • Plan — read-only. The agent proposes a plan and changes nothing.
  • Ask — the agent runs, and asks here before any tool call your rules don't already allow.
  • Auto — the agent runs commands and edits files unattended.

In Ask mode a call the rules don't settle is parked as a card in the transcript with Allow, Always allow, and Deny. Always allow writes a rule, so the next call like it goes through without asking. Rules belong to the workspace, not to one conversation, and the pane's Rules panel is where you read and edit them.

A rule for a command covers that plain command and nothing else. Anything chained, piped, redirected, or wrapped in a substitution is asked about every time, because a prefix rule that allowed git status must not also allow git status; curl … | sh. At most 20 calls wait at once — past that a request is declined immediately with a reason the model can act on, rather than growing a column of cards nobody reads — and a card unanswered for four minutes times out.

Ask and Plan modes ignore the repository's own .claude/settings.json and .mcp.json: Claude Code is launched with --setting-sources user --strict-mcp-config, so a repository you cloned cannot pre-approve its own tools, add hooks that run on their own, or define a server named trmnly that shadows the one the approval gate lives on. Plan gets the same treatment because a repository's hooks and MCP servers run programs whatever the permission mode. Your own user settings still apply. Auto runs everything unattended, so a repository's settings add nothing to it.

The cards can also be answered from outside the tab: approval_list and approval_resolve are box tools, events_tail reports a request as it arrives, and agent_rules_get / agent_rules_set read and change the rules.

A folder field sets the directory the turn runs in (a pasted ~/workspace/ prefix is fine). Stop ends the turn and leaves a neutral Stopped. note; a turn that hears nothing from the box for five and a half minutes stops with Lost touch with the box, and your next message resumes the conversation.

The composer takes images and files — pasted, dropped, or picked, up to six per message. History lists past conversations to reopen and resume. A message typed while a turn is running is queued rather than dropped; that queue belongs to the box, so a prompt queued from another tab, or by the agent itself, runs in the same order.

The iPhone app's Cloud agent screen is the same agent: Plan, Ask and Auto modes, Ask's Allow / Always / Deny cards, a model picker, the folder field, and photo attachments (up to six, 8 MB). Leaving the screen doesn't end the turn. See Remote control.

The agent in the box can call the box's own tools — the board, notes, panes, the browser — so it can work the way the sidebar agent does on the Mac.

Beside the model sits a usage pill showing how much of the allowance is left, for whichever window runs out first. A reading it could not take shows usage unknown, with the reason on hover, rather than implying a full allowance.

Tasks

The Tasks tab is the box's own board, with the same #N refs — see Kanban. A workspace can hold several named boards; the tools take a board, kanban_boards lists and switches them, and a call that names none acts on the selected one. The main board is called Main. A card an agent has claimed reads held by <holder>, followed by · until 14:05 while the lease runs or · lease lapsed once it has expired and the card is anyone's again. A holder that is a chat conversation renders as chat- plus the first eight characters of its id, with the full id on hover. Free drops the claim and puts the card back in To do. Claims explains the lease.

Scheduled jobs

The Jobs tab, or the job_* tools over MCP, schedules work that runs whether or not anything of yours is open. A job is either a headless Claude Code run against a prompt (kind: agent, with a landing mode — open a pull request, push, or just report) or a shell command whose output is the report (kind: command). It runs on a cron or once, in UTC unless it names an IANA zone, under a time cap of 5 to 40 minutes, and can email you when it finishes. A dispatcher ticks every 15 minutes, so a job starts at the first tick at or after its minute. The run starts the box if it has to, is billed for the time it actually ran, and stops the box afterwards when nobody is attached. Scheduled runs has the schedule grammar and options.

Flows

Flows is three things behind one segmented control, all of them the same tools the agent uses:

  • Runbooks — saved, named command sequences. Run chains the steps with && into the focused shell, stopping at the first failure. Run & record has the box run them instead, one step at a time in a pane of its own, with each step's exit status written down and the run followed live.
  • Rules — monitor rules: when a pane prints a line matching a pattern, notify me, flag the pane, type text into it, or run in a new pane. Typing is for answering a prompt that would otherwise stall a script; flagging is for a build that failed.
  • Layouts — a named set of panes, each with its directory and command, applied in one click.

A rule made in this pane is one the agent can list and change, and the events bell opens this pane on Rules when a monitor rule is what fired.

Keyboard

Does macOS Elsewhere
Command palette ⌘K Ctrl+Shift+P or Ctrl+Shift+K
Show or hide the right panel ⌘B Ctrl+Shift+B
Help ⌘/ Ctrl+Shift+/
Split the focused shell **⌘** *Ctrl+Shift+*
Close the focused split ⌘⇧X Ctrl+Shift+X
New shell ⌘⇧↩ Ctrl+Shift+Enter
Next / previous split ⌘⇧→ / ⌘⇧← Ctrl+Shift+→ / Ctrl+Shift+←
Next / previous shell ⌘⇧↓ / ⌘⇧↑ Ctrl+Shift+↓ / Ctrl+Shift+↑
Find in the focused shell's scrollback ⌘⇧F Ctrl+Shift+F
Text size up / down / reset ⌘⇧= / ⌘⇧− / ⌘⇧0 Ctrl+Shift+= / Ctrl+Shift+− / Ctrl+Shift+0

Off macOS every chord takes Shift, so plain Ctrl+K, Ctrl+B, Ctrl+\ and Ctrl+/ still reach the program in the pane — Ctrl is the terminal's own modifier there.

Tools on the box

313 tools run in the box, alongside 16 control-plane tools at the edge that a sandbox cannot provide for itself. Beyond the obvious — files, grep, bash, git and pull requests, the browser (88 browser_* tools), panes — these are the families worth planning around:

Family Tools
Agents in panes agent_start, agent_read, agent_send
Approvals approval_list, approval_resolve, agent_rules_get, agent_rules_set
Wait for output watch_terminal, wait_for_panes_idle, spawn_and_read, events_tail
Background work run_background_job, list_background_jobs, job_output_digest
Command history command_stats, command_provenance, get_command_errors
Editing apply_patch, edit_file, ast_rename, run_tests, lsp_*, dry_run_*
Undo list_write_snapshots, revert_write_snapshot
Coordination kanban_*, plan_*, fleet_*, chat_*, notes_*, memory_*
Web web_search, web_fetch, image_generate (paid in credits)
Page assertions browser_dom, browser_a11y_tree, browser_console, browser_cookies_get, browser_list_tabs, browser_emulate, browser_mock_route
Replay session_record / session_replay for panes, browser_action_run for recorded browser macros
Finding a tool get_context for the state of the box in one call, help_search for a tool by what it does

Prefer a wait-for-output tool to polling: spawn_and_read runs a command in a new pane and returns when it settles, and wait_for_panes_idle blocks until a set of panes goes quiet. job_output_digest summarises a long job's output instead of handing back the whole log.

The undo pair covers the agent's own file writes, not yours: every write a tool makes keeps a copy, and revert_write_snapshot puts the previous contents back.

Keys work without their values entering a conversation: access_key_list names what the vault holds, and every shell already has each one in its environment under that name.

The control plane

Tools What they do
workspace_status, workspace_start, workspace_stop, workspace_quota Whether the box is up and its agent answering; start, stop, and time left
job_list, job_create, job_update, job_delete Scheduled jobs
key_list, key_set, key_delete The access-key vault: names and set/delete, never a value back
agent_credential_status, agent_credential_set Whether Claude Code, Codex and GitHub are signed in on the box, and signing them in
project_list_github, project_link_github Repositories to clone, and cloning one
feedback_submit A bug report or feature request to the TRMNLY team

These run without the box, so they answer — and workspace_status is honest — while it is stopped. Every box tool needs it running; the first one called against a stopped box starts it.

Driving the box from outside

The box is an MCP server at https://trmnly.dev/mcp, signed in through the browser the first time a client connects — MCP server has the claude mcp add / codex mcp add lines and how the sign-in works. The web pages use the same tools through the same proxy, so anything a tab does, a client can do.

The usual reason to connect is to have Claude Code or Codex do the work in the box: agent_start with agent: "claude" or "codex" and a prompt opens a pane running it and returns the screen once it settles; agent_read checks on it (and can wait for it to finish); agent_send replies or follows up. If the agent isn't signed in there, agent_start says so: connect it in the Keys tab's Agents card. list_panes shows agents already running, and panes an outside agent opened are marked in the shell list so you can take one over. For a one-shot answer instead, spawn_and_read with claude -p "…" or codex exec "…".

Saving a workspace

A box's disk does not outlive it, so the workspace is saved to your account and restored into the next box: ~/workspace, plus the small dotfiles that make a fresh box feel like yours (.gitconfig, shell profiles, .claude settings). An open tab saves every three minutes and when you leave the page, skipping the upload when nothing changed; the palette's Save the workspace saves now. Autosave never wakes a stopped box. The archive is encrypted with a per-account key before it is stored.

A save is capped at 50 MB compressed. The snapshot deliberately skips the stores that exist to be thrown away — the agent's undo copies, files attached to a chat turn, and job logs — along with node_modules, build output, and live credentials. Without those exclusions a box that had done a day's work would blow the cap and save nothing.

.git is kept: losing history would cost more than the bytes.