CLI and MCP
Control persistent agents from the com CLI and local MCP server using the same organization-scoped lifecycle and messaging API.
Contents
The CLI and local MCP server use the same authenticated API as the dashboard. They manage persistent agents; com agent login, status and logout configure a model provider for local runs and are a separate feature.
Use the CLI
Install and sign in, or update an existing installation with com update (npm update -g @composal/cli for npm installations). Check your installed command help before scripting. Older releases may expose only local-provider commands under com agent.
com agent --help
com agent list --org acme --json
com agent show AGENT --org acme --json
AGENT is the readable url_slug, legacy slug or returned agent_… public ID. Organization selection is explicit here; commands can also use your saved organization context. Keep token values in the CLI's saved authentication or COMPOSAL_API_TOKEN, not --api-token arguments.
Configure and message an agent
Create an agent with a JSON file containing its name and optional configuration. Send messages with a JSON file containing conversation_id and text. Keep the exact file and idempotency key after an uncertain response.
com agent create --org acme --body-file create-agent.json \
--idempotency-key research-create-001 --json
com agent message AGENT --org acme --body-file message.json \
--idempotency-key research-message-001 --json
com agent update AGENT --org acme --body-file settings.json \
--idempotency-key research-settings-001 --json
Settings updates use native { "expected_version": "RETURNED_VERSION", "instructions": "..." } payloads. There is no separate activation step. Read replies through the dashboard or the native HTTP API.
Share an agent
New agents default to organization sharing. In a CLI release with com agent share, echo sharing_version from show:
com agent share AGENT --org acme --visibility organization --expected-version 7 --json
Use --visibility private to restrict the audience. This command uses optimistic version checking rather than an idempotency key. After an uncertain response, run show to confirm sharing before retrying. Members can view and message a shared agent; owners and explicit managers control settings. Existing agents also become organization-shared at rollout; owners/managers can switch them to private afterward. If your installed CLI does not include share, use the sharing API.
Use an MCP client
For an agent-only remote connection, use Streamable HTTP at
https://api.composal.com/v1/mcp/spark. This connector exposes Composal agents,
conversations, messages, run status and connected-account grants. It does not
expose Verify, browser control, hosting or source-management tools.
Sign in with Composal and approve one organization or all your organizations.
The agents:read scope permits discovery and history; adding agents:write
permits agent creation, messages, conversation management and account grants.
Your existing agent permissions still apply. Start with spark_organizations_list,
then use a returned organization slug or ID with spark_agents_list.
Select an agent by its returned slug or exact name in the agent argument.
Prefer a unique slug when names are ambiguous. Chat responses use agent names
and slugs; conversation and run identifiers remain internal to tool calls.
Sending a message is asynchronous and can take external actions or consume
credits. Preserve the request body and idempotency_key when retrying an uncertain
response. Read spark_run_get and spark_messages_list for the outcome. Run
acceptance alone is not completion; follow message cursors to read further replies.
Connected accounts must already exist in Composal; this connector never accepts
or returns their passwords or tokens.
Install the local Composal MCP server into a supported client:
com mcp init --help
Follow its interactive target selection, or use com mcp stdio as the server command in your client's MCP configuration. Sign in with com login first. The server's com_command tool accepts the same arguments you would type after com:
{ "args": ["agent", "list", "--org", "acme", "--json"] }
To send an existing exact request file:
{
"args": [
"agent",
"message",
"AGENT",
"--org",
"acme",
"--body-file",
"/absolute/path/message.json",
"--idempotency-key",
"research-message-001",
"--json"
],
"cwd": "/absolute/path/to/project"
}
Use the same tool for show, create, update, activation/lifecycle actions, and updates. The MCP tool returns ok, exit_code, stdout and stderr; inspect the JSON response inside stdout and check errors before continuing. It runs with closed stdin, so MCP mutations need a real body file rather than --body-file -. Never put API tokens or provider secrets in tool arguments.
Understand account and connector scope
The local MCP server uses the signed-in Composal user and organization context. It preserves the API's agent sharing, management authorization and version checks. Installing it does not connect an app account to a persistent agent: select that account separately in the agent's Apps and MCPs panel, or use the remote account tools below.
The remote Verify MCP connector is scoped to verification. Do not use its Verify OAuth token to manage persistent agents. Use local com_command for MCP management, or the HTTP API with a personal access token for a server integration.
Use the remote V2 agent tools
Connect an MCP client to https://composal.ai/api/v1/mcp with a Composal personal access token in its bearer authorization header. Keep the token in your client's secret storage. This general endpoint exposes named tools for proactive V2 agents; the Verify OAuth connector remains scoped to verification and browsers.
| Tool | What you can do |
|---|---|
agent_list | Find accessible V2 agents, with search and cursor pagination. |
agent_create | Create an agent with instructions, optional model and repository configuration, and private or organization sharing. |
agent_integrations_list | Discover available app accounts and custom MCPs, current authorizations and enabled state. |
agent_integration_update | Enable or disable one existing account or custom MCP without replacing other settings. |
agent_get | Read agent settings and provisioning status. |
agent_threads_list | Discover the agent's conversations. |
agent_thread_create | Start a separate conversation if you manage the agent. |
agent_message_send | Send a message and receive an accepted run ID. |
agent_run_get | Check whether that run has finished or failed. |
agent_messages_list | Read recent messages, receive replies, and browse older history. |
Every tool takes organization_id as an accessible organization slug or public ID. Agent-specific tools also take id, the agent's returned public ID or readable alias. The API enforces the signed-in user's membership, agent sharing, management permissions, and feature availability.
For example, create an agent:
{
"name": "agent_create",
"arguments": {
"organization_id": "acme",
"name": "Research assistant",
"configuration": { "instructions": "Research the topics I send you." },
"visibility": "private",
"idempotency_key": "research-agent-create-001"
}
}
Choose app accounts and custom MCPs programmatically
After creating an agent, use agent_integrations_list with its organization_id and id. This lists the accounts available to that agent, including already-connected custom MCP servers. Filter by q or toolkit, and follow data.pagination.next with cursor for more accounts. Each account includes its id, current generation, reference, enabled state and availability information.
Enable only the account the user requested, using the exact returned values:
{
"name": "agent_integration_update",
"arguments": {
"organization_id": "acme",
"id": "AGENT_ID",
"connection_id": "RETURNED_CONNECTION_ID",
"generation": 1,
"enabled": true
}
}
Replace generation with the account's returned integer, not a guessed version. To turn it off, use enabled: false. Repeat for each agent that should use the account; this updates one selection without replacing other accounts, instructions or repository permissions. The response contains the agent's current account selections. After a lost response, list the accounts again before retrying. Enabling an account does not start the agent or send it a message.
For another new agent, you can also put a returned reference in agent_create's configuration.connection_grants array. Creation and updates recheck current ownership, sharing, generation and availability. Managing an agent does not grant access to someone else's private account; private agents may use their owner's accounts automatically. These tools select existing connections, not create MCP servers or collect credentials. Connect missing accounts through the secure connection flow; never send API keys, tokens or passwords in tool arguments or chat.
Call agent_get until data.agent.setup_pending is false, then send a message:
{
"name": "agent_message_send",
"arguments": {
"organization_id": "acme",
"id": "AGENT_ID",
"conversation_id": "main",
"text": "Summarize the latest release notes.",
"idempotency_key": "research-message-001"
}
}
Tool results contain status and data inside structuredContent. Check isError and the HTTP status before continuing. Creation and messaging can start billed agent work. Preserve the same idempotency key and exact arguments after an uncertain response.
Message acceptance is asynchronous. Use agent_run_get with the returned run_id and original conversation_id, then agent_messages_list to read the reply. Without a cursor, the messages tool returns the latest bounded history page. Pass the returned older_cursor as cursor for older messages, or newer_cursor for newer messages, and deduplicate by message ID. You can also supply run_id to include that run's status in the history result.
Receiving replies and proactive messages uses polling. These tools do not register push notifications or keep a subscription open. Poll each conversation you want to follow; use agent_threads_list to discover other conversations.
Claude Code and Codex with Desktop
Desktop builds that include coding-agent control use your existing computer pairing. In Desktop, connect to your organization and allow computer access. Install and sign in to Claude Code or Codex locally, then open the V2 agent's Setup → Your devices panel, choose your computer and select the provider. Desktop manages the connection; you do not need a separate CLI pairing or foreground daemon for this path.
Existing agent grants cover Codex. Choose Allow Claude Code and confirm access to add Claude. The agent can then create Claude or Codex threads that appear in its normal Activity → Threads list, with their computer and provider. Follow-ups keep the same native session. Native permissions and credentials stay on your computer. An independently running Claude session can be read; remote control does not take over its writer or interrupt a turn owned by another process.
Linux Desktop 0.1.110 supports both providers through its existing pairing, including background operation, incoming-message controls and task results. Fresh sign-in, real-model background execution and the published Desktop UI have hosted qualification. Mac publication and native Mac testing remain deferred. The published standalone CLI daemon below supports Codex.
Linux CLI 1.17.113 can select a Desktop-connected Claude provider explicitly.
com --org acme control --device "My computer" --provider claude threads list --json
com --org acme control --device "My computer" --provider claude \
--request-key rename-001 threads rename NATIVE_THREAD_ID --name "Repair sign-in"
In candidate builds, choose Rename thread beside a local conversation's name. This changes its native Claude Code or Codex title without a model prompt and keeps your unsent message. A failed response keeps the entered name; use Check same request to recover its receipt. New Claude thread names are saved immediately and applied to the native session when its first task starts. Native thread IDs stay the same.
To tidy the agent's Threads → On computers list, hover a finished Claude Code
or Codex thread and choose Archive. It leaves the list once the computer
confirms; open Archived and choose Restore to bring it back. Archiving
keeps the conversation history and never changes the session's folder, git
checkout or worktrees. A thread that is still working is refused until you stop
it. The control appears once the computer's Desktop supports archiving. Agents
use local_agent_control with threads.archive and threads.unarchive for the
same result.
To add an existing native conversation in candidate builds, open Computer → Your devices, select its provider and thread, then choose Add to agent. Its existing messages and title appear in the agent's normal Threads list. Enrollment sends no message. Claude requires this agent's explicit access and no active external writer; Codex must be unloaded. Check same request recovers a pending adoption after reload without creating another conversation. An updated Desktop Control connection is required. If Add to agent is disabled and asks for an updated connection, update Desktop and reconnect the computer.
com --org acme control --device "My computer" --provider claude \
--request-key adopt-001 threads adopt NATIVE_THREAD_ID --for-agent helper
com --org acme control --device "My computer" \
operation DEVICE_CONTROL_OPERATION_ID --for-agent helper
Use the original operation ID for receipt recovery. Completed adoption receipts retain their native thread references after copied results expire. The read requires current access to that agent and computer.
Connect your computer
Coding-agent control is available in production. A V2 agent can discover, start and continue Codex or Claude threads on your paired computer. Your computer must be awake and connected. Codex and Claude use their own installed sign-ins, and their credentials stay on that computer. The provider account's usage limits apply to local turns.
Desktop controls Codex through its running local app-server. Open the Codex app, or run codex app-server daemon start if your installed Codex CLI provides that command.
Desktop setup. Install Composal for Mac, the Windows installer, or the Linux package, then sign in to your organization. Desktop bundles the device runtime and control daemon and connects this computer automatically. Open your avatar menu → Devices to check its connection or use Connect this computer when a manual retry is available. Existing paused work stays paused.
Use Keep this computer connected to enable background startup. Closing the chat window then leaves the service available while you remain logged into the operating system. The computer's ⋯ menu offers Rename and Remove computer…. Rename preserves its connection; Remove disconnects it and removes its entry, while keeping local provider threads and workspace files.
When you use an agent on this computer, Desktop remembers its connection for future restarts. If a task is interrupted during an update or disconnection, send a new message to continue.
When you reopen Desktop, it checks the saved computer registration before reconnecting. A revoked registration stays disconnected; Desktop does not register a replacement automatically. If the connection cannot be checked, your saved pairing is kept for retry.
Desktop's paired-machine sessions use your OS account's access without project or per-command approval dialogs. While a computer's All agents switch is on in Devices (the default), requests you send as its owner can use any agent, including ones you add later, without another per-agent setup step. Turn it off to allow only the agents you choose. Agents already listed keep their access until you remove them. General file, program, browser and screen-control tools also require their device execution grants and availability. Where those tools are enabled, a cloud conversation can use the paired computer directly. Saved restrictions and revocations remain effective. Another team member needs an explicit grant from the computer owner. macOS Accessibility and Screen Recording permissions are configured separately in Devices when using computer control.
Ask your V2 agent to discover existing Codex or Claude threads, start a thread in an existing directory, or continue a saved thread. Agent-created threads appear in Activity → Threads with their harness icon, native thread title and computer name. Follow-up messages use that thread's original provider.
In Linux CLI 1.17.113, list your paired computers. Select a computer and provider for its native thread list.
com --org acme control computers --limit 20 --json
com --org acme control --device "My computer" --provider claude threads list --json
Use the returned computer ID when names are ambiguous. Current end-to-end qualification covers Linux Desktop 0.1.110 and Linux CLI 1.17.113.
CLI-only setup. An installed CLI whose com control --help lists these commands can also connect a standalone Codex daemon:
com update
com control connect --org acme --name "My computer"
com control daemon
Use your organization slug (such as acme) or its org_… ID for --org.
Keep the daemon running. It uses Codex's installed app-server connection and account; it does not copy model credentials. If your Codex executable is outside PATH, pass --codex-binary /absolute/path/to/codex to the daemon. Use separate --profile NAME values when connecting multiple organizations.
On macOS, if com control daemon --help lists service commands, install a background login service after pairing:
com control daemon install
com control daemon status
Run these as your normal macOS user, without sudo. Installation starts the service now and at future logins, so you can close the terminal. Your Mac must remain awake and logged in. Status shows process state and log paths; use Setup → Your devices to check the connection.
Use com control daemon stop to stop it and disable login startup, start to enable it again, or uninstall to remove the service while keeping your pairing and logs. Pass the same --profile NAME when managing another profile. Stop any foreground daemon before installing, and uninstall the service before disconnecting. This service is managed separately from Desktop's connection.
For the standalone daemon, open the V2 agent's workspace, choose Setup → Your devices, select the computer, and enable Let this agent use Codex. Only requests from the person who granted access can use that grant. Existing browser, file, or process grants do not grant access to Codex conversations.
Your devices lists loaded Codex agents and recent threads. Select a thread to read its history or send a message, or choose Start a Codex thread and provide an existing absolute directory. Stop turn interrupts the selected native turn. The standalone daemon preserves Codex's native permission settings. Interactive approvals for that daemon are completed locally in Codex.
Your computer's paired daemon must remain running to read or control these threads.
Control collaboration
Compatible Desktop source builds manage the connection through your existing Desktop pairing and support both Codex and Claude Code. Enable Claude Code explicitly in Setup → Your devices. New agent-created native threads join the agent's private Relay room automatically and appear in its normal Threads view. The separate manual CLI daemon above remains Codex-only.
The local thread list can appear while the provider's sign-in check is still running. Status updates automatically, including when you open a thread. Start and send controls become available when the provider reports readiness.
In Desktop builds with Activity → Control and the web workspace, the Control view shows participants, channels, direct conversations and replies for your requester room. Native participants show their saved thread title, Claude Code or Codex icon, and full computer name. Choose Open thread to open an authorized participant’s native history and composer. In Desktop, Back to Control returns to participants. In the web workspace, Back to the agent returns to the parent conversation. Viewing does not mark messages as read. Choose Download beside an attachment to save it, or Message beside a participant to send a direct message as yourself. Open a channel or direct/group conversation to write there; choose Reply beneath a channel message to start or continue its replies. Drafts and pending sends survive a reload in the same window or browser tab. Use Check delivery after an uncertain response. Your Relay membership still controls sending; viewing does not join a conversation. Use Manage for the channel or group actions your current Relay membership permits. Use Threads to continue or stop native work.
For a local thread, Disconnect Relay immediately blocks new Relay access while keeping native history and running work. Cleanup recovers automatically if the connection or a background job is interrupted; you do not need to repeat the action. Use Stop turn separately to interrupt model work.
For an adopted native session, the thread workspace shows its Participant name. Choose Rename participant to change that address. Earlier addresses continue forwarding, and the native conversation keeps its title and history. Use Check result for an unconfirmed save. This control is available in the web workspace and Linux Desktop 0.1.132.
An adopted session uses its native MCP tools to reply when Final-answer replies is set to Auto. Select Always in Incoming messages to send its final answer back automatically for incoming messages. A native reply consumes that message's automatic reply opportunity.
To continue an idle thread in its native coding app, choose Release thread when available in your build. Codex detaches this control connection, and Claude closes its idle process. Resume the same native thread to continue with its history. Incoming Relay messages can reopen the thread. Use Incoming messages → Ask first to hold those messages for your approval while you work locally.
For a busy thread, use Stop turn for its exact active turn, wait for idle,
then choose Release thread. Updated Desktop source builds report a busy
Release refusal as a failed release_not_applied receipt. Keep an uncertain
Release receipt and inspect the native thread before another write.
V2 uses local_agent_control for Release with arguments.provider,
arguments.thread_id and the original arguments.source_operation_id from thread
creation or adoption. Keep that
receipt with the native thread ID. Published Linux Desktop 0.1.110 has verified
live Claude process closure and Codex unsubscribe through this path.
Native first-party MCP also exposes integration.action.register,
integration.action.get_invocation and integration.action.complete. A native
session can register its own action handler. V2 invokes it through relay_call,
then gives that handler a task containing the returned invocation reference.
The handler reads the persisted input and completes the same invocation with its
typed output. This explicit two-task action flow has hosted real-model
qualification for both Claude Code and Codex through Neki-backed Relay storage.
Source CLI builds with com control relay --help also expose the room as your human operator identity:
com control relay AGENT tools --org acme --json
com control relay AGENT resources --org acme --json
com control relay AGENT call message.dm.send --org acme \
--requester-id REQUESTER_FROM_DISCOVERY --request-key relay-message-001 \
--arguments-file relay-message.json --json
com control relay AGENT operation OPERATION_ID --org acme --json
For the send example, relay-message.json contains a JSON object such as {"to":"v2-agent","text":"Hello from my CLI"}. Discovery returns the requester ID. Retain it together with the exact request key and arguments after a timeout. Switching accounts cannot silently replace the sender. Calls do not retry automatically. A completed tool receipt does not mean the recipient read the message or finished a task.
Control automatically delivers new native messages to V2 for already-authorized work, and can wake an idle enrolled Claude/Codex session for an incoming Relay message. Updated Desktop connections keep the original receipt queued until a busy native session is idle, preserving thread order and leaving reads and exact interruption available. The message expires at most one hour after creation. In the originating agent’s Threads view, verified incoming Relay messages show their sender and original text. That context remains available after Relay disconnect while native history is still authorized.
For a priority direct message, the first-party message.dm.send tool accepts "mode":"steer" on an updated Control connection. Claude interrupts its active task and accepts the message in the same session. Codex accepts a distinct input on its active turn. Native permissions and incoming-message approval still apply. Keep the original receipt after an uncertain delivery. For channel priority, join or invite the intended agents first, then use message.post with "mode":"steer". The Control channel composer also offers Delivery → Priority input.
An acknowledged steer or Stop turn retires the superseded turn's unclaimed automatic report. An already claimed outbound report keeps its original receipt and outcome.
Idle V2 round trips, native approval and busy-session waiting have real-model qualification for both providers. Published Linux Desktop 0.1.124 also passes computer-level message review through hosted V2 and QA Neki. Published Linux Desktop 0.1.126 passes hosted V2 priority DMs and channel posts to both real providers with exact automatic replies. Published Linux Desktop 0.1.129 preserves pairing across upgrade and displays both native histories and channel reply threads. The published channel delivery selector passes keyboard qualification, and production recovery retires the superseded automatic report. macOS publication and native Mac testing are deferred for this task.
For structured task results, V2 can pass an optional
result_schema JSON Schema object or boolean when starting or adopting a native
thread. That original source receives a submit_result MCP tool and schema
resource. Native models can submit progress with final:false, then a final
result with final:true (the default). A final result closes submissions; it
does not mean the native process exited. V2 reads results with
local_agent_result using the original source operation ID. A new final result
automatically queues a follow-up in its originating V2 conversation; progress
results remain available without waking it. The follow-up keeps the original
requester and current computer access. In the native thread workspace, choose
Task results to read submissions and agent-delivery status. The shared
Desktop view is available in Linux Desktop 0.1.110. Both providers have passed
hosted progress/final submission and automatic V2 result reads through that release.
com control relay AGENT task-result SOURCE_OPERATION_ID --org acme --json
Read additional pages with the returned next_cursor using --cursor.
Adoption also accepts --result-schema-file schema.json (or - for stdin).
Keep the same request key after an uncertain callback and read its receipt.
Result data expires after one hour; task completion and receipt identities are
retained. A queued follow-up does not mean the agent has read or completed the
result. macOS publication and native Mac testing remain deferred.
New threads from a conversation
On desktop and web, choose + in your V2 agent's name pill to start a new thread from the one you're in. Write what the thread should work on, then choose Start or press Enter (Shift+Enter adds a line). A thread can't start without this first message: the agent names the thread from it and starts working on it straight away. If naming fails, the thread is named from the message's opening words.
Beside Start, Works on says what the thread works on. By default it's one of the agent's repositories, in its own copy, so it can't change another thread's files. Choose the coding agent (Codex, Claude Code or Pi) beside it. Only Codex can start in an Empty folder, without a repository. Separate copies are offered on private agents; elsewhere a new thread works on the Agent’s computer, or in the same folder from a thread on a computer. Open Works on to choose: a repository, Empty folder, Agent’s computer (its machine in the cloud, sharing files with the agent's other threads), Same folder (from a thread on a computer), or a folder on one of your computers. The new thread starts without the earlier conversation's messages; the agent keeps its identity, instructions and accessible memory. Back returns to the thread you started from, and Bring result back adds the new thread's last reply to that thread's draft.
The orbs at the end of the name pill are the subagents running now or finished recently, one colour each. Choose them to see what each is doing, or All subagents for the full list.
Threads started by earlier app versions with copied conversation context show it collapsed under Started from parent conversation, separate from the new thread's messages. Expand it to read the earlier conversation.
The new thread opens in the main conversation area with its own composer and history.
Works on has two sections, Cloud and Your computers. Under Your computers, each paired computer lists its projects: the folders you chose for it in Devices, then folders where earlier threads ran, most recent first. Choose one to start the thread there. Another folder opens Folder, which lists the same projects. On your own computer it also lists subfolders as you type a path starting with ~ or /; pick one to see its subfolders. Press Enter to use the typed folder, then choose Start. Remove a folder from your computer's projects with its × button. Folder lists come from Composal Desktop, so the computer must be connected, with local agent control enabled for your organization. On a teammate's computer you see its projects and type the path yourself. You can start another thread from any thread, and Back always returns one step.
Folder starts empty unless you already chose another folder on that computer. Use a project folder rather than your entire home folder or a drive root. An invalid folder stays editable so you can correct it; choosing a working folder does not add a permission approval or restrict the paired machine's access.
After a reply finishes, Bring result back appends its text to the source conversation's composer as an editable draft. Existing draft text is retained. Review it before sending. Each thread keeps its own unsent draft.
If creation loses its reply, use Retry or Open it to recover the same thread.
Opening a computer-hosted thread waits for that computer to finish preparing it. If setup is still pending, Retry continues the saved setup with the same folder and conversation context; it does not dispatch another worker or create another thread.
When your V2 agent creates a Codex or Claude thread through Desktop, open Activity → Threads in the agent's hosted conversation. The new thread appears under On computers with its harness icon, title and computer name. Each row shows whether it is Running, Waiting for you, Failed, Stopped, Done or Offline, and when it last did something. Running and waiting threads come first. New idle threads stay visible ahead of offline threads, including before their first prompt. Finished threads fold under Done. A title taken from the thread's first prompt shows that prompt's first line; hover over it to read the whole prompt. An older Desktop connection shows Status unavailable until the computer helper is updated. The list keeps every loaded page current and orders sessions by state and last activity before paging. Select a thread to read live history, send a follow-up, or stop its current turn. Return to the thread list to choose another conversation. Local threads are visible only to their original requester under current consent; other members of a shared agent cannot read them. Revoking consent removes access to these links and their history.
Thread links retain the native thread ID after temporary operation payloads expire. History is read from your computer, so it must be connected. The list refreshes while open; use Refresh to check immediately. Drafts and unresolved receipts stay with their thread while navigating within the agent workspace. Check an unresolved receipt before sending again.
If ending a Claude thread reports that session discovery is unavailable, refresh its status before trying End again. That refusal keeps the native thread's state intact. An uncertain End requires inspection of its original receipt and native thread before another write.
Opening or refreshing a native thread updates its sidebar name. If current title metadata is unavailable, the list uses its saved title or a short native ID. You can name a newly created Claude thread before its first task. The chosen name survives Desktop restarts and becomes its native Claude session name when that task starts.
Open Incoming messages on an enrolled thread to review delivery preferences. Desktop builds with these controls show the same panel below the thread heading. Enable Ask first for this thread to review incoming messages before native execution. Choose Approve message or Dismiss message for each held item. If a decision's response is lost, use Check receipt to inspect that original decision. Retry same decision retains its original version and choice. With an updated Desktop connection, Always forwards an incoming Relay turn's final answer back to its original conversation. An explicit native reply prevents an extra automatic answer. Auto uses the thread's defaults, including replies to the V2 agent that created it; Off drops waiting automatic replies. A send already claimed can still finish. Save preferences before leaving the panel.
Linux Desktop 0.1.120 provides a computer-wide restriction in Devices → Control messages. Turn on Restrict incoming Control messages to require an allowed sender or an explicit approval across Claude and Codex sessions on that paired computer. Each agent room keeps its own allowed senders. Queued deliveries are checked when they are claimed, and a turn already admitted can finish under its original receipt. The setting survives reconnecting the same computer registration.
Linux Desktop 0.1.124 adds Review messages in the same section. It lists held messages across your authorized Claude and Codex threads on the selected computer. Each thread shows its harness icon, title, agent and computer, followed by the sender, preview and expiry. Open Incoming messages for that thread to approve or dismiss the original message, then Refresh the inbox.
Linux CLI 1.17.115 provides the same inventory.
com control --device "My computer" delivery-policy inbox --org acme --json
com control --device "My computer" delivery-policy inbox --org acme \
--cursor NEXT_CURSOR --json
Continue with next_cursor until it is null, including after an empty page.
The inbox shows messages from your own sources under current agent access and
computer consent. Reading it preserves each message's approval state.
Linux Desktop 0.1.123 also supports switching organizations through sign-out and browser sign-in. Choose the other organization during sign-in. Desktop creates a separate native Control identity for each account and organization; returning to an organization reuses its registration. The last locally chosen computer-wide restriction follows this Desktop installation and is applied before connecting. Allowed senders and thread permissions stay with their original organization. A newer server version for the current registration takes precedence when reconciling a saved change. macOS release and native Mac testing of these controls remain deferred.
Read and change that computer setting with Linux CLI 1.17.114 or later using the version
returned by show.
com control --device "My computer" delivery-policy show --org acme --json
com control --device "My computer" delivery-policy set --org acme \
--restricted true --expected-version VERSION
After a lost response, read show and retain the original version before another
change. Per-thread Incoming messages displays when this computer-wide rule
applies. These computer-wide controls currently ship on Linux.
The CLI exposes the same versioned setting. Read the current version with
com control relay AGENT delivery SOURCE_OPERATION_ID status, then use
set --expected-version VERSION --restricted false --ask-first false --final-reply always.
Choose auto, always, or off; omitting --final-reply preserves the saved mode.
Omitting every --allow-sender clears sender allowances, so include each existing
allowance when replacing restricted preferences.
Sign outbound Relay events
V2 and enrolled Claude/Codex sources can create an outbound event subscription
with integration.subscription.create. Pass signature_scheme: "standard-webhooks"
and a private whsec_-prefixed base64 secret encoding 24–64 bytes. The receiver
gets webhook-id, webhook-timestamp and webhook-signature headers. The signature
binds the delivery ID, Unix-seconds timestamp and exact raw request body. Read
signatureScheme from the creation or inspection result to confirm the selection.
Retries retain the delivery ID and event body while refreshing the signing
timestamp. The receiver verifies the raw-body signature and timestamp tolerance,
then uses the delivery ID to prevent repeated processing. Omitting
signature_scheme preserves the existing legacy raw-body HMAC behavior, with
its X-Relay-Signature header. Current source authority and source-owned
subscription cleanup apply to both formats.
Continue a V2 conversation from a Relay webhook
For organizations with local agent control enabled, ask your V2 agent to create
one Relay channel and an integration.webhook.create resource in the conversation
you want to continue. Tell the agent what work incoming events authorize. Its
first-party relay_tools and relay_call tools supply the endpoint and bearer
token in the successful creation receipt.
Configure your sender to POST JSON containing text to that endpoint with
Authorization: Bearer <webhook-token>. An accepted event appears as Relay
webhook in the original V2 conversation and automatically continues that
conversation. The original requester must retain access. Incoming text supplies
external context and can continue work already authorized in that conversation.
Keep the bearer token private. If a response is lost, inspect the original
channel before sending again. Ask the same V2 agent to remove the hook with
integration.webhook.delete when it is finished. It can archive a temporary
channel with channel.archive.
The hosted flow passed a real-model test on the QA Neki backend after a Control worker replacement. macOS release and native Mac testing remain deferred.
Receive a webhook in a coding thread
For organizations with local agent control enabled, a source-owned Relay webhook
can continue its original Claude Code or Codex conversation. Ask your V2 agent to
start a native thread, have that thread join a Relay channel, and create an
integration.webhook.create resource through its attached first-party MCP tools.
Keep the native thread in that channel. The completed creation receipt supplies
the endpoint URL and one-time bearer token for your sender.
Configure the sender to POST JSON containing text to that URL with the token
in its Authorization: Bearer <webhook-token> header. Keep the token private.
Delivery uses the webhook's original source and current requester permissions.
An event's display author cannot select a different coding thread.
Open the native thread's Incoming messages controls. Ask first holds the event until you approve it. Always returns the verified final answer as a reply to the original Relay event. The same preferences and approval receipts are available through the CLI delivery commands. Disconnect Relay retires that source's hooks and keeps its native conversation history available under your current computer access.
The hosted approval and automatic-reply flow has been verified with real Claude and Codex models on Linux Desktop 0.1.93. macOS release and native Mac testing remain deferred.
When V2 creates an empty native thread and submits its first task in the same request, Auto returns that task's final answer to the original hosted conversation as a Relay DM. A native DM to V2 or an accepted final structured result consumes that automatic report. Off retires a waiting report, and changing back to Auto does not revive it. Later direct control tasks keep their own native receipts.
Running threads keep updating while selected. Large history pages automatically use fewer turns; an individual turn that exceeds the remote display limit must be opened in Codex.
You can also operate locally or select a paired remote computer explicitly:
com control agents list --json
com control threads list --json
com --org acme control --device "My computer" threads list --json
com --org acme control --device "My computer" --request-key task-001 \
send NATIVE_THREAD_ID --message-file task.txt --json
Thread lists page recent threads and loaded sessions independently. Continue with --cursor and
--loaded-cursor; use --skip-recent or --skip-loaded when that stream has no next cursor.
Read-only operation receipts expire after five minutes; refresh the thread to read current history again. Network failures keep the history already shown. Losing permission or a failed Codex read clears it; check that the native thread still exists, then refresh.
Remote writes require a request key. Keep the exact key and message after an uncertain response; inspect the returned receipt or thread before sending anything else. com control --device COMPUTER operation OPERATION_ID checks a receipt without repeating work. A completed send receipt means Codex accepted the turn; read the thread for the final answer. Canceling the invoking V2 run or closing the panel stops observation, while an already accepted operation can still execute.
If a hosted agent restarts during local work, ask it in a fresh message to inspect the existing thread or receipt. The local Codex turn can keep running while the connection recovers. Inspect its result before repeating an edit.
Turn off the agent's Codex switch to revoke its grant. Choose Disconnect computer in the panel or run com control disconnect on the computer to revoke the pairing. Revocation stops new requests and access to copied history; a Codex turn already running may continue locally. Copied request and result contents expire after one hour. The original Codex conversations remain on your computer.