Build with Port42 and your AI companions.

Start microphone capture. Streams audio.transcription events (and audio.data when rawAudio is set) to the calling port until audio.stopCapture.

Play base64-encoded audio data (WAV, MP3, AAC).

Speak text aloud using text-to-speech

• rate number Speech rate 0.1-1.0 (default 0.5)
• text string, required Text to speak

Stop any active speech synthesis or audio playback.

Stop the microphone capture and release the audio engine.

Execute AppleScript code and return the result. Use this to control other applications on macOS.

• source string, required AppleScript source code
• timeout integer Timeout in seconds (default: 30, max: 120)

Execute JavaScript for Automation (JXA) code and return the result. Use this to control other applications on macOS.

• source string, required JXA source code
• timeout integer Timeout in seconds (default: 30, max: 120)

Take a screenshot of an open browser session. Returns base64 PNG.

• sessionId string, required Browser session ID from browser_open

Close a browser session

• sessionId string, required Browser session ID to close

Run JavaScript in an open browser session and return the result.

Read the HTML of an open browser session, optionally scoped to a CSS selector.

• options object { selector } to scope the read.
• selector string CSS selector to read from (default: the whole page).
• sessionId string, required The browser session.

Navigate an open browser session to a new URL.

Open a URL in a headless browser and return the page title. Use browser_text to read page content after opening.

• url string, required The URL to open (http or https)

Extract text content from an open browser session

• selector string CSS selector to extract from (default: body)
• sessionId string, required Browser session ID from browser_open

Capture a photo from the device camera. Returns a base64 PNG image.

Stop the camera stream and release the capture session.

Start continuous camera streaming. Pushes camera.frame events to the calling port until camera.stopStream.

Post to a port's chat. Every port has one: pass port 0 for the desktop, a space id, or a port's id. The entry is attributed to you, the caller, and every subscriber of the port gets a `chat` event carrying it.

• port string, required Whose chat: `0` (the desktop), a space id, or a port id / udid / title.
• text string, required What to say.

