billing
ChatGPTShow your box plan, the credits left in your box wallet, when the paid period ends (0 without one), which boxes the plan includes (their machine time is free; other boxes pay from credits), a downgrade waiting for the period end if any, and the link to upgrade or top up. Hand the person billing_url when they run out of credits or want a bigger plan. Paid plans are coming soon: until then every box is free, plan is free and billing_url is empty.
box_approval_answer
ChatGPTFor the box screen view only: answers one approval with the token box_approval_token minted for the person's click.
box_approval_token
ChatGPTFor the box screen view only: turns the person's click on one of their pending approvals into a token, valid for a minute, that box_approval_answer takes. The token is in the result's _meta only.
box_approvals
ChatGPTFor the box screen view only: lists the connector calls of your boxes' agents that wait for your approval, oldest first.
box_create
ChatGPTCreate another box with this name and wait until it is running. Your other boxes stay as they are; only a limited number may run at once.
box_delete
ChatGPTDelete one of your boxes with its saved state and snapshots. Requires the box and confirm: true.
box_ensure
ChatGPTStart or wake your box and wait until it is running. Waking takes a few seconds; creating a new box takes longer.
box_hibernate
ChatGPTHibernate your box. Running programs and memory are kept and come back on the next wake. A box waiting in line for a machine leaves the line.
box_list
ChatGPTList your boxes with their names, states and images. For a connected client, client counts the boxes the user assigned to it and those it created, and max_boxes is how many it may create; with max_boxes 0 it may use only the assigned ones. view_url opens the box's screen for the person; hand it to them when a step needs them, such as a sign-in, 2FA, a captcha or a payment, and wait until they say they are done.
box_restore_paths
ChatGPTCopy files or folders from a snapshot into a new folder ~/Restored/<save time> in the running box; nothing else changes. Paths are under ~ or /workspace.
box_save
ChatGPTSave your files, logins and agent history from the box to storage now. On a desktop box the browser closes during the save.
box_snapshots
ChatGPTList the kept snapshots of your box's files, newest first, with when each was saved. The box may be hibernated.
box_status
ChatGPTShow the state of your box: running or hibernated, its image, whether an upgrade is available, and when your files were last saved. view_url opens the box's screen for the person; hand it to them when a step needs them, such as a sign-in, 2FA, a captcha or a payment, and wait until they say they are done.
box_upgrade
ChatGPTMove your box to the latest image of its kind. Running programs restart; files, logins and agent history are kept. Requires confirm: true.
box_view
ChatGPTShow the live screen of your box, waking it: a client that renders MCP Apps shows it in the chat, view only, with a button that opens view_url, where the person can type; elsewhere hand the person view_url. Use it when the person wants to watch, or a step needs them, such as a sign-in, 2FA, a captcha or a payment. Call it once per conversation; the view stays live. Other tools act on the box without calling this again.
box_view_token
ChatGPTFor the box screen view only: mints an hour's view-only token for the running box and names the socket that takes it.
box_wake
ChatGPTWake your box, the same as box_ensure: start or wake it and wait until it is running.
browser_click
ChatGPTClick the element with the given ref from the latest snapshot. When the click opens a page or changes the address, returns the new page's snapshot.
browser_fetch
ChatGPTRead a web page without showing it: the box's Chrome loads the URL in a hidden tab with the user's cookies and sign-ins, waits for the page to load and its network to settle (at most 15 s, then returns what has loaded), and returns the page title, final URL and visible text, up to 20000 characters, then closes the tab. The user's windows and tabs are untouched. Prefer it to browser_navigate plus browser_read for looking something up. For reading only: to sign in, click, fill a form, or show the user a page, use browser_navigate.
browser_fill
ChatGPTFill a web form in one call: types each field's text by ref from the latest snapshot (a select takes an option's label or value), then, with click, clicks that ref, such as the submit button, waits for the page it opens, and returns that page's snapshot. For a form filled once per row, call it once per row.
browser_navigate
ChatGPTOpen a URL in the box's Chrome and return the page snapshot: headings, text and interactive elements tagged [ref=eN]. It works in your own Chrome window; to act on a page the user already has open, pass tab.
browser_read
ChatGPTReturn the visible text of the page, or of one element by ref, up to 20000 characters from offset; a longer text ends with the offset to pass for the rest.
browser_snapshot
ChatGPTReturn the current page as a ref-tagged element list. Refs from older snapshots become invalid.
browser_tabs
ChatGPTList the tabs the user has open in the box's Chrome, outside your own window: id, title, URL and which ones are in front. To act on one, such as a page a task refers to that is already open, pass its id, or "active" for the tab in front, as tab to browser_navigate, browser_snapshot, browser_click, browser_type or browser_read. Without tab those tools work in your own window and leave the user's tabs alone.
browser_type
ChatGPTFocus the element with the given ref and type text into it. On a select (a combobox with options in the snapshot), text picks the option with that label or value.
computer_act
ChatGPTOn this box, desktop-app GUI work (menus, dialogs, settings, Save As) goes to one gui_plan call with the whole plan, and loops over many items to one script_run script, instead of a chain of computer_act calls. Perform one input action, then return a fresh screenshot. Target an element by index from the latest computer_state, or x,y in the pixels of your latest screenshot. For a few steps you can already place, such as opening a menu and picking its item, pass actions in place of action: a list of such actions, run in order with one screenshot at the end; it stops at the first failure. Each action already waits for a still screen, so do not add wait.
computer_state
ChatGPTScreenshot of the whole screen, scaled to a long edge of 1024 pixels unless max_edge says otherwise, the visible windows (pid, window_id), and the accessibility elements [index] of the frontmost window or of the given pid.
desk
ChatGPTOne desktop call in plain JSON on the accessibility tree: op windows; snapshot {window?, text?}; find {name, role?, window?}; read {id, text?}; press {id} (selects, opens menus, clicks or runs the element's action); act {id, action: click|action|select|focus}; at {x, y, window?}; key {keys: "ctrl+shift+s"}; type {text}; click {x, y, button?, count?}; focus {window}; close {window}; launch {app}; shot {x?, y?, w?, h?}; screen. Element ids come from snapshot or find; window is title text, default the focused window. x, y, w, h and bounds are screen pixels, unlike computer_act's screenshot pixels. For GUI work of several steps use gui_plan.
edit_file
ChatGPTReplace an exact string in a file. old_string must match exactly once unless replace_all is true.
gui_plan
ChatGPTRun a desktop-app GUI plan in ONE call: the box runs each step on the accessibility tree (0.1-0.5 s), checks it, and stops at the first surprise. Use it for GUI work in desktop apps (menus, toggles, dialogs, Preferences, Save As, settings). Write the whole plan at once, without looking first. One op per step; optional window: title text of the window the step acts in (waited for): {app: "mousepad"} focus or launch; {menu: "Edit > Preferences"} (an approximate path is fine); {menu: "Document > Word Wrap", on: true} set a menu toggle (read first, never toggled twice); {click: "Save"}; {check: "Show line numbers", on: false} a check box or switch; {set: "font size", value: "14"} a text, spin or combo field; {type: "text"}; {key: "ctrl+s"}; {wait: "Save As"} a window title; {verify: "Name", value: "x"} (or on, enabled); {close: true} close the focused dialog. Returns {ok: true, trace} or {ok: false, escalate: {step, reason, window, outline}}. Trust ok: true: each step was verified, so add no checks or screenshots, except for the steps in caveats: read their effect first. On escalate, handle the reason, then call again with only the remaining steps. Close the dialogs you open. A path for a file dialog may end in \n to submit it. Name targets by their visible label. A passing plan that starts with an app step is saved as a flow: name it with save: "app-action" and write values a later request changes as {{name}} with params: {name: value}. To save a plan that already ran, or the steps that passed before an escalation, call {save: "app-action"} alone: it does not run them again. Replay a flow with {flow: "name", params: {...}}: one call, no model. Check saved flows with {flows: true} before planning a task you may have done before. screenshot: true adds a screenshot (default: only on escalate).
list_dir
ChatGPTList a directory (default /workspace).
read_file
ChatGPTRead a text file with line numbers. Relative paths resolve under /workspace. A line over 2000 characters is cut, with a marker that gives its length.
screenshot
ChatGPTLook at the desktop: a read-only screenshot of the whole 1280x800 screen, scaled to 1024x640 unless max_edge says otherwise; the result gives its size and input tokens. To look again, prefer a desk snapshot (text, no image) or a region at full resolution to another full screenshot.
script_run
ChatGPTRun one script for desktop work a single gui_plan cannot hold: loops over many items, data between apps, logic. A script is a JavaScript or TypeScript ES module run by Node 24 that drives the desktop through the desk API (import * as desk from '/opt/desk/lib/desk.mts': windows, accessibility snapshots with checked states, find and press elements, keys, typing, clicks, screen crops, gw model calls); the desk command does the same from shell. Read /opt/desk/AGENTS.md first (also the resource cocoonbox://desk/AGENTS.md). Pass code, or script: a file in the box. A module that exports main(params) is called with params and its return value comes back as result. Nothing persists between runs. Returns JSON {result, logs, error?: {kind, message}, duration_ms, exit_code, stderr, snapshot?, screenshot_path} and a screenshot taken after the run.
shell
ChatGPTRun a bash command in the agent's persistent shell session (cwd /workspace). Returns merged stdout/stderr and the exit status; a non-zero status or a timeout is an error result. Output over ~30 KB keeps only its head and tail. Keep each command's wait well under the time left; save the required output early and improve it after.
usage
ChatGPTShow the model usage gw metered for your account, all your boxes together: requests, tokens and cost in micro-dollars today and this month (UTC), by model, with your daily cost cap (-1 unlimited) and what is left of it today. Your own model client's tokens are not in it.
write_file
ChatGPTCreate or replace a file with the given content; parent directories are created.