All pages

Developers

Build on TRMNLY

Everything the agent can do, your code can do too: 420 tools over MCP, a REST API at trmnly.dev, a CLI for the panes, and a plugin API for adding your own.

Ways in

MCP server — on your Mac

Claude Code, Codex, Claude Desktop, Agent SDK scripts

Every tool the in-app agent has, behind the same approval policy. A stdio launcher over a Unix socket; an optional loopback HTTP + SSE transport for clients that cannot spawn one.

claude mcp add --scope user trmnly -- \
  "$HOME/Library/Application Support/TRMNLY/mcp-bridge"
Read more →

MCP server — hosted

Any MCP client, no Mac required

trmnly.dev/mcp drives your cloud workspace. OAuth 2.1 with PKCE and dynamic client registration: the first connect opens a consent page, no token to paste.

claude mcp add --transport http trmnly-cloud https://trmnly.dev/mcp
codex mcp add trmnly-cloud --url https://trmnly.dev/mcp
Read more →

REST API — trmnly.dev/api/v1

The desktop app, the iOS app, your own scripts

Pairing, devices, tunnels, credits, feedback and account endpoints. A session cookie or a bearer device token; every route is documented below.

curl https://trmnly.dev/api/v1/devices \
  -H "Authorization: Bearer $TRMNLY_TOKEN"
Read more →

trmnly CLI

Anything running in a pane

Panes name themselves, report status and progress, raise flags for the operator, and spawn or message other panes.

trmnly set-title "F2 Routes"
trmnly set-progress 0.4
trmnly raise-flag "Need a call on the schema migration"
Read more →

JavaScript plugins

Your own tools, status pills and sidebar views

Drop a .js file in the plugins folder. Tools a plugin registers reach the agent and every MCP client automatically.

trmnly.tools.register({
  name: "echo",
  description: "Return the input verbatim.",
  inputSchema: { type: "object", properties: { text: { type: "string" } } },
  execute: (args) => args.text,
});
Read more →

AppleScript & Shortcuts

macOS automation

Queue commands, focus panes and read terminal details from Script Editor, osascript or the Shortcuts app, with per-source consent.

tell application "TRMNLY"
    queue command "npm test" to terminal 1 of tab 1 of window 1
end tell
Read more →

The tool surface

420 built-in tools on macOS, each classified READ (runs silently under the default posture) or WRITE (asks first). MCP clients get the same list, plus whatever plugins and inbound MCP servers add at runtime. The cloud workspace and the Linux app serve smaller sets under the same names.

Every tool, with its arguments →

Web API reference (trmnly.dev)

Availability: Any platform — this is trmnly.dev's web API, not an app feature.

The TRMNLY desktop app, the iPhone app, the cloud workspace and the web dashboard all talk to a Next.js backend at trmnly.dev: accounts and licensing, device pairing and remote access, credits and managed inference, shared chat, the cloud workspace, telemetry, and macOS auto-updates. This page is the canonical reference for those endpoints.

Routes live under site/app/api/. Every path below is relative to https://trmnly.dev/api unless it is written out in full (/mcp, /.well-known/…). All routes run on the Node.js runtime (export const runtime = "nodejs"); none use edge.

Authentication

Several schemes are in use. Don't mix them up.

