All pages
Developers
Build on TRMNLY
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/mcpRead 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 tellRead 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.
| Domain | Tools | Write | Read | Share |
|---|---|---|---|---|
| Browser | 144 | 76 | 68 | |
| Terminal & panes | 56 | 22 | 34 | |
| Knowledge & collaboration | 47 | 10 | 37 | |
| OS & desktop | 34 | 19 | 15 | |
| Automation & workflows | 26 | 18 | 8 | |
| Filesystem & search | 13 | 5 | 8 | |
| Docker & containers | 13 | 8 | 5 | |
| Orchestration | 13 | 8 | 5 | |
| Git & GitHub | 12 | 3 | 9 | |
| Safety & policy | 12 | 6 | 6 | |
| Code intelligence | 10 | 3 | 7 | |
| Ports | 10 | 5 | 5 | |
| Projects & worktrees | 9 | 6 | 3 | |
| Build, test & jobs | 7 | 4 | 3 | |
| Terminal intelligence | 6 | 1 | 5 | |
| Remote & connections | 6 | 4 | 2 | |
| Web & network | 2 | 0 | 2 |
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 with403 { 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 with403 { 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,pingandtools/listare answered at the edge without starting the box; notifications get202with no body; control-plane tools (workspace_start,workspace_status, …) and sharedchat_*calls are served from the database. Any othertools/callstarts the box if needed and is proxied once, never retried. Unknown methods are a JSON-RPCmethodNotFound.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
400for the whole batch. - One event whose
propertiesare over 4096 bytes answers413for the whole batch. Truncate on the client before sending. - More than 100 events answers
413. Split the batch. 401means 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/;/mcpissite/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/andsite/lib/pairing.ts - Managed inference —
site/lib/managed-inference-handler.ts - Desktop counterpart — Remote control and the
macos/Sources/Features/Remote/directory