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 withproject_list_githubandproject_link_github, which also takes a pasted github.com URL orowner/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:
- The pane's repository — committed, uncommitted and untracked work — is
pushed to a new branch
trmnly/handoff/<id>on its GitHuborigin, using your own git credentials. Your branch, index and files are not touched. - 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. - If Claude Code is running in the pane, it is stopped on the Mac, its
transcript is copied into the box's
~/.claude/projects/, andclaude --resumestarts 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.