Scheme Used by How to send Verified by
Session cookie (Auth.js) The signed-in website Session cookie auth()
Bearer device token Desktop app, iPhone app, paired browsers, API scripts Authorization: Bearer trmnly_… resolveCaller() / requireCaller()
MCP sign-in token MCP clients that signed in through /api/oauth/* Authorization: Bearer trmnly_… on a cloud-agent device row resolveCaller(req, { allowCloudAgent: true }) — accepted by /mcp only
Admin session /admin/*, internal panels Session cookie of a verified address in ADMIN_EMAILS requireAdmin()
Box attach token A cloud workspace calling the site for its owner Authorization: Bearer <attach token> + x-trmnly-workspace-user: <userId> boxCaller() / resolveBoxTelemetryCaller()
Cron secret Vercel Cron Authorization: Bearer $CRON_SECRET (an admin session also works) timing-safe compare
Run callback token A scheduled job reporting back from the box Authorization: Bearer <per-run token> timing-safe compare against the run row
HMAC-SHA256 Cred and GitHub webhooks X-Cred-Signature / X-Hub-Signature-256 timing-safe compare
None Pairing handshake, appcast, public forms, page-view beacon, OAuth metadata/registration n/a per-IP rate limit

resolveCaller() accepts either a session cookie or a bearer device token, so the web dashboard, the desktop app and the iOS/remote clients share one surface. Three things narrow it:

  • Scoped tokens — a browser pairing token, a redeemed invite, or a token whose explicit scopes leave out admin — are refused unless the route opts in (allowScoped). Refused with 403 { code: "device_scoped" }.
  • Unconfirmed devices (minted by the GitHub device flow, not yet confirmed by the owner) are refused unless the route opts in (allowUnconfirmed). Refused with 403 { code: "device_unconfirmed" } — never a 401, which a client reads as "signed out".
  • MCP sign-in tokens (platform: "cloud-agent") are treated as no token at all everywhere except /mcp.

An expired or revoked token is a 401. A cookie on a state-changing request (anything but GET/HEAD/OPTIONS) must also carry a same-origin Origin header, or the cookie is ignored.

Several routes also require a verified email: anything that touches the credit wallet (looked up by email), the cloud workspace, and the assistant. Those answer 403 until the address is confirmed.

All responses are JSON unless noted. Errors are { "ok": false, "error": "<message>" } with the HTTP status, plus a machine-readable code where the entry says so.

Client identification and request ids

Native clients send X-TRMNLY-Client: <app>/<version> (<build>) <arch> on every request — macos/0.1.128 (125) arm64, linux/0.1.128 x86_64. The build and arch are optional, and the header itself is: older clients send none. The server reads it only for diagnostics (server error rows and log lines); a value over 100 characters or of any other shape is ignored.

Every 5xx answer carries X-TRMNLY-Request-Id. Quote it in a bug report: it is the id on the server's log line and on the web.error.* row for that failure. Managed inference (/v1/inference/*) sends it on every answer.

Pairing

Used by the desktop to bind itself to a trmnly.dev account without an out-of-band token paste. Stateless on the desktop side: it gets a code and nonce, surfaces the code, and polls until the user claims it.

POST /v1/pair/start

Start a pairing handshake. No auth (10/min per IP).

Request (optional): { deviceName?, platform?, appVersion? }. Response: { ok, code, nonce, expiresInSeconds, pairUrl }. The code (10-minute lifetime) is what the user types at trmnly.dev/pair; the nonce is the polling secret the desktop keeps.

POST /v1/pair/poll

Poll for a claimed code. No auth (60/min per IP).

Request: { nonce }. Response: { ok, status: "pending" } until claimed, then { ok, status: "claimed", deviceId, token, tokenPrefix }. The token is re-delivered to the same nonce for a short grace window in case that response was lost; after that, and for unknown nonces, { ok, status: "expired" }. The token is the desktop's bearer token from then on.

GET /v1/pair/preview?code=…

Which device a code belongs to, so the claim page can show it before the user confirms. Session-only, 20/min per account. Response: { ok, device: { deviceName, platform, appVersion, createdAt, … } }. Unknown, expired and already-claimed codes all answer 404.

POST /v1/pair/claim

Browser side of pairing — claim a code, mint the device + token. Session-only, 30/min per account.

Request: { code, name?, confirmPhone? } — name renames the device; confirmPhone: true trusts a paired iPhone, honoured only when the code itself declared ios. Response: { ok, deviceId, deviceName, trustedPhone }.

The browser never gets the device's own token (that goes to /v1/pair/poll). For a Mac or other desktop code it also gets a token of its own so the /remote page can drive that Mac: { token, tokenPrefix, browserDeviceId, tokenExpiresAt, scopes } — kind browser, scopes read + terminal, bound to that Mac alone, 12 hours. A phone's code gets no extra token.

404 unknown or expired code, 410 already claimed, 409 being claimed concurrently.

POST /v1/pair/github/start

"Sign in with GitHub" for clients with no browser (GitHub device flow). No auth (10/min per IP). Request (optional): { deviceName?, platform?, appVersion? }. Response: { ok, nonce, userCode, verificationUri, interval, expiresIn }. 502 when GitHub issues no device code (usually Device Flow switched off on the GitHub App); 503 when GitHub sign-in isn't configured.

POST /v1/pair/github/poll

Poll until the user approves the code on github.com. No auth (60/min per IP; GitHub's interval is enforced server-side). Request: { nonce }.

Response: { ok, status: "pending", interval }, { ok, status: "denied" }, { ok, status: "expired" }, or on success { ok, status: "claimed", deviceId, deviceName, token, tokenPrefix, confirmed: false }. The GitHub token is used once to read the identity and never stored. The device is unconfirmed until the owner confirms it on the dashboard, and the owner is emailed about it. A first sign-in from an address nobody approved answers 403 (invite-only; the address joins the waitlist); other terminal failures are 502.

POST /v1/pair/redeem · GET /v1/pair/redeem?code=…

Redeem a time-limited invite (see /v1/devices/invite). Session or bearer token — the guest must be signed in to some TRMNLY account; the code is still the grant. 10/min per IP.

POST request: { code, deviceName?, platform?, appVersion? } — platform: "ios" mints a phone token, anything else a browser token; never a Mac. Response: { ok, token, tokenPrefix, deviceId, kind, scopes, expiresAt, macDeviceId }. The token expires with the grant and, when the invite was bound to a Mac, reaches only that Mac. The owner is emailed.

GET previews a pending invite: { ok, invite: { scopes, expiresAt, macDeviceId, macName, name } }. Unknown, expired and used codes are 404.

Devices

A "device" is one token: a paired Mac, a phone, a browser pairing, an invite guest, an API script, or an MCP sign-in. Each has its own bearer token, a kind (mac, phone, browser, …), optional explicit scopes (read, terminal, files:write, agent, gui, docker, admin; null means the legacy rules), and an optional expiry.

GET /v1/devices

List the account's devices. Session or bearer token (scoped and unconfirmed tokens allowed).

Response: { ok, devices: [{ id, name, platform, appVersion, tokenPrefix, revoked, createdAt, lastSeenAt, tunnelUrl, tunnelStatus, tunnelUpdatedAt, tunnelReason, trustedPhone, kind, scopes, effectiveScopes, expiresAt, expired, confirmed, remoteDisabled, audienceDeviceId, lanEndpoints, transport, wol }], callerDeviceId, caller }. caller describes the calling token ({ deviceId, kind, scopes, effectiveScopes, expiresAt, confirmed, audienceDeviceId }) or is { via: "session" }.

Token callers never see a tunnel URL for a Mac that is unconfirmed or remote-disabled (it reads as down, with the reason), nor any URL while they are themselves unconfirmed. A token bound to one Mac sees only that Mac and itself. wol is shown to the owner only (a session, or their own phone or Mac).

POST /v1/devices

Mint a device token by hand (scripts, MCP clients that can't sign in). Session-only.

Request (all optional): { name?, platform?, appVersion? }. Response (201): { ok, device, token, tokenWarning }. The token is shown exactly once — there's no recovery, only revoke + re-issue.

PATCH /v1/devices/[id]

Change a device. Session or bearer token. Body: any of

Field Who may set it
name The session, the device itself, or a full token on the account holding admin
trustedPhone Session only; setting it needs a live row that declared ios
confirmed: true Session only — confirms a GitHub-flow device. No un-confirm; revoke instead
remoteDisabled false: the session or that Mac itself. true: also an admin token

Response: { ok, device: { id, name, trustedPhone, confirmed, remoteDisabled } }. 403 when the caller may not change a field, 404 not on this account, 400 for a revoked device or an untrustable row.

DELETE /v1/devices/[id]

Revoke a device (soft — the row is flagged, not deleted; its push token is cleared). Session or bearer token. Sessions can revoke any device they own; a token can only revoke its own device (403 otherwise). Revoking a Mac also revokes every token bound to it alone (its browser pairings and Mac-bound invites).

DELETE /v1/devices/me

A device revokes itself with its own token, without knowing its id (iOS sign-out, macOS unpair). Bearer token only (400 for a session). Clears the push token and tunnel. Response: { ok, deviceId }. 401 for an unknown or already-revoked token — callers treat it as success.

PUT /v1/devices/[id]/scopes

Set what a device may do on the account's Macs. Session-only.

Request: { scopes: string[] | null, expiresAt?: string | null } — null scopes return the device to the legacy rules; expiresAt null clears it, omitted leaves it. Response: { ok, device: { id, scopes, effectiveScopes, expiresAt } }. 400 for a bad scope, a past expiry, or a Mac (a Mac's own token is its identity — scope the devices that drive it). Macs pick the change up on their next heartbeat (20–60 s).

POST /v1/devices/invite

Create a time-limited grant ("Invite for 1h"). Session, or a full device token that is the trusted iPhone or holds admin (and can't grant scopes it doesn't hold). 20/hour per account.

Request: { scopes, minutes, deviceId?, name? } — minutes is clamped to 5…10080 and counts from now; deviceId binds the grant to one confirmed Mac. Response: { ok, code, url, expiresAt, scopes, deviceId, minutes, limits: { minMinutes, maxMinutes } }. The code is a bearer credential until redeemed once at /v1/pair/redeem or by opening url (render it as a QR code).

GET /v1/devices/invite lists pending invites ({ ok, invites: [{ code, url, expiresAt, createdAt, name, scopes, deviceId }] }); DELETE /v1/devices/invite?code=… cancels one. Same auth.

POST /v1/devices/kill-all

"Kill all remote access". Session, or a full (unscoped, unexpired, confirmed) token that is a Mac, the trusted iPhone, or holds admin. No body.

Revokes every live non-Mac token on the account except the caller's own, deletes unredeemed invites, and marks every Mac remoteDisabled with its tunnel URL withdrawn (Macs stay paired so they hear the flag on their next heartbeat). Response: { ok, revoked, macsDisabled, keptDeviceId }. Remote comes back per Mac via PATCH /v1/devices/[id] { remoteDisabled: false }.

GET /v1/devices/[id]/endpoint

Resolve deviceId → current tunnel URL for Remote control. Session or bearer token (scoped allowed; an unconfirmed caller gets 403 device_unconfirmed), constrained to the caller's own devices; a token bound to one Mac may look up only that Mac.

Response: { ok, device: { id, name, platform, appVersion, lastSeenAt }, endpoint: { url, status, updatedAt, reason, lanEndpoints, transport, wol? }, tunnelReason, confirmed, remoteDisabled, toolScope, accessToken? }. An unconfirmed or remote-disabled Mac answers status: "down", no URL, and the reason. Token callers looking up a Mac whose tunnel is up also get accessToken: { token, expiresAt, audience, kid } — a 15-minute Ed25519 JWT only that Mac accepts (keys at /v1/remote/keys). Revoked devices return 410. See Remote control.

POST|PUT /v1/devices/me/tunnel

Mac heartbeat — advertise the current tunnel URL. Bearer token of a Mac (unconfirmed and scoped accepted so an unconfirmed Mac keeps its keychain; phones, browsers and expiring grants are 403). Used by RemoteTunnelManager.

Request: { url, status: "up" | "down" | "error", reason?, error?, lanEndpoints?, wol?, transport? } — empty url clears it; status: "up" needs an https URL on *.trycloudflare.com / *.cfargotunnel.com.

Response: { ok, authorizedTokenHashes, authorizedTokens, pushDevices, remoteDisabled, confirmed, deviceId, accessTokenKeys } — the roster of token hashes (with kind, trustedPhone, scopes, expiresAt) this Mac should accept, how many phones can be woken for an approval, and the JWKs for the access tokens above. A killed or unconfirmed Mac gets empty rosters; MCP sign-in tokens are never on a roster.

POST|DELETE /v1/devices/me/push-token

Register (upsert) or clear the phone's APNs token. Bearer token, own row only (scoped and unconfirmed accepted). Request: { token, environment?: "production" | "sandbox" }. Response: { ok }; 404 for a revoked device.

POST /v1/devices/me/push-approval

A Mac has a tool call waiting on approval and no phone holds its event stream: wake the owner's phones. Bearer token of a Mac (403 for a phone, browser or MCP token). 60/min per account.

Request: { requestId (uuid), tool, reason?, arguments?, safety?: "read-only" | "writes" | "dangerous", macName? }. Response: { ok, sent, failures? , reason? } — reason is remote-disabled, no-push-devices or apns-not-configured when nothing was sent. The time-sensitive notification carries the request id and the Mac's tunnel URL; it expires after 120 s.

POST /v1/push/event

A Mac tells the account's phones that something they were watching happened (pane idle, command finished, agent turn done, flag raised). Bearer token of a Mac (full, confirmed). 30/min per Mac.

Request: { kind (snake_case, ≤ 40), title (1–200), body? (≤ 2000), data? }. Response: { ok, sent, failures?, reason? } with the same reason values as push-approval. Reaches confirmed, unexpired phones that can read, plus guests bound to this Mac.

GET /v1/remote/keys

The JWKS that signs the access tokens from /v1/devices/[id]/endpoint. No auth. Response: { keys: [jwk] }, cached 5 minutes. 503 if the signing secret is missing.

Identity & licensing

GET /v1/me

Return the calling user's profile. Session or bearer token (unconfirmed allowed).

Response: { ok, user: { id, email, name, image, plan, verified }, via, github } — via is "session" or "token". github is { linked, login, userId, profileUrl, appConfigured, installUrl, installations }, or null when the lookup failed (render as "couldn't load", never "not linked").

POST /v1/me/delete

Permanently delete the account (App Store 5.1.1(v)). Session or bearer token (MCP sign-in tokens refused). 5/hour.

Request: { "confirm": "DELETE" } — anything else is 400. Cancels the monthly plan, deletes the cloud workspace, its saved archives and the assistant's files first, aborting with 502 (nothing deleted) if any fails; then the account rows. Response: { ok, deleted: true }.

POST /account/verify-email · GET /account/verify-email?t=…

POST re-sends the verification link to the signed-in account (session-only, 3/hour): { ok } or { ok, alreadyVerified: true }. GET is the emailed link: marks the address verified, grants the sign-up credits the first time, and redirects (303) to /app?verify=done or /app?verify=invalid.

POST /v1/license/verify

Entitlement and release-build access for an installed app, called at launch and every 15 minutes. Session or bearer token (unconfirmed allowed). 401 means the token is revoked or unknown — the app reads it as "access removed".

Request (optional): { machineId? (hex SHA-256), appVersion? }. Every answer carries { ok, valid, plan, entitled, user: { id, email }, access }:

access Extra fields When
"approved" updatesUntil, and for a token caller with machineId: pass, passExpiresAt Approved account; pass is the signed proof the app may run, good offline for 7 days
"pending" — Account not approved yet (the operator is emailed once)
"pending" reason: "device_unconfirmed" GitHub-flow device not confirmed
"pending" reason: "seats_full", seats, machines, message Seat-only account with every seat taken by another Mac
"pending" reason: "updates_expired", updatesUntil, coveredVersion, renewUrl, message This version was released after the licence's update window

updatesUntil is null for accounts whose updates never end. 503 when the database or the pass signing key is unavailable (never a false "pending").

Desktop licence

Route Method Auth What it does
/licence/checkout POST session, verified, invited or approved to buy cred.diy hosted checkout for one seat. { ok, url }. 403 not invited / unverified, 503 not on sale
/licence/renew POST session, verified Checkout for a year of updates. 409 no seat to renew or updates never end, 503 not on sale
/licence/machines GET session { ok, licence }: seats and the Macs holding them
/licence/machines/[id] DELETE session, own rows Free a Mac's seat; it keeps running on its current pass (≤ 7 days)

The cred webhook turns the resulting credits.issued into the seat or the update days.

Credits & billing

Credits live in a cred.diy wallet keyed by the account's email, so every route here needs a verified email (403 otherwise), answers 503 when Cred isn't configured, and 409 when the account has no email.

GET /v1/credits/balance

Session or bearer token, 120/min. Response: { ok, balance, creditTypeId, symbol }. When Cred is slow or down the route answers with the last figure it gave for this account, up to 7 days old, and adds stale: true and asOf (ISO 8601). 502 only when nothing is cached.

GET /v1/credits/tiers

What can be bought — credit packs only (the seat and renewal are sold from the Licence page). Session or bearer token. Response: { ok, tiers }.

POST /v1/credits/checkout

Start a hosted checkout. Session or bearer token, 20/min. Request: { pricingTierId, successUrl?, cancelUrl? } — the desktop passes trmnly:// callbacks; redirects must be on the allowlist (400 otherwise). Response: { ok, url }. 400 for a tier not for sale, 502 if Cred can't create it.

POST /credits/subscription

Open Stripe's billing portal for the monthly plan (via Cred). Session-only, verified. Response: { ok, url }; 404 when there's no monthly plan.

POST /v1/credits/usage

A usage receipt from a finished (or streaming) desktop agent turn, debited from the wallet. Session or bearer token, 240/min.

Request: { model, inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens, clientCostHint? } — raw counts only; the server computes the cost (the hint is logged when it disagrees). Response: { ok, amount, balance }. 402 when the wallet refuses the deduction.

Managed inference

The agent runs on TRMNLY's provider keys and pays in credits. Session (same-origin only) or bearer token, verified email. 60 requests/min per provider; at most 4 replies in flight per account.

Route Method Shape
/v1/inference/anthropic/messages POST The Anthropic Messages API, byte for byte — the client is a base-URL swap. anthropic-version and allowed anthropic-beta headers pass through
/v1/inference/openai/chat/completions POST OpenAI Chat Completions
/v1/inference/models GET { ok, rateVersion, verified, models: [{ id, provider, displayName, contextWindow, creditsPerMInput, creditsPerMOutput, creditsPerMCacheRead, creditsPerMCacheWrite }] } — only providers this deployment holds a key for. 60/min

Admission happens before the upstream call, against the live balance minus what the account's other in-flight turns hold: 402 { code: "insufficient_credits", balance, reserve }. The output budget may be clamped to what the balance can pay for, reported in x-trmnly-max-output-tokens. Bodies over 4 MB are 413; a body the proxy refuses is 400 with code (invalid_body, model_not_managed, file_sources_not_allowed). Upstream errors are passed through verbatim with their status. Streams are settled once, when they end; an abandoned stream stops costing when the client hangs up.

Image generation

Route Method Auth Notes
/v1/images/generate POST {prompt, size?, quality?, count?, format?, transparent?} device token, web session, or a cloud box (its attach token as bearer + x-trmnly-workspace-user) Draws with OpenAI gpt-image-2.5-flare on TRMNLY's key and debits credits (2 / 8 / 31 per square image by quality, 3 / 12 / 45 wide or tall). Answers {ok, model, size, quality, count, format, credits, balance, promptClipped, images:[{b64, format}]}. 402 code: credits below the price, 413 code: too_large when the answer would pass ~4 MB, 422 code: rejected when OpenAI refuses the request, 502 code: provider for an upstream failure.

POST /webhooks/cred

Inbound webhook from cred.diy. HMAC-SHA256 of the raw body in X-Cred-Signature (an optional sha256= prefix is stripped); every request is refused while CRED_WEBHOOK_SECRET is unset. credits.issued for the licence or renewal tier grants the seat or update days, idempotently on purchase_id; other events are logged and acknowledged. 500 only when a licence grant fails (cred retries); 401 on signature mismatch.

Shared chat

Rooms on trmnly.dev shared between people and agents (shared chat). Every route takes a session or bearer token and needs an account with an email. Room refs are r:<code>.

Route Method What it does
/v1/chat/rooms GET { ok, rooms: [{ ref, title, kind, project, you, role, members, updated_at }] }
/v1/chat/rooms POST {title, kind?, project_name?, members?, agents?, import?} Create a room, optionally importing desktop threads (import.threads[] with local_ref, title, topic, messages). Answers { ok, room, threads: [{ local_ref, ref, title }], members }
/v1/chat/rooms/[room] GET Room, members, and open invites (email invites to everyone; link invites to the owner)
/v1/chat/rooms/[room] PATCH {title} Rename. Owner only
/v1/chat/rooms/[room] DELETE Delete. Owner only
/v1/chat/rooms/[room]/members POST {email} or {agent, name?} Add a person (any member) or one of the caller's own agents. 409 when the handle belongs to another member, 429 too many invites
/v1/chat/rooms/[room]/members DELETE ?member=<id> / ?invite=<id> Remove a member (owner: anyone; anyone: themselves or their agents) or cancel an email invite
/v1/chat/rooms/[room]/links POST / DELETE ?id= Create (token returned once; multi-use, 7 days) or revoke an invite link. Owner only
/v1/chat/join POST {token} Spend an email or link invite. { ok, room, handle }; 410 used or expired
/v1/chat/lookup GET ?email= Does this address have an account? { ok, email, exists, name, image, you }. Throttled
/v1/chat/tool POST {name, arguments} Run a chat_* tool against shared rooms (chat_wait parks up to 120 s). { ok, result }; a tool that ran and refused is 400 with the reason

Conversation archive

The Mac app's conversation archive (conversation archive) uploads transcripts to the account with its device token.

Route Method Auth What it does
/v1/conversations/upload PUT ?key&source&part&parts&bytes&modified + x-conversation-title / x-conversation-project headers (percent-encoded) session or device token One gzip part of a transcript (≤ 4 MB), in order; the row is written on the last part. Answers { ok, stored, of }. 413 code: quota_full when the account's quota is full (checked on part 0); 503 with no Blob store.
/v1/conversations/[id] GET session Streams the original transcript as an attachment.
/v1/conversations/[id] DELETE session Deletes it and its stored parts.

Feedback

POST /v1/feedback · GET /v1/feedback

Bug reports and feature requests (feedback reports). Session or bearer token (unconfirmed allowed); the device id comes from the token, never the body.

POST takes the report plus optional conversation (the agent chat the user chose to include) and logs (the Mac's diagnostics bundle). Both are sealed into Blob; the report is saved even if that fails, and conversationStored / logsStored say which happened. 429 with Retry-After past the hourly limit. GET returns { ok, reports }, the caller's own.

Cloud workspace

One Vercel Sandbox microVM per account (cloud workspace). Every route needs an account that may use the workspace — a verified email and either WORKSPACE_OPEN=true or an admin address — or answers 403 "Cloud workspace is not enabled for this account yet.". Anything that can start the box passes the same start gate: 429 past the monthly quota, 402 outOfCredits with an empty balance.

Auth below is caller (session or full bearer token) or session (browser only).

Route Method Auth What it does
/workspace/terminal GET caller Reattach only — never boots. { ok: true, url (wss), token, quota }, or { ok: false, error } (still 200) when no current box is up
/workspace/terminal POST caller Boot or resume the box, start its agent, push the key vault. { ok, url, token, quota, restored?, bootstrap? }. 20/min
/workspace/heartbeat POST caller Keep the box alive and metered while a tab is attached. { ok, quota }
/workspace/stop POST caller Stop the box via the sandbox host (works when the agent is wedged). { ok, running: false, stopped }
/workspace/save POST ?ifChanged=1&force=1 caller Tar, seal and store ~/workspace + dotfiles. ifChanged=1 (autosave) never wakes a stopped box and skips an unchanged one ({ skipped: true }); a big shrink is refused 409 shrink: true without force=1; over the size cap is 413
/workspace/exec POST {command, cwd?} caller Run one shell command without the agent (the way to look at a box whose agent is down). { ok, stdout, stderr, exitCode }. 60/min
/workspace/exec GET session { ok, workspace } — whether this account has one, and its sandbox name
/workspace/mcp POST (JSON-RPC body) caller Proxy to the box's MCP server; the attach token is added server-side. x-trmnly-wake: 0 stops a background poll from starting the box
/workspace/agent POST {prompt, resume?, model?, cwd?, mode?, attachments?} caller One headless Claude Code turn on the box, streamed as NDJSON ({type:"trmnly_error", error} on failure). mode is auto/ask/plan; up to 6 attachments of ≤ 8 MB as base64. Needs a Claude credential set
/workspace/agents GET / POST {agent: "claude"|"codex", token} session Whether Claude Code / Codex is signed in on the box; set or clear (empty token) the credential. Write-only
/workspace/file POST {path} / PUT {path, content} session Read or write a text file (≤ 2 MB; binaries 415) on a running box (409 otherwise)
/workspace/transfer POST {path} / PUT {path, dataB64} session Binary download (≤ 10 MB) / upload (≤ 25 MB) as base64, running box only
/workspace/preview GET session { ok, ports: [{ port, listening, url }] } for the preview ports, running box only
/workspace/projects GET / POST {name, directory, color?} / PATCH {id, …} / DELETE {id} session The project rail. Deleting removes the bookmark, not the directory
/workspace/keys GET / POST {name, value} / DELETE {name} session The access-key vault: names only, values write-only; a running box is updated
/workspace/github/repos GET session Repositories the TRMNLY GitHub App can reach (200 with a next step when it isn't installed)
/workspace/github/clone POST {repo, directory?, branch?, addProject?} session Clone owner/name into ~/workspace/<directory> using the installation's token (never written to the remote URL), and add a rail entry. 10/min
/workspace/jobs GET / POST / PATCH {id, …} / DELETE ?id= session Scheduled jobs (agent or command, cron or runAt, landing pr/push/report, …) with recent runs and next-run info. Deleting mid-run is 409
/workspace/jobs/run POST {id} / GET ?runId= session Run a job now (409 when deferred behind a running job); or read a run with its live log tail
/workspace/jobs/secret GET / POST {which: "claude"|"github", token} session Whether the headless-run tokens are set; set or clear them. Write-only
/workspace/cron GET cron secret or admin The scheduler tick (every 15 min): sweeps stale runs, dispatches due jobs, at most 4 launches per tick
/workspace/cron/complete POST ?runId= {code, log, result} per-run callback token The box reports a finished run. Idempotent

/mcp (also /api/mcp)

The account's cloud workspace as a public MCP endpoint (Streamable HTTP):

claude mcp add --transport http trmnly https://trmnly.dev/mcp

Bearer token — a device token, or one minted by MCP sign-in (below); the workspace entitlement applies. With no token the 401 carries WWW-Authenticate: Bearer … resource_metadata="…", which starts browser sign-in in a compliant client (error="invalid_token" when a token was sent and refused).

  • POST — JSON-RPC. initialize, ping and tools/list are answered at the edge without starting the box; notifications get 202 with no body; control-plane tools (workspace_start, workspace_status, …) and shared chat_* calls are served from the database. Any other tools/call starts the box if needed and is proxied once, never retried. Unknown methods are a JSON-RPC methodNotFound.
  • GET — 405 (no server-initiated stream); a browser asking for HTML is redirected to /app/devices#connections.
  • OPTIONS / DELETE — 204.

MCP sign-in (OAuth)

OAuth 2.1 with PKCE so an MCP client can connect with no pasted token. The consent page is /oauth/authorize (a page, not an API route).

Route Method What it does
/.well-known/oauth-protected-resource[/mcp|/api/mcp] → /oauth/metadata/resource GET RFC 9728 metadata; resource is the URL the client connected to
/.well-known/oauth-authorization-server, /.well-known/openid-configuration → /oauth/metadata/server GET RFC 8414 metadata: /oauth/authorize, /api/oauth/token, /api/oauth/register
/oauth/register POST RFC 7591 dynamic registration. Nothing stored: the client_id is the signed registration. Public clients only (token_endpoint_auth_method: none). 201
/oauth/token POST (form or JSON) Code → { access_token, token_type: "Bearer", scope: "workspace" }. The token is a trmnly_… device token on a cloud-agent row: it reaches /mcp and nothing else, never expires, and is revoked from the dashboard's Connections. A code used twice revokes the token it minted (invalid_grant)

All four answer OPTIONS preflights. Errors are OAuth-shaped ({ error, error_description }).

Web assistant

The "Ask TRMNLY" side panel in /app. Session only (a device token is 403), same-origin only, verified email.

Route Method What it does
/assistant POST {messages, decisions?, attachments?} (JSON) One turn, streamed as NDJSON: text, tool, approval, notice, done {messages, credits, balance}, error. The browser holds the transcript; a turn paused on an approval resumes when the next request carries decisions (allow/deny per tool-use id). Debited in credits. 402 outOfCredits, 20/min
/assistant/files POST (multipart file, thumbnail?) Upload an attachment to the Files API (images, PDFs, text; ≤ 4 MB). { ok, fileId, token, kind, name, size, expiresAt } — the token proves the file is this person's. 415 wrong type, 413 too big
/assistant/files GET The person's file history, with fresh tokens
/assistant/files DELETE {tokens, unsent?} Delete files from Anthropic (those of a deleted chat stay in history; unsent: true drops them from history too)
/assistant/files/[id] DELETE Remove one file from the history and from Anthropic

Updates (Sparkle)

GET /v1/updates/appcast.xml

Sparkle appcast for macOS auto-updates. No auth. Returns XML, cached 5 minutes. Built from LATEST_APP_* environment variables — a release step sets the version, download URL, EdDSA signature, and so on; no code change needed. With no release set it is an empty, well-formed feed.

Telemetry

POST /v1/telemetry

Single event ingest. Session or bearer token (scoped and unconfirmed allowed), or a cloud box's attach token, which may post only box events. Thin wrapper around the batch endpoint. Request: one event object. Response: { ok, written }.

POST /v1/telemetry/batch

Batch event ingest, same auth. Take this path from the desktop — it ships events on a flush interval. 120 requests/min per device (shared with the single-event route).

Request: { events: [ … ] }. Response: { ok, written }.

Event shape

Field Required Limits
name yes <app>.<area>.<verb>, lowercase a-z0-9._-, starting with a letter or digit, at most 80 characters
app yes "web", "macos", "ios", "linux", "windows", "trmnlyd", "cli" or "box"
properties no A JSON object. At most 4096 bytes once serialized (compact JSON, UTF-8)
appVersion, platform no Strings, at most 40 characters
sessionId no String, 1–80 characters
clientCreatedAt no ISO-8601 in UTC with a Z suffix (2026-10-06T12:00:00Z). An offset such as +02:00 is refused

A batch is all-or-nothing — nothing is written unless every event passes:

  • One event that fails the table above answers 400 for the whole batch.
  • One event whose properties are over 4096 bytes answers 413 for the whole batch. Truncate on the client before sending.
  • More than 100 events answers 413. Split the batch.
  • 401 means the device token is missing, revoked or unpaired. Events are only accepted from a signed-in caller.

Error events (<app>.error.<area>)

An event whose name has error as its second segment is an error report. The server needs no change for a new area: anything matching <app>.error.<area> is picked up by /admin/errors and the Errors section of /app/admin.

The macOS app sends:

Name When
macos.error.agent An agent turn failed — the provider, stream or CLI harness error shown in the sidebar banner
macos.error.agent_tool A tool call failed
macos.error.mcp_bridge The MCP bridge failed
macos.error.app The previous run of the app ended abnormally
macos.error.hang The main thread stalled past the watchdog threshold; frames names the app's own functions on the busiest path
macos.error.metrickit A MetricKit diagnostic arrived — crash, hang, CPU or disk-write exception, slow launch
macos.error.persistence A store could not be read, decoded or written
macos.error.remote Remote control failed on the Mac — tunnel, heartbeat, push, LAN listener, cloud handoff

The iPhone app sends the same shape as ios.error.<area> with app: "ios": agent (cloud agent), agent_tool, remote (requests to the Mac, the event stream, the device list, push registration), persistence and metrickit. The specs/error-uplink pair lists every kind and field.

The website records its own errors with app: "web":

Name When
web.error.client An uncaught exception or unhandled rejection in a signed-in browser
web.error.render A React render error caught by app/error.tsx or app/global-error.tsx
web.error.fetch One of the site's own /api routes answered 5xx to the browser
web.error.server Next.js caught a server exception (instrumentation.ts onRequestError); no user, platform: "server"
web.error.api A route answered 5xx through apiError; the user and device when the route had resolved them, platform: "server"
web.error.upstream A provider behind managed inference or image generation answered an error that is ours, not the request's (kind: upstream_<status>; a 400, 413 or 422 is only logged)

Every web.error.* row the server writes carries requestId (the X-TRMNLY-Request-Id the caller was sent, when there was one) and client (the caller's X-TRMNLY-Client, or null) in properties.

properties on an error event:

Property Type Meaning
kind string, required Short machine name for the failure: provider_http, stream, harness_exit, tool_failed, …
message string, required Human-readable detail. Scrub secrets and truncate on the client; the server stores what it is sent
count number How many identical occurrences this one event stands for. Default 1
provider, model string Which model the turn was using
status number HTTP status or process exit code
tool string Tool name, for agent_tool
category string Client-side error category
build string debug or release
os_version string

sessionId on these is one per app launch, not a chat id.

Errors are grouped by name, kind and a fingerprint of the first 300 characters of message. The fingerprint lowercases the text and takes out what varies between occurrences of one failure: digits, UUIDs, hex ids, long opaque ids, file paths, and the path and query of a URL (the host stays). So HTTP 529 after 3212 ms and HTTP 529 after 41 ms are one group. A number of up to three digits directly after http, status, code, exit, errno or signal is kept, so a 401 and a 529 are not. Put what distinguishes two failures near the start of message, not after a long preamble.

POST /v1/pv

One page view from the site's own beacon (site analytics). No auth, anonymous by design. Body: { path, referrer?, utm? } (≤ 2 KB). Always answers 204, whatever was kept; bots and views over 120/min per IP are dropped silently.

Admin (requireAdmin())

Internal panels. Every route requires the browser session of a verified address listed in ADMIN_EMAILS — a device bearer token is answered 403.

Route Method What it returns
/admin/stats GET { ok, counts: { users, devices, waitlist } }
/admin/users GET ?limit&offset Paginated users (default 100, max 500): id, email, name, plan, Stripe customer id, access approval and request times, licence seats, licensedAt, updatesUntil
/admin/users/[id]/access POST {approved} Approve an account to run release builds, or remove that (takes effect at each Mac's next renewal)
/admin/devices GET ?limit&offset Paginated device list across users (default 100, max 500)
/admin/waitlist GET ?limit&offset Paginated waitlist entries (default 500, max 5000)
/admin/waitlist.csv GET CSV export of the waitlist, with approved_at / approved_by
/admin/waitlist/approve POST {email, approved} Approve an address to create an account and buy a desktop seat, or revoke that; inserts the waitlist row if missing and emails the person on approval (emailed says whether it went)
/admin/investors.csv GET CSV of every /investors indication of interest
/admin/metrics GET ?range Active users (DAU / WAU / MAU, per app), top events and daily counts from telemetry; range 1–365 days, default 30
/admin/errors GET ?since&limit&name&kind&app&user&version&build App-reported errors (error events), grouped, plus the most recent raw rows
/admin/feedback/[id]/conversation GET ?download=1 The agent conversation attached to a feedback report (inline JSON, or as a download)
/admin/feedback/[id]/logs GET ?download=1 The logs bundle attached to a feedback report

GET /admin/errors

Parameter Default Meaning
since 7d Start of the window: an ISO date or timestamp, or a range back from now — 90m, 24h, 7d, 2w. Anything else answers 400
limit 200 How many raw events to return, at most 1000. Group counts always cover the whole window
name Exact event name, e.g. macos.error.agent
kind Exact properties.kind
app web, macos, ios, linux, windows, trmnlyd, cli or box
user Case-insensitive substring of the user's email
version Exact app version
build debug or release

Filters narrow groups and events alike. The window is measured on the server's receive time, not the client's clock.

{
  "ok": true,
  "since": "2026-09-29T12:00:00.000Z",
  "until": "2026-10-06T12:00:00.000Z",
  "limit": 200,
  "filters": { "name": null, "kind": null, "user": null, "version": null, "build": null },
  "totals": { "occurrences": 6, "events": 3, "groups": 1, "users": 2 },
  "truncated": false,
  "groups": [
    {
      "name": "macos.error.agent",
      "kind": "provider_http",
      "fingerprint": "http 529 after # ms",
      "count": 6,                 // occurrences, honouring properties.count
      "events": 3,                // rows
      "users": 2,                 // distinct signed-in users
      "firstSeen": "2026-09-30T11:19:53.351Z",
      "lastSeen": "2026-10-06T10:19:53.351Z",
      "versions": ["0.1.95", "0.1.94"],
      "sampleMessage": "HTTP 529 after 41 ms"   // most recent, first 300 characters
    }
  ],
  "events": [
    {
      "id": "…",
      "name": "macos.error.agent",
      "kind": "provider_http",
      "message": "HTTP 529 after 41 ms",
      "fingerprint": "http 529 after # ms",   // with name + kind, its group
      "count": 1,
      "userId": "…",
      "userEmail": "someone@example.com",
      "deviceId": "…",
      "app": "macos",
      "appVersion": "0.1.94",
      "platform": "macos-arm64",
      "sessionId": "…",
      "clientCreatedAt": null,
      "receivedAt": "2026-10-06T10:19:53.351Z",
      "properties": { "kind": "provider_http", "message": "HTTP 529 after 41 ms", "status": 529, "build": "release" }
    }
  ]
}

groups are ordered most frequent first, events newest first. truncated is true when the window held more than 5000 distinct messages; groups and totals then cover the most recent of them, and a shorter since gets exact numbers back.

Open it in a browser signed in to an admin account.

Internal

Route Method Auth What it does
/cron/error-digest GET ?dry=1 cron secret or admin Daily (15:00 UTC) email of the last 24 h of client error groups. A quiet day sends nothing; dry=1 returns the email instead
/workspace/cron GET cron secret or admin Scheduled-jobs tick (see Cloud workspace)
/webhooks/github POST HMAC (X-Hub-Signature-256, GITHUB_WEBHOOK_SECRET) GitHub App deliveries: installation, installation_repositories, github_app_authorization (revoked) keep installation and repo rows current; ping and other events are acknowledged. 500 on a database failure so the delivery can be redelivered
/webhooks/cred POST HMAC (X-Cred-Signature) See Credits & billing
/auth/[...nextauth] GET, POST — Auth.js handler; delegates to the providers in site/auth.ts / site/auth.config.ts. Browser-only

Marketing & public

All are no auth and rate-limited per IP. The form routes answer a filled honeypot with the same { ok: true } a person gets.

Route Method What it does
/waitlist GET { ok, count } — public signup count
/waitlist POST {email, firstTouch?} Join the waitlist (5/hour). { ok, stored, count, added }; re-submitting is a no-op and keeps the first-touch attribution. The team is emailed for a new address
/newsletter POST {email} Join the AW3 newsletter (5/hour). Same answer whether the address was new
/contact POST {name, email, company?, topic, message} Email the team (5/hour). 503 when it couldn't send
/investors POST {name, email, phone?, firm?, investorType, checkUsd, accredited, message?, consent} Record a non-binding indication of interest and email the team (5/hour)
/learn/[slug]/audio GET A /learn lesson read aloud: usually a 302 to the cached MP3; the first request generates it. Unknown slugs 404
/academy/[course]/[slug]/audio GET The same for an Academy lesson; gated lessons need the learner pass (401)
/academy/pass GET { unlocked } — whether this browser holds a learner pass
/academy/pass POST {email, next?, firstTouch?} Email a one-click link that sets the learner pass (5/hour). The address joins the waitlist (source: academy); a pass is not account approval
/academy/pass/verify GET ?t= The emailed link: sets the pass cookie and redirects back to the lesson (?pass=ok, or /academy?pass=expired)

Error taxonomy

Routes return one of:

Status When
200 Success
201 Created (POST /v1/devices, /oauth/register)
202 / 204 Accepted with no body (MCP notifications, page views, preflights)
400 Bad request body, missing required field, validation failure
401 Missing, invalid, revoked or expired auth — clients treat it as "signed out"
402 Not enough credits (code says which check)
403 Authenticated but not allowed: admin-only, unverified email, no workspace, device_unconfirmed, device_scoped
404 Resource not found (also used for codes and invites that are unknown, expired or used, so they can't be told apart)
405 Method not offered (GET /mcp)
409 Conflict (a pairing code claimed twice at once, a box not running, a run in progress, nothing to renew)
410 Gone (revoked device, already-claimed pairing code, spent chat invite)
413 Body, file or batch too large; storage quota full
415 Unsupported file or content type
422 The upstream provider refused the request itself (image generation)
429 Rate-limited (per IP for public routes, per account or device otherwise), or workspace quota exhausted
500 Server error
502 An upstream (Cred, OpenAI, Anthropic, GitHub, the sandbox) failed
503 Not configured or unavailable (database, Cred, Blob, signing keys)

Versioning

/v1/... is the stable surface the native clients pin against. Breaking changes get /v2/...; additions to existing routes (new optional response fields, new optional request fields) ship on the existing version.

Everything else — /admin, /account, /academy, /assistant, /auth, /contact, /credits, /cron, /investors, /learn, /licence, /mcp, /newsletter, /oauth, /waitlist, /webhooks, /workspace — is not versioned: browser-side or internal surfaces, or (/mcp, /oauth) shaped by an external protocol.

Source pointers

  • Routes — site/app/api/; /mcp is site/app/mcp/route.ts, re-exporting /api/mcp
  • Auth helpers — site/auth.ts, site/lib/api-auth.ts, site/lib/api-route.ts, site/lib/admin.ts, site/lib/device-access.ts, site/lib/mcp-oauth.ts
  • Schemas — site/db/schema.ts
  • Pairing flow — site/app/pair/ and site/lib/pairing.ts
  • Managed inference — site/lib/managed-inference-handler.ts
  • Desktop counterpart — Remote control and the macos/Sources/Features/Remote/ directory