Read a port's chat, oldest first. Pass `after` (a seq you have seen) to get only what is newer. Returns { entries, last, agents? }. Each entry's `from` is {id, name, kind, handle, computer?}: `name` as people read it, which on a port shared with another computer carries the author's computer, `scribe (gordon's Port42)`; `handle` is the bare name, to match on and @mention; `computer` is set when the chat shows one. `last` is the newest seq in the chat (0 when empty), and `agents`, on a port shared with another computer, names this computer's agents on it as the chat shows them, whether or not they have posted.

• after integer Only entries with a seq greater than this.
• limit integer At most this many, the newest ones (default 50, max 200).
• port string, required Whose chat: `0` (the desktop), a space id, or a port id / udid / title.

Read the current clipboard contents. Returns text or base64 image data.

Write text to the system clipboard

• data string, required The text to copy to clipboard

Make a companion, as the new-companion card does: an agent CLI (claude or codex) in a terminal port, or a custom command run headless. runs: "port" (default, on the desktop) or "running" (off the desktop, a card under Running in the rail; reach it through its chat). It joins the space and hears @mentions there; pass `port` to have it watch that port instead, woken by `kinds` (default ["port"], the port's own events) and replying in its chat. Needs the terminal permission, since it starts one.

• agent string The CLI (default claude).
• args array Arguments for the CLI or command.
• command string agent custom: the command to run.
• cwd string Working directory (default: the space's).
• kinds array With `port`: event kinds that wake it.
• name string, required Its name; @mention it by this.
• port string A port to watch instead of listening to the space.
• prompt string Its system prompt.
• runs string Where its terminal runs: port (a tile on the desktop, the default) or running (off the desktop, a card under Running in the rail; hidden is the older name).
• space_id string The space (default: yours, else the current one).

Delete a companion for good: it leaves every space, its watches go, the ports it made and its terminals close, and its tokens are revoked. Cannot be undone; use companions.remove to take it off one space's roster instead. The person may delete any; anyone else asks the person, naming the companion, every time, and a yes is never kept. companion is its id or name.

• companion string, required The companion's id or name.

Get details about a specific companion by ID, with `spaces`, the spaces it is a member of ([{id, name}]): the spaces whose chats and ports it can read.

• id string, required The companion's ID

List the companions in a space with their names, models, and trigger modes. Defaults to YOUR space, the companions you share this space with, because a companion acts within its space, not the whole instance. Pass space_id to target a different space, or space_id:"*" for the full global roster across every space in the Port42 instance (rarely what you want). From another computer: the companions of the shared port's own space, named by `port`.

• port string From another computer: the shared port whose space to list.
• space_id string Omit for your own space (the default). A space id targets that space. "*" returns the whole-instance roster.

Take a companion off a space's roster, as its card's "Remove from this space" does. It stops hearing @mentions there; the companion itself, its ports and its files are kept, and it can be added back. companion is its id or name; space_id defaults to your space. Removing a companion that is not on the roster is not_found.

• companion string, required The companion's id or name.
• space_id string The space whose roster it leaves (default: your space).

Stop watching a port. Call it as the watcher, or pass `companion`.

• companion string Whose watch, by name or id (default: you).
• port string, required The watched port (id, udid or title).

Change a companion's settings, as its settings box does: name, system prompt, model, where it runs (port or running), command and args, working directory, and trigger (mentionOnly or allMessages). Pass only what changes. A companion changes itself freely; anyone else asks the person, naming the companion and what changes, every time. Its secrets are not changeable here. A new prompt, command or folder reaches a running session when it next starts; a new name takes effect at once. companion is its id or name.

• args array Arguments for the CLI or command.
• command string agent custom: the command to run.
• companion string, required The companion's id or name.
• cwd string Working directory.
• model string Its model, where the CLI takes one.
• name string A new name. Two companions cannot share one.
• prompt string Its system prompt.
• runs string Where its terminal runs.
• trigger string What wakes it in a chat.

Watch a port: an event on it of a kind you name wakes you for a turn, and your reply is posted in that port's chat. Default kinds: ["port"], the port's own published events (port.publish). Others: "console" (a log line or error), "state" (an edit), "chat" (every post in its chat), or one exact kind such as "port.alert". Events that arrive while you are in a turn are held and given to you together when it ends. Watching again changes the watch and resumes it if it paused (a watch pauses after 60 wakes in an hour, and says so in the port's chat). Call it as the companion that should wake, or pass `companion` to set a watch for another.

• companion string Whose watch, by name or id (default: you).
• every integer The least time between two wakes, in seconds (default: none).
• kinds array Event kinds that wake you (default ["port"]).
• port string, required The port to watch (id, udid or title).

List watches: yours, another companion's (`companion`), or every one (`companion`: "*"). Each is {companion, port, title, kinds, every, paused}.

• companion string A name or id, or "*" for all (default: you).

List the contents of a directory in the Port42 data directory. Relative paths only (e.g. "scopes/strategy" or "scopes/strategy/decisions"). Returns a sorted list of filenames.

• path string, required Relative path to the directory (e.g. "scopes/strategy")

Create a directory (and any missing parent directories) in the Port42 data directory. Relative paths only (e.g. "scopes/strategy/decisions").

• path string, required Relative path to create (e.g. "scopes/strategy/decisions")

Open the native file picker. The chosen paths become readable and writable for the calling principal via fs.read / fs.write, with no further permission.

Read a file. Use a relative path (e.g. "scopes/strategy/scope.md") to read from the Port42 data directory without a file picker. Use an absolute path for picker-approved files.

• encoding string utf8 (default) or base64
• path string, required Relative path within Port42 data directory (e.g. "scopes/strategy/scope.md") or absolute path for picker-approved files.

Write a file. Use a relative path (e.g. "scopes/strategy/facts.md") to write to the Port42 data directory, parent directories are created automatically. Use an absolute path for picker-approved files.

• data string, required Content to write
• encoding string utf8 (default) or base64
• path string, required Relative path within Port42 data directory (e.g. "scopes/strategy/facts.md") or absolute path for picker-approved files.

Set the version budget of the imagine team in a space, for example to let it keep going after the budget is spent. The team's writes to its port past the budget are refused with budget_spent; a budget of 0 has no limit. The same as typing /imagine --versions N in that space's chat.

• space string, required The space the team was imagined in.
• versions integer The new budget, in versions of the port: any number, or 0 (or leave it out) for no limit.

Start an imagine team: from one line, a new space with its port (a placeholder until v1) and a lead and two engineers (their terminals on its desktop) who build that port, in at most `versions` versions (default 10; 0 is no limit), until the lead posts DONE. Returns the space, the port, the team's names, the port title and the budget. The same as ⌘I or typing /imagine in a chat.

• line string, required What to make, in the person's words.
• versions integer The version budget (default 10; no upper limit; 0 is no limit at all).

Accept an invite someone sent you: this instance joins their port, which opens here as a tile. Returns { address, title, rights, tile }. Then call methods on the port by its address or the tile's id. remoteWake (default true): a mention of one of your companions in that port's chat wakes it here, on your model; the tile's chrome can turn it off later. companions: names of your companions to bring onto the tile; only companions brought onto it act on it, and each is told what it is.

• code string The six-digit code, if the invite needs one.
• companions array Your companions to bring onto the tile (by name).
• link string, required The invite link (https://tele.port42.ai/#…).
• remoteWake boolean Let their chat wake your companions for this port (default true).

Make an invite link that lets one person on another computer open ONE port: in Port42 if they have it, otherwise in their browser. The link lets in two computers (say their browser, then their Port42) and is then used up. Returns { link, code?, id, expires, discloses }. rights: any of see, use, edit, wake_agents, fork (default see, use and wake_agents: remote wake, their companions may wake yours in this port's chat; fork lets them take a copy, which Port42 offers only when given; move hands the port over to whoever opens the link, once, and closes it here, asked every time). requireCode: a six-digit code they must type, sent to them another way. `discloses` lists what the port itself can do on this computer; whoever you let in can make it do so. Port 0 and spaces cannot be shared.

• expiresIn integer Seconds until the link stops working (default 7 days, at most 30).
• port string, required The port to share (id / udid / title).
• requireCode boolean Require a six-digit code, to send another way.
• rights array see, use, edit, wake_agents, fork, move. Default see, use and wake_agents.

The invites this instance has made: id, port, rights, expiry, whether a code is required, and whether each is open, used, expired or withdrawn. A link lets in two computers (a move, one), so it stays open after the first: usedBy names the first and usedAgainBy the second, when it has let them in.

Withdraw an invite that has not been used. To remove someone who already joined, remove them in Settings → Access.

• id string, required

Change what one person a port is shared with may do: rights is the full set wanted, of use, edit, wake_agents, fork (see always stays; to remove someone use invite_stop). Taking rights away needs no card. Adding any asks the person first, every time for edit, as sharing does. Returns the rights now held.

• peer string, required The person's peer key or name (from invite_shared).
• port string, required The port (id / udid / title).
• rights array, required The full set wanted: use, edit, wake_agents, fork.

Who a port is shared with now: each person's peer key, name and rights. A person who joined through an invite; invite_list shows the links.

• port string, required The port (id / udid / title).

Stop sharing a port with one person: their access goes, and the links they came in on are withdrawn. The port stays shared with anyone else. Taking access away needs no card.

• peer string, required The person's peer key or name (from invite_shared).
• port string, required The port (id / udid / title).

Send a macOS system notification

• body string, required Notification body text
• title string, required Notification title

Do one step in a web or browser port, as the person would, after port_look. action: click (element n from your last look, or a point x,y in page pixels), type (text into element n, clicking it first, or into what has focus), key (a key: enter, tab, escape, up, down, left, right, pageup, pagedown, home, end, backspace, space, or one character as a site's shortcut, with modifiers as cmd+k, shift+tab), scroll (dy page pixels, down is positive, over element n or the page), navigate (url), back, forward. Delivered as real input, so the page treats it as a person's. Returns url, title and navigated, and a new token; look again before the next step. Refused as stale_write if the person touched the port since your look.

• action string, required
• dy number scroll: pixels, down is positive
• id string, required The port's UDID (from ports_list)
• key string key: the key, with any modifiers joined by + (cmd+enter)
• n integer An element number from your last port_look
• text string type: the text to enter
• token string, required REQUIRED. The port's token from your last look or act.
• url string navigate: the address
• x number click: page x in pixels, when not naming an element
• y number click: page y in pixels, when not naming an element

Close the calling port.

Check a port for problems. level=count returns only how many errors and warnings it has logged, no text: the cheap check that a port you built works. The default (problems) adds the errors and warnings themselves (the most recent 20), to deal with them. level=all reads everything it printed, for debugging. A terminal's output has no levels, so for a terminal the default is its last 50 lines. `omitted` says how many lines were left out.

• id string, required The port's UDID (from ports_list), or a terminal's name.
• level string count: the numbers only. problems (default for a web port): errors and warnings. all: every line, for debugging.
• tail integer How many recent lines to return (default 20 for problems, 50 for all).

Create a port and return its id. The uniform way to make any port. type:"web" needs html (a full port HTML body) and renders inline in chat. type:"terminal" needs command and opens a native terminal (runs in /bin/zsh; the command is typed in, claude/gemini get the Port42 hooks). type:"browser" needs url and opens an embedded browser tile with an address bar that follows links. type:"chat" reveals that space's chat port (idempotent, one chat per space; brings it back if parked, popped out or closed, and a DM is a space, so pass its space_id to open that conversation). For terminals you may also pass args, cwd, systemPrompt (companion personality), env, and initialInput (a line left waiting, unsent, in the CLI's input box). Drive the result with port_push (input to terminals, data to web ports) and list with ports_list. Pass space_id to target a space (default: current).

• args array type:"terminal", arguments for the command.
• command string type:"terminal", executable/CLI to run (e.g. "bash", "htop", "claude").
• cwd string type:"terminal", working directory (default: home).
• env object type:"terminal", custom environment variables for the shell.
• html string type:"web", full port HTML body (include a <title> and <meta name="version">).
• initialInput string type:"terminal", a line typed into the CLI once it is up but NOT submitted: it waits in the input box for the user to press Enter. For handing someone a first prompt to run. Use port_push instead to actually send input.
• presentation string Where the port appears: "tiled" (default, a desktop tile), "running" (off the desktop at full speed, a card under Running in the rail: a background job, a pipe stage, or an agent nobody needs to watch) or "paused" (off the desktop, slowed, listed under Paused). Show it with port.manage show. "hidden" and "parked" are the older names.
• space_id string Space to create the port in (default: current space).
• systemPrompt string type:"terminal", companion personality/role appended to the CLI's system prompt.
• title string Port title (default: derived from html <title>, or the command).
• type string, required The port type to create.
• url string type:"browser", the page to open (e.g. "https://example.com").

Delete a CLOSED port for good: its record, versions and chat. Close it first (port.manage close); an open port is refused, so nothing live is ever deleted in one step.

• id string, required The closed port's id.

Execute JavaScript on a live port. Use this to call functions, push data, or update state on an existing port without replacing its HTML. The JS runs in the port's webview context with access to window, document, and any globals the port defines.

• id string, required The port's UDID (from ports_list)
• js string, required JavaScript code to execute in the port's context. Return a value to get it back in the response, as {value, token}. A bare expression yields its value (multi-line is fine). A multi-statement body needs an explicit return: `foo(); 42` is a syntax error, `foo(); return 42;` works.
• token string, required REQUIRED. The port's `token`, as it was when you composed this write, from ports_list, port_create, or whatever your last write returned. Without it the write is refused with 'token_required'; if the port has changed since, with 'stale_write'. Both carry the current token, so retry once with that instead of clobbering whoever moved it.

Fork a web port: an independent copy with no grants of its own, titled '<title> (copy)', as the tile menu's Fork does. It lands in space_id, else the current space. A port someone shared is copied only when they allowed it. Returns {id}.

• id string, required The port to copy (from ports_list).
• space_id string The space for the copy (default: the current space).

Read a WEB or BROWSER port's LIVE DOM, what is on screen right now, including everything its JS has changed since load. Use this, not port_get_html, when you need current state: port_get_html returns the stored SOURCE, which does not reflect any port_exec or port_push that has run since. Returns {html, token}; pass that token as 'token' on your next write and it will be refused rather than clobber someone if the port moved in between.

• id string, required The port's UDID (from ports_list)
• selector string Optional CSS selector to read just one subtree. Omit for the whole document.

Read the HTML of a port. Omit 'version' to get the current HTML. Pass 'version' (from port_history) to read a specific historical snapshot.

• id string, required The port's UDID (from ports_list)
• version integer Optional version number (from port_history). Omit for current HTML.

List all saved versions of a port by its UDID. Returns version number, createdBy, and createdAt for each snapshot. Use port_get_html with a version number to read a specific snapshot, or port_restore to roll back.

• id string, required The port's UDID (from ports_list)

Return the calling port's own id, title, space, capabilities, and activity token.

See a web or browser port as the person sees it, to act on it with port_act. Returns image (the path of a PNG of the visible page with every actionable element outlined and numbered: read it with your image tool), elements ([{n, role, label, box:[x,y,w,h]}] in page pixels; a field also has type and value, never a password's value), text (the visible page's text), url, title and token. Look again after every act: the numbers are this look's. A browser port asks the person once per site before a companion may look at or act on it. The port must be on the desktop.

• id string, required The port's UDID (from ports_list)

Manage a port. Actions: focus (raise to the front of the desktop), close (archive it: it can be reopened with port.reopen), hide (off the desktop, still running at full speed, with its chat and subscriptions, shown as a card under Running in the rail), pause (off the desktop, slowed, listed under Paused in the rail; a terminal keeps running), show (bring a running or paused port back onto its desktop), pin (keep it above the other ports in its space), pinEverywhere (show it in every space, above the other ports, at one position), unpin, showIn (show it in another space too, as the port menu's Spaces… row does: pass space_id; the port stays where it lives and is live in both), hideFrom (stop showing it in space_id), reload (the tile menu's refresh: a web port's page loads again in place), background (make it the live backdrop behind a space's desktop, as Set as background in the port menu does: pass space_id for which space, else the current one; each space has its own, and a port is the backdrop of one space at a time), unbackground (that space goes back to the ambient backdrop and the port returns to a tile). ports_list reports where it is also shown as alsoIn. Check the status field from ports_list: 'tiled' | 'running' | 'paused'.

• action string, required One of: focus, close, hide, pause, show, pin, pinEverywhere, unpin, showIn, hideFrom, reload, background, unbackground (minimize and dock are older names for hide; park for pause; restore and undock for show)
• id string, required The port's UDID or title
• space_id string showIn and hideFrom: the other space. background and unbackground: which space's backdrop.
• token string, required REQUIRED. The port's `token`, as it was when you composed this write, from ports_list, port_create, or whatever your last write returned. Without it the write is refused with 'token_required'; if the port has changed since, with 'stale_write'. Both carry the current token, so retry once with that instead of clobbering whoever moved it.

Move a port's tile to desktop coordinates, resize it, or both. Pass x and y together to move, width and/or height to resize (a missing one keeps its current value; the smallest a tile can be is 150 by 110). Use screen_info to get display bounds first. A resize is the tile's own size, the same on every desktop it is shown on.

• height number New height in points.
• id string, required The port's UDID (from ports_list)
• space_id string Which desktop to move it on. A port kept from another space is a tile on BOTH, with a position on each. Defaults to the current space when the port is on it, else the port's home space.
• token string, required REQUIRED. The port's `token`, as it was when you composed this write, from ports_list, port_create, or whatever your last write returned. Without it the write is refused with 'token_required'; if the port has changed since, with 'stale_write'. Both carry the current token, so retry once with that instead of clobbering whoever moved it.
• width number New width in points.
• x number Horizontal position in desktop points (with y)
• y number Vertical position in desktop points (with x)

Make a targeted edit to a port's HTML, replace an exact string with new content. Much safer than port_update for small changes because only the specified text is replaced; everything else is preserved exactly. Use port_get_html first to read the current HTML, find the exact string to replace, then call port_patch. Errors if 'search' is not found in the current HTML, so the port is never silently mangled. Snapshots the result the same as port_update, and reaches the page the same way (reloading only when it has to; see port_update).

• id string, required The port's UDID (from ports_list)
• replace string, required The string to replace it with.
• search string, required The exact string to find in the current HTML. Must match exactly, copy it from port_get_html output.
• token string, required REQUIRED. The port's `token`, as it was when you composed this write, from ports_list, port_create, or whatever your last write returned. Without it the write is refused with 'token_required'; if the port has changed since, with 'stale_write'. Both carry the current token, so retry once with that instead of clobbering whoever moved it.

Return a port's position and size on one desktop (a kept port has a position per desktop).

A port emits its OWN state or event on its own Notify topic, for consumers watching via port_subscribe. This is a port broadcasting AS itself, distinct from port_push, which is input sent INTO a port. Only meaningful from inside a port; the topic is the calling port's own id, so there is no target argument. Use this instead of having a consumer reach in with port_exec to read state: the port publishes, consumers subscribe.

• kind string, required Event kind, e.g. 'state', 'progress', 'error'. Namespaced on the way out: you publish 'state', subscribers see 'port.state', so a port cannot emit a system event like 'driver' or 'browser.load'.

Send input to a port, one verb, dispatched by the port's type. A WEB port receives the data as a 'port42:data' CustomEvent with the payload in event.detail. A TERMINAL port receives the data as raw keystrokes typed into the shell: end with a newline (e.g. "ls\n") to run the command, or omit it to leave the line waiting unsubmitted. Use the id from ports_list. Prefer this over port_exec for data transfer.

• data required For web ports: any JSON value (object/array/string/number) delivered as event.detail. For terminal ports: a string of raw keystrokes (include \n to execute). Required, omitting it is refused with missing_arg rather than sent as nothing, and a terminal refuses an explicit null because there is no keystroke for null.
• id string, required The port's UDID (from ports_list), or a terminal's name.
• token string, required REQUIRED. The port's `token`, as it was when you composed this write, from ports_list, port_create, or whatever your last write returned. Without it the write is refused with 'token_required'; if the port has changed since, with 'stale_write'. Both carry the current token, so retry once with that instead of clobbering whoever moved it.

Rename a port. Sets the port's display title (shown in the title bar). Works for tiled, parked, docked, and inline ports. Use the port's id from ports_list.

• id string, required The port's UDID (from ports_list)
• title string, required The new title for the port
• token string, required REQUIRED. The port's `token`, as it was when you composed this write, from ports_list, port_create, or whatever your last write returned. Without it the write is refused with 'token_required'; if the port has changed since, with 'stale_write'. Both carry the current token, so retry once with that instead of clobbering whoever moved it.

Reopen a closed port with its id, content, position and chat. A terminal relaunches its command in its last working directory. Closed ports are listed by ports_list with include_closed.

• id string, required The closed port's id.

Restore a port to a specific earlier version. The port's live HTML is replaced with the snapshot and a new version entry is recorded. Use port_history to find available version numbers.

• id string, required The port's UDID (from ports_list)
• token string, required REQUIRED. The port's `token`, as it was when you composed this write, from ports_list, port_create, or whatever your last write returned. Without it the write is refused with 'token_required'; if the port has changed since, with 'stale_write'. Both carry the current token, so retry once with that instead of clobbering whoever moved it.
• version integer, required The version number to restore to (from port_history)

Set the calling port's own capabilities list.

Set the calling port's own title.

Subscribe to a port's live event stream. Yields Notify events { topic, kind, payload, token } as the port emits them (e.g. terminal.output), after a first `subscribed` event that says the stream is live: read anything you need to catch up on then. `token` is the port's state token AT THAT MOMENT, so you can write next without re-reading the port first. OVER THE GATEWAY THIS IS WEBSOCKET-ONLY: connect to /ws and send it as a `call` envelope, and events arrive as `stream` frames on the same call_id. On HTTP /call it is refused with `unsupported`, because the stream never ends and a request/response call could only hang. The stream stays open until cancelled.

• id string, required The port to observe (id / udid / title).

Update an existing port's HTML content. The port can be identified by its UDID or title. Works whether the port is windowed or minimized. The page is reloaded only when it has to be: a change confined to <style> is applied in place, and any other change is first offered to the page as a cancelable 'port42:update' event (detail.html is the new HTML), which the page may apply itself by calling preventDefault(), keeping its state. Returns applied: unchanged, styles, handledByPage or reloaded.

• html string, required The new HTML content for the port (full HTML, not a diff)
• id string, required The port's UDID or title to identify which port to update
• token string, required REQUIRED. The port's `token`, as it was when you composed this write, from ports_list, port_create, or whatever your last write returned. Without it the write is refused with 'token_required'; if the port has changed since, with 'stale_write'. Both carry the current token, so retry once with that instead of clobbering whoever moved it.

List active ports. Each port has an id (UDID), title, capabilities array, status, spaceId, createdBy (an id) with createdByName (who that is, for display), and cwd (if it has a terminal). Terminal ports also report surfaceBound. Use capabilities: ["terminal"] to filter to terminal ports; pass space_id to list only that space's ports. Use the id field with port_push for reliable routing (raw keystrokes to terminals, data to web ports). Always show the id and capabilities fields when presenting results, they are required for follow-up tool calls.

• capabilities array Filter to ports that have all of these capabilities. Examples: "terminal", "claude-code", "browser". Omit to list all ports.
• include_closed boolean Also list closed (archived) ports, with status 'closed'. Reopen one with port.reopen.
• space_id string List only this space's ports. Omit to list every space you can see (a port or companion sees only its own space).

Who is on a chat's messages right now: each companion that has a message from this chat (`received`), is working on it (`working`), or is waiting for the person (`waiting`, with `why` when it said). `doing` says what it is doing right now ("editing ShellView.swift", "running swift test") when its CLI reports tools (Claude Code does); a caller on another computer is told only the kind ("editing a file"). Returns { presence: [{name, handle, computer?, state, since, why?, doing?}] }, `handle` the bare name and `name` as the chat shows it, empty when nobody is. Subscribe to the port for the `presence` event to hear each change; the event carries only the kind of what each is doing.

• port string, required Whose chat: a space id, or a port id / udid / title.

Leave a port someone shared with you: its tile closes here and this instance forgets it. The host's grant is theirs to remove; a new invite brings it back. Anyone but the person is asked first, every time.

• tile string, required The tile's id (from ports_list: a port with a mirrors entry).

Whether a mention in the host's chat of a port shared with you may wake your own companions here. Turning it on by anyone but the person asks first, every time; turning it off never does.

• on boolean, required true to let them wake your companions.
• tile string, required The tile's id (from ports_list).

Make an HTTP request to an external API. Use the 'secret' parameter to inject authentication from the secrets store, you never see the raw credential. Supports GET, POST, PUT, PATCH, DELETE. JSON bodies are auto-serialized. Responses with JSON content-type are auto-parsed.

• body string Request body. Objects are JSON-serialized automatically.
• headers object Additional HTTP headers as key-value pairs.
• method string HTTP method: GET, POST, PUT, PATCH, DELETE. Default: GET.
• secret string Named secret from the secrets store. The runtime injects the auth header, you never see the raw key.
• timeout integer Timeout in milliseconds. Default: 30000, max: 120000.
• url string, required Full URL to call (https recommended)

Capture a screenshot of the screen. Returns a base64 PNG image.

• scale number Image scale factor 0.1-2.0 (default 1.0)

Get display information: size, position, and visible area (excluding dock/menubar) for all connected displays. No screen recording permission required. Use this to calculate port positions before calling port_move.

Record an app surface for a fixed number of seconds and auto-stop (the convenience form). Pass options.seconds. Returns {path, width, height, seconds, fps, bytes}.

• options object Recording options: target ({window:"self"} | {window:<osId>} | {port:<udid>} | {ports:[<udid>...]} | {region:{x,y,w,h}} | {display:<id>}). window/port/ports are occlusion-proof (only that surface); region/display capture the raw display (may catch other apps). Also aspect (e.g. "16:9"), fit (cover|exact; contain is not yet supported), width, height, scale, fps, padding, cursor (bool; only on a display or region target, a window/port capture cannot include the cursor), audio (none|system|mic|both), format (mov|mp4), path, and for the convenience form seconds.

Start recording an app surface (window:self / a port / multiple ports) to a video file with optional system or mic audio. Returns {recordingId, width, height, target}. Stop with screen.record.stop.

• options object Recording options: target ({window:"self"} | {window:<osId>} | {port:<udid>} | {ports:[<udid>...]} | {region:{x,y,w,h}} | {display:<id>}). window/port/ports are occlusion-proof (only that surface); region/display capture the raw display (may catch other apps). Also aspect (e.g. "16:9"), fit (cover|exact; contain is not yet supported), width, height, scale, fps, padding, cursor (bool; only on a display or region target, a window/port capture cannot include the cursor), audio (none|system|mic|both), format (mov|mp4), path, and for the convenience form seconds.

Report whether a recording (or any recording) is active and its elapsed seconds.

• recordingId string Optional recording id; omit for the overall status

Stop a recording started with screen.record.start. Returns {path, width, height, seconds, fps, bytes}.

• recordingId string, required The id returned by screen.record.start

Stop the screen stream and release the capture stream.

Start continuous screen streaming. Pushes screen.frame events to the calling port until screen.stopStream.

List all visible windows with their titles, apps, and positions

The Claude Code and Codex sessions running on this Mac that Port42 did not start, each with its project, branch, title, last activity and the app it runs in, grouped into a space per project. What the first-run import and ⌘K 'bring in running sessions' offer.

Bring running sessions into Port42 as forks: each becomes a companion in its space whose terminal starts with a copy of the whole conversation; the original is not touched and should then be closed. Each item: {id, cli, cwd, space, name}.

• sessions array, required The sessions to bring in: {id, cli (claude|codex), cwd, space, name}.

Create a space. Returns {id, name}. The name is lowercased with spaces as dashes. Pass switch: true to also make it the current space; by default the person stays where they are.

• name string, required The space's name.
• switch boolean Also switch to it (default false).

Get a space's metadata and member list: { id, name, type, memberCount, members: [{ id, name, type, owner, qualifiedName }] }. Pass space_id to inspect a specific space (e.g. your own PORT42_SPACE_ID); omit it for the currently selected space. From another computer: the shared port's own space, named by `port`.

• port string From another computer: the shared port whose space to read.
• space_id string Optional space id to inspect. Defaults to the currently selected space.

Delete a space: its own ports and terminals close, then the space and its chat go. A port adopted into another space stays there. Cannot be undone. The same as Delete in the galaxy.

• space_id string, required The space to delete (from space_list).

List all spaces the user belongs to, with each one's accent color, whether it is resting, and its place in the galaxy order (the list is in that order).

Move a space in the galaxy order, as dragging it does: it lands just before the space named in before, or at the end when before is omitted. Returns the order, as space ids.

• before string The space it should come before. Omit to put it last.
• space_id string, required The space to move.

Put a space at rest: off the galaxy front, unindexed and silent, nothing lost (Rest in the space settings card). Resting the space the person is in moves them to another working space. A space already at rest is refused.

• space_id string, required The space to rest.

Set (or clear) a space's working directory. Command companions spawned in the space default their cwd here so they share one workspace; each still gets its own claude session. Clearing falls back to home, and is a deliberate act: send path as null (or an empty string). OMITTING path is an error, not a clear. Defaults to the current space.

• path required Absolute directory path. Send null or "" to clear it and fall back to home. Required: omitting it is refused with missing_arg, so a malformed call cannot silently clear the setting.
• space_id string Space id (default: current space).

Switch the app's current space by id.

Change a space's name or accent color, as the space settings card does. The name is lowercased with spaces as dashes, and may not be one another space holds. The accent is a hex color like #4ECDC4. Returns the space.

• accent string A hex color, #RRGGBB.
• name string The new name.
• space_id string, required The space (from space_list).

Wake a resting space: back into the working set, on the galaxy front. It does not switch to it (space_switchTo does). A space not at rest is refused.

• space_id string, required The space to wake.

What a port's card shows: its title, then its lines, declared first (known: false), then what Port42 knows (known: true): a terminal's running command, last exit code, directory and bell, a companion working or waiting, a browser's page, console errors. progress is 0 to 1 when there is a bar.

• port string The port's id; omit from a port's own page.

Say what a port is doing, in a few short lines, shown on its card when it is small (a peek), on its card under Running in the rail and in ⌘K, before what Port42 knows about it. From a port's page: port42.state.set([{label, value}, …]) for itself. From an agent: name the port. Only the port, its author, the person or a companion in its space may set it. Kept until the port sets it again or closes.

• lines array, required Up to 5 lines, first the most important, each {label, value}: e.g. [{"label":"doing","value":"building the join card"},{"label":"progress","value":"3 of 5"}]. Values are cut at 80 characters. An empty list clears it.
• port string The port's id; omit from a port's own page.

Delete a value from persistent storage

• key string, required The storage key to delete
• port string For a copy of a port shared from another computer: that port's id, to reach its own storage there.
• scope string "global" for storage shared across spaces; omit for this space's.
• shared boolean true for the space's shared bucket rather than the caller's own.

Get a value from persistent key-value storage. Private to the caller by default; options {shared:true} and {scope:'global'} widen it, and {scope:'global', shared:true} is a PUBLIC board every caller on this computer can read and overwrite, so treat what you read there as untrusted.

• key string, required The storage key
• port string For a copy of a port shared from another computer: that port's id, to reach its own storage there.
• scope string "global" for storage shared across spaces; omit for this space's.
• shared boolean true for the space's shared bucket rather than the caller's own.

List all keys in persistent storage

• port string For a copy of a port shared from another computer: that port's id, to reach its own storage there.
• scope string "global" for storage shared across spaces; omit for this space's.
• shared boolean true for the space's shared bucket rather than the caller's own.

Store a value in persistent key-value storage. Private to the caller by default. {scope:'global', shared:true} is a PUBLIC board: every port, companion and client on this computer can read and overwrite it, so never store secrets or personal data there.

• key string, required The storage key
• port string For a copy of a port shared from another computer: that port's id, to reach its own storage there.
• scope string "global" for storage shared across spaces; omit for this space's.
• shared boolean true for the space's shared bucket rather than the caller's own.
• value string, required The value to store

Execute a shell command and return the output. Runs in /bin/zsh.

• command string, required The shell command to execute
• cwd string Working directory (default: home)
• timeout integer Timeout in seconds (default: 30, max: 120)

From a port's page: call back once, after `seconds`, as port42.timer.after(seconds, fn). Paced as timer.every: only a paused port may fire it later, as soon as it is shown again. Returns { id }.

• id string The timer's id, chosen by the page (the port42 library does this); else Port42 makes one.
• seconds number, required Seconds between ticks (at least 0.25).

From a port's page: stop a timer, by the id timer.every or timer.after returned (port42.timer.cancel(id)). A port's timers also stop when it closes or its page reloads.

• id string, required The timer's id.

From a port's page: call back every `seconds`, as port42.timer.every(seconds, fn), which returns the timer's id. Use it instead of setInterval: Port42 owns the clock and runs it at full rate wherever the port is, another space included; only a port the person paused slows to about once a minute, and it fires at once when shown again. Returns { id }.

• id string The timer's id, chosen by the page (the port42 library does this); else Port42 makes one.
• seconds number, required Seconds between ticks (at least 0.25).

Get the current user's identity (id and display name)