Search Composal documentation

Search public documentation, commands, and release notes.

Persistent agents

Create always-on agents with their own instructions, memory, app connections and work repositories. Control them from the dashboard, API, CLI or MCP.

Contents

A persistent agent is a named assistant you configure for ongoing work. Its identity, instructions and history survive browser sessions. It can receive messages, react to configured events and run on a schedule. Idle agents do not need a continuously running sandbox.

By default, an agent can create and coordinate its own threads for work you authorize, including messaging those threads and reviewing their results. A general instruction to avoid other agents refers to separate team agents; you can explicitly restrict its own delegation too. As the owner, you can revise an earlier role instruction in chat without a separate manager approval. These instructions do not grant access to repositories, integrations or data. Available tools and access settings still apply. Existing agents receive this guidance on their next turn after the runtime update.

In V2 chats on the web and desktop, your message bubbles use a soft tint of the agent's primary character colour. Light and dark themes keep the bubbles muted and the text readable. Agents without a character colour use neutral bubbles.

V2 agents answer in your local time. The web app, Composal Desktop and the iOS and Android apps send your device's time zone and clock with each message, and the agent sees when you sent it in your zone. Email, Slack and report turns use the zone your apps last reported. Only the time zone and time are sent, never your location. To pin a zone instead, send PATCH /api/v1/me with an IANA time_zone such as Europe/London; send an empty value to follow your device again. Older app versions send no zone: the agent uses the one your other apps last reported, or UTC.

V2 agents use 12-hour prompt caching for OpenAI calls in chats, automations and coding runs. Matching context can be reused across breaks without changing any settings. Cache writes cost more than with the default 30-minute lifetime, so savings depend on how often the context is reused.

Generate images in chat

Ask a V2 agent to create an image, or attach a reference and describe the changes you want. The conversation shows Sketching it out while the image is being made. Open the finished image to view it full size or download it. Generated images are also saved privately in the agent’s Library. Image generation uses the organization’s token credit.

Agents-only workspaces

An administrator can enable agents_only_ui for an organization to open directly in V2 Agents. The sidebar shows your agents and inbox without a product picker, Verify link, or Agents back button. Account settings, team settings, billing and integrations remain available. Disabling the flag restores the organization’s usual product navigation. Agents shows V2 agents in either layout.

V2 sandbox resources

On web and desktop, select the agent’s name and open Setup → Computer. It includes the machine profile, runtime size and environment, agent-specific secrets and repositories. Only the agent’s manager can change them. Choose Mac for a Mac runner, acknowledge the change, then choose Save changes. Mac must be enabled by an administrator. If runtime settings report that the worker needs an update, the administrator must update that organization’s worker before these controls can load. Setup updates while the Mac is preparing. Switching between Linux and Mac keeps separate workspaces.

Ask a V2 agent to size its sandbox for the task, for example: “Use 8 GB RAM” or “Set up ComposalAI/vex for development with a 16 GB volume for the checkout and build caches.” Its sandbox_runtime tool inspects and changes its own runtime.

New Blaxel Linux sandboxes include a 16 GB volume at /home for repositories, Rust build caches, Docker layers and files that must survive sandbox replacement. To opt out, ask the agent to call sandbox_runtime with action=configure, volume_size_mb=0 and the latest status version before its first sandbox command. Operators can set CLAWDER_SANDBOX_VOLUME_MB=0 to disable the default. Existing workspaces can be migrated to a volume after the agent stops processes that write files. Migration preserves /home and native workspace files; files elsewhere are not copied.

The development base includes npm, pnpm, Bun, Go, uv, Docker, jq, Git and native build tools. An agent can build a repository-specific Docker image and switch to it while retaining an attached volume. Changing memory or images restarts processes and may clear files outside the volume. Attached volumes can grow, but cannot be shrunk or removed through the tool.

Create your first agent

  1. Open Agents in your organization, then choose the round + (New agent) beside Agent Inbox in the sidebar.
  2. Enter a name and instructions describing its purpose and how it should report back. Composal generates a readable, organization-scoped link such as /vex/agent/garrytan. Names are reserved automatically; collisions receive a short suffix. Existing identifiers keep working.
  3. Under Who can use it, choose Just me (a private agent that uses every app account you've connected) or My team (everyone in the organization; tick the apps it can use under Apps this Spark can use). Then choose Light Spark. The desktop app shows Lighting… until the agent's computer is ready, then opens the conversation.
  4. Open its conversation and send a message. No separate activation step is required.
  5. Follow its task status and reply in the conversation, or check Agent Inbox for outcomes across agents.

Character generation runs in the background. If a request fails or its outcome cannot be confirmed, an owner or manager can retry from Settings. Retries reuse completed work. If an animation sheet cannot fit the image limit, the retry regenerates one animation while retaining the character and other strips. Generation never changes the agent's operating instructions or grants access to apps or repositories.

V2 agents also receive an original generated character in the background. Existing active V2 agents without one are picked up automatically. The published character appears in the agent list, conversation header and Composal Slack replies. In the app, a black-and-white dithered sphere stands in until it is ready, and agents without a character keep that sphere. Animated characters use the organization's avatar setting; reduced motion uses the still image.

To customize a V2 character on desktop or web, open Setup → Name and avatar and choose Customize beside Avatar. New agents start with Pixel. Choose that style to preview a shape, color, and accessory. Choose Dither for the original sphere. Auto lets the character choose that detail from its seed. Select Apply changes to save the previewed character, or Regenerate for a fresh character. Pixel characters react to the pointer and use their smaller form while thinking or working in chat. You can also pick Chibi, Anime, Globby, Emoji, Animal, or Dino and describe its appearance.

You can also send /avatar in chat to open the picker, or include a style and prompt: /avatar dino a curious purple pal. This opens the editor without sending a message to the agent or starting generation. Owners and managers can request changes; other users cannot start a generation.

Ask a V2 agent to change its character in ordinary chat, for example “Make your character blue” or “Give yourself a new animal avatar.” Its built-in avatar tool can read the available styles, request an edit or fresh character, and explicitly retry an interrupted generation. character_get and character_generate remain available. Generation returns immediately; only ready confirms publication. The last published image remains visible during replacement. A failed or uncertain paid request is never automatically repeated. Use Retry generation to resume saved work. If delivery of your request is interrupted, Retry request reuses that same request.

The conversation uses the agent’s main link, such as /vex/agent/garrytan. Other tabs have their own paths: /memory, /files, /updates, /triggers and /settings beneath that link. Older links using agent_view still open the matching tab.

V2 conversations open with a recent page of messages. Scroll up to load earlier messages a page at a time. At the top, choose Load earlier messages if scrolling does not fetch the next page. Desktop keeps a recent window for reopening conversations; earlier pages remain available by scrolling up. Summarizing a long conversation does not hide its earlier messages. After a conversation reset, history starts at the reset, with any messages the reset kept, and a note marks where it happened. If earlier messages can’t be found from where you are, a note asks you to reopen the conversation.

Switch agents from the agent list in the sidebar. When the sidebar is collapsed, select an avatar to open that agent. The selected V2 agent, its navigation and the message box appear at once, with placeholders where the messages will be. You can start typing right away; the loaded history fills in around your draft without touching it.

Switch between Agent Inbox and your agents without reloading the page. Both sidebars stay in place while the selected content loads. Unsent conversation drafts are restored when you return to an agent from the inbox or another agent. Switching organizations clears the previous organization’s workspace.

Mission Control cards show what changed and the next action, with a link to the relevant PR or commit when available. Long cards scroll inside their fixed frame. On the map, scroll over overflowing card content to read it; scroll elsewhere to zoom. Focus a card’s content to use arrow keys and Page Up or Page Down.

Cards can show a short paragraph, actions, check status, a PR chip, or an existing screenshot from the thread’s Library. Quiet work can omit the summary. Cards use GPT 6 Luna with high reasoning. They refresh after thread activity or changed PR evidence, and may briefly show the last reply while the server prepares the card. A summary does not approve, merge, deploy, or release work.

In the web agent panel, returning to Automations, Skills, or Library preserves your place while hidden panels pause their activity. Quick revisits reuse recent reads; Refresh still requests current data. If a workflow-run refresh fails temporarily, the last loaded runs remain visible with a retry option. Losing access clears them.

In Library, you can choose another file while a preview loads. The latest choice wins. Small, unchanged previews are briefly reused; explicit downloads always request the file again.

Agent replies, background results and Updates render Markdown, including lists, links, tables and code blocks.

Where the read-only briefing experiment is enabled, Agent Inbox also shows a short agent-written recap of what V2 agents have done since yesterday. A background writing pass chooses up to four completed highlights and writes a brief paragraph, with inline count chips, people and miniature file or change previews. It prioritizes bug fixes and test repairs. Rails validates references against the work you can currently read and supplies the widgets and their values; the writer cannot supply its own counts or links. Coding results with the same activity and delivery stage share one combined count instead of repeating the same point; tap that widget to choose an individual result. Other widgets open their details directly. Group counts come from the submitted item list, not numbers in a title; people chips show a sample of the names, with the full list in the details. Blockers and failures appear separately under Needs attention, never as accomplishments. Once one is dealt with, people who can manage its agent can open it and choose Mark handled to clear it; it comes back if the agent reports a change to it. See activity opens all returned work, including unfinished work and outcomes not highlighted in the recap. Findings show submitted measurements, message excerpts remain read-only, and library files use the agent's existing access controls. Other work uses a summary with labelled fields.

The inbox does not wait for the writing pass: saved results remain available through See activity while the recap is being written or is unavailable. An unchanged recap is reused; new or revised work requests a fresh one. The writing pass receives bounded outcome titles and summaries, not full transcripts, test logs or file contents. Its prose is agent-reported, not independent verification of the underlying claims. If generation fails, the inbox says so rather than presenting a template as an agent-written recap.

The briefing includes up to 50 results updated in the last 24 hours and 20 older outstanding exceptions. Counts describe the displayed collections, not all-time totals. Agent reported means the agent submitted the result; it does not independently verify a fix, deployment or message delivery. An exception is something to inspect, not an approval request. Sending, editing, applying changes and approvals are not part of this experiment. Conversations and the existing inbox updates remain available below the briefing.

Agents are instructed to save meaningful outcomes from ordinary work without a separate request: research, drafted writing, generated files or Pages, code changes, and substantive blockers. They skip simple answers, acknowledgements and checks with nothing new, and respect requests not to save or publish. Existing agents receive this guidance on their next message after the worker update. This is agent-driven reporting, not automatic extraction of every conversation or a guarantee that every task will appear.

Agents use work_publish to save the outcome and work_get to update the same result rather than duplicate it. For new results, the runtime supplies the current conversation source when omitted. Updates reuse the original source returned by work_get, even when the task continues in another conversation. Files are preserved separately with library_publish, then referenced by the saved outcome. Publishing does not perform the work itself or replace event_report; if it fails, the agent still returns the work in chat. If an open result changes, Updated result available loads its newer revision without silently replacing what you are reading. Disabling the experiment restores the existing inbox without deleting saved work.

Bug fixes and test repairs use the same work_publish tool. Opening their recap widget shows a short outcome and a compact source card linking to the full description, such as a GitHub pull request or commit. Agents put that link in the first non-null evidence.source_url; local work without an external link offers View work instead, and never invents a GitHub link. Implementation explanations and test logs stay out of the card. Results distinguish a local change, an opened pull request, a merge and a deployment; a local fix is not described as shipped. Before/after checks remain stored as agent-reported evidence, not independent verification. Recording a result does not run tests, create a pull request, merge or deploy anything.

Generic results can also use payload version 2 to attach a typed Sentry issue reference to each saved item. The agent supplies its selected Sentry connection and authorization generation, the Sentry organization slug, and the numeric issue ID as a string. Rails checks the connection before accepting the publication. Referenced items open as Sentry cards with the saved outcome and Open in Sentry; items without a reference keep their labelled details. A card is an agent-reported historical result, not a check of the issue's current status. Live issue enrichment is not available yet, and opening the inbox or card does not contact Sentry.

Agents are general purpose: your instructions and selected tools define their work. A draft can exist while its private repository is being initialized; wait for setup to finish before activation.

Chat with your agent

V2 messages appear immediately when you send them, and replies stream into the conversation as the agent generates them. While the agent works, its character shows a thinking animation alongside the current reasoning-summary heading when the model provides one. Between summaries, the working character periodically spins or hops. Reduced-motion settings keep the character still. You can send another message while the agent is working. The native runtime handles it using the conversation’s native queue policy: it can steer the current run or hold the message for a follow-up. Send /queue to inspect the policy, /queue steer to steer ongoing work, or /queue followup to wait until the current run finishes. If delivery cannot be confirmed, retry the original message to reuse its identity. The conversation reconnects automatically after a temporary connection loss; refreshing the page loads the saved history.

Opening a chat in the web or desktop app prepares the agent for your first message. If you see Waiting to send, the app is checking whether the agent has received your message. It keeps checking the original send while the connection recovers.

During a Spark update, the chat may say Your Spark is being updated and restarted. The app reconnects automatically and keeps checking any message you already sent.

With Composal billing, a temporary failure connecting to the model service is retried once before the reply fails. This recovery happens before sending the model request; it does not restart an interrupted response.

Inline confirmations — gated preview, disabled by default. When enabled for your organization and agent worker, a V2 agent can ask for a harmless confirmation directly in the main Agents conversation. Choose Confirm or Decline to save an explicit answer. Owners and managers who cannot answer a request see Cancel request instead, which closes it without sending an answer to the agent. Typing a reply in ordinary chat does not submit the card.

Approving writes. Before a write you need to decide on, such as deleting, overwriting or sending to other people, the agent shows what will change and waits. Long lists fold under a short summary; choose Show all to see every item. Press the write's button, such as Move 3, to approve it, or Answer in a message. If you manage the agent, Always allow approves this write and lets the agent make later writes with the same tool, as the same account, without asking. Deletes, email sends, payments, access changes, and changes that can't be undone, that the agent flags, or that run SQL are always shown first; those items also stay above Show all. To make the agent ask again, open Setup → Who can use it and choose Remove beside the tool under Always allowed. A permission stops working if the person who gave it can no longer manage the agent; the list marks it Not in effect.

The card distinguishes a saved answer from delivery to the agent. If delivery is unconfirmed, use Refresh status; do not send a replacement decision. Retry same decision reuses the exact saved operation after a connection failure. Pending retries stay in the same browser tab and signed-in account; reloading restores them. Requests expire after 24 hours, and resetting or rewinding the conversation can make an unanswered request unavailable. An older or unsupported client shows a readable instruction to open the main web Agents conversation instead of actionable controls.

Inline integration access — separately gated preview, disabled by default. An agent can propose enabling an already-connected organization account, such as Sentry, directly in the conversation. An owner or manager with permission to manage the agent reviews the account name, toolkit and authorization generation, then chooses Enable for agent or Decline. Enabling grants all tools available through that connection, including actions that may change data; it is not limited to the task mentioned in the proposal. A harmless Confirm card never grants access.

The saved receipt records access enabled at decision time, not the connection's current health or permissions. Retrying an accepted decision does not restore access that was subsequently removed. This preview does not connect a new provider account, collect credentials, configure a new MCP server or activate workflows. Those setup steps remain separate.

In the V2 message box, use the paperclip to add images or files, drop files onto the composer, or paste an image from your clipboard. Review image previews and remove attachments before sending. You can send a file without accompanying text. Attach up to 20 files per message, up to 2 GB in total. Images can be up to 25 MB, videos up to 1 GB and other files up to 250 MB. Files start uploading when you add them, and you can send once they finish. The agent finds each file on its computer and can use its tools on it. Uploaded files count toward a 25 GB limit per person and 100 GB per organization; unsent files are removed after 7 days and sent files after 30 days. Unsent attachments stay with the conversation draft; a failed send retains them for retry.

In Desktop, switching conversations stops unfinished uploads but keeps their draft tiles while the app stays open. Return and choose Retry to continue from acknowledged parts. Removing a tile cancels its upload. Restarting the app restores completed attachments only; add unfinished files again.

To send a voice message in the web or desktop app, hold the microphone button and speak, then release. You can also focus the button and hold Space or Enter. The finalized transcript sends automatically, together with any text and files already in the composer—there is no review step. Press Escape to cancel. Switching conversations or leaving the window cancels voice input. Allow microphone access when prompted; recordings are limited to one minute. Audio streams to OpenAI for transcription, and the agent receives text rather than an audio attachment. If transcription fails, nothing is sent; if message delivery fails, the transcript stays in the draft for retry.

A floating card above the text input shows microphone levels and elapsed recording time. After release, it shows transcription and sending progress, then a tick once the agent accepts the message. With reduced motion enabled, the card keeps its status and timer without the moving waveform.

For a hands-free conversation, choose Call agent beside the microphone. Allow microphone access and speak naturally; pauses send your requests to the same agent, with its existing conversation, model and tools. An OpenAI voice companion speaks short summaries of the agent’s results while full responses stay in chat. The floating call card shows captions, Mute microphone, Stop speaking and End call controls. You can interrupt the spoken reply by talking. Ending the call or pressing Escape stops the microphone and audio, not work already sent to the agent. Switching agents or conversations also ends the call; switching windows does not. Calls end automatically after 10 minutes. Calls do not send or clear any text or attachments already in your composer. If delivery is uncertain, check the chat before repeating a request.

While the agent is working, its avatar and current activity stay above the message box as you scroll through the conversation.

Choose a model and thinking effort in the composer toolbar. The picker automatically selects the model currently in use, including when it follows the agent’s saved model. If you can manage the agent, your choice becomes the agent’s default, so new conversations, reloads and teammates use it too; otherwise it applies to your messages in that conversation. When no effort is set, the picker shows the model’s default. On Enterprise agents with live model switching enabled, the saved choice applies to new chat turns as they start, without restarting the runtime. Conversations with their own model choice keep that choice.

You can save multiple personal subscription accounts for Claude, ChatGPT/Codex, or Grok. In the model selector, choose a provider and open Accounts. Select Add account to connect another subscription without replacing the one in use. Provider emails appear when available and remain visible after renaming an account. Claude setup tokens do not include an email; give these accounts a name, such as Personal or Work, to tell them apart. Choose an account and model, then select Switch account (or Use this account). The In use marker updates when the agent is ready. You can rename saved accounts, detach them from this agent, or remove them from all your agents in the same panel. Personal subscriptions are available only on private agents you own.

On desktop, open your account menu and choose Subscriptions to manage saved accounts across workspaces. Add or rename accounts, see which agents use them, or remove an account from all your agents. Connecting ChatGPT/Codex or Grok here needs a private agent online to complete device-code sign-in; Claude uses a setup token. Adding or renaming an account does not change any agent’s model. Choose the account and model from that agent’s model picker when you are ready to use it.

If a provider stops a reply because of a rate or usage limit, the conversation shows the failure and keeps it in history. Check your plan’s usage reset time, or choose another provider in the model picker. Reopening the conversation does not reset provider limits.

For Enterprise agents, enabling or disabling a skill applies through a runtime update. The API returns 202 with configuration_state: "pending" while that update runs; the returned catalog describes the last observed settings. When you approve a skill import, its approval remains pending until the update finishes and the approved files are available and enabled. Retrying the same approval keeps its original selection.

Type @ in the web or desktop composer to find a team agent or one of your own private agents by name. Choose a suggestion with its name and avatar to insert a mention chip. The chip shows the agent’s name and image; its routing handle stays attached when you edit, copy, or send the message. Use Backspace to remove a mention and Shift+Enter to start a new line.

The @ menu also lists connected apps and MCP accounts enabled for the agent. Each account shows its sharing scope and verified email or workspace when available. Select the exact account to use it for this message; mentioning it does not change saved access. Keep typing after the app name to narrow the account, such as @gmailalex for a Gmail account whose email contains alex. Saved drafts retain the selected account. If it reconnects or loses access, the agent cannot silently switch to another account.

In the web or desktop app, send /usage by itself to your private V2 agent to open a usage card in the conversation. It shows the connected provider’s reported subscription limits, percentages used and reset times, plus the current conversation’s input, output and cache token counts and model breakdown. Account limits include usage outside this agent. Select Refresh to update the report or Close to dismiss it. The command does not start a model reply or change the agent’s model.

Usage details are available only to the owner of a private agent with no shared access. Provider limits can be unavailable when the connected sign-in cannot read them; the card says so rather than displaying zero usage. Conversation counters may also be partial while the native session report refreshes. Token counts are usage information, not a subscription charge.

Open Activity → Threads and select the + at the top of the list to start another conversation with the same V2 agent. Choose Cloud, or a paired computer and a folder on it. Where a thread runs is fixed when you start it; a computer thread shows its computer beside the composer. The main conversation and threads the agent starts itself run in the cloud. The list includes both conversations and coding work. Each thread has its own link, history and unsent draft. The agent can create threads itself and review its own conversations.

On web and desktop, requests from another thread appear as Message from the Spark, not as your own message. Select the linked name to open its source conversation, or the task title to expand the brief. In the sending conversation, each call that starts a thread or messages one is followed by Created a thread and sent a message to or Sent a message to that thread's linked title. Report from links to the reporting thread; select its status to expand an available report. No report means the child's turn ended without an explicit task report; the Spark still gets the child's last reply, so a question it asked is not lost. A child that scheduled itself to continue in the same thread, for example to wait for CI, can still report from that scheduled turn before the task's deadline. A workflow waiting for that child keeps waiting for the report until its wait expires; a failed or cancelled turn, or an explicit report asking for attention, can end the wait earlier. In Activity → Threads, such a child stays under Waiting for report while it can still report, then moves to Couldn't finish with the reason, never Done, until someone writes in it. Child rows in Activity → Threads show their parent conversation, with a chat icon to open it.

Agents finish a task by default. When a minor detail can't be verified or the request leaves a small choice open, the agent makes a reasonable assumption, carries on and names the assumption in its report. It stops to ask only for a real blocker: access or a sign-in only you can provide, an action that is destructive, irreversible, costs money or others will see and that you haven't approved, or a goal that contradicts itself. Approval checkpoints still apply.

When the agent asks you a question, the conversation shows a Needs you card above the composer with the question and any answers it suggests. Pick one, or type your own and send it, and the agent carries on. Anyone who can message the agent can answer.

To tidy Activity → Threads, hover or focus a hosted thread and click its archive action. To archive several, tick their checkboxes or use Cmd/Ctrl-click, then choose Archive in the selection bar. Shift-click selects a range. Rows leave immediately; if an archive is refused, the thread returns with an inline Retry. Other threads remain usable while requests finish.

With a thread focused, Up/Down moves between rows, Enter opens it, and Space selects it. Shift+Up/Down extends a range, Cmd/Ctrl+A selects all loaded eligible rows in that group, Esc clears the selection, and E archives or restores the selection (or the focused thread). Loading more rows does not select them automatically.

To set a hosted thread aside until later, hover or focus it, click its alarm-clock action and choose 15 minutes, 1 hour, Tomorrow morning or Next week. Snoozed threads move to Snoozed at the end of the list, showing when they return. A thread returns to its usual group at that time, or earlier when you select Wake or the agent works in it again. Snoozing does not stop work or schedules. Only idle top-level threads can be snoozed, not the main conversation or threads started from another thread. Owners and managers can snooze threads.

Expand Archived at the bottom of the list to read or restore archived threads. It opens in place, with the same selection and keyboard controls; a selection belongs to either active or archived threads, never both. Archiving keeps conversation history, stops work in that thread and may disable its attached routines. Independently scheduled workflows keep running: their conversation is only where run notes are sent. Restoring does not restart stopped work or routines. The main conversation cannot be archived. Owners and managers can archive and restore; readers can view history. You can also ask the agent to archive or restore its other threads. Local coding sessions listed from your computer are managed separately.

For Sandbox threads, archiving keeps the workspace and its reserved capacity. Open Tasks → Workspaces to see which workspaces are kept and why. Keep workspace prevents automatic deletion. Delete workspace is a separate, confirmed action: it can discard unpushed files and interrupt running work, but keeps thread history. Restoring a thread does not recreate a manually deleted workspace.

Automatic deletion requires a live clean-tree check, independent verification that HEAD is on the GitHub branch, and no known or uncertain execution. Eligible workspaces stay for at least 24 hours and are checked again before deletion. New input or commands invalidate the earlier check. Dirty, unpushed, unavailable or uncertain workspaces stay kept without an automatic deletion deadline. Current execution adapters cannot prove every writer exited, so used workspaces normally need manual deletion. A workspace made for a triggered workflow run is deleted on its own schedule without these checks, and cannot be kept.

Each bot can retain up to 100 thread sandboxes, with a safety limit of 500 across the organization. Kept workspaces retain storage and may incur compute charges. Retiring means deletion is still being confirmed; capacity is freed only after both the machine and volume are confirmed gone. Seven days without use can expire execution access, but never authorizes deleting unverified files.

Before deleting a bot, delete its retained workspaces explicitly and wait for cleanup to finish. Bot deletion does not authorize discarding those files for you. Deleting the bot then deletes its own computer, including the files in its home directory.

When Devices is enabled for your organization, the desktop app connects your computer to the organization you signed into. Open Devices from your account menu to check its connection and local providers. To use your own Codex, Claude or Roder account, install and sign in to that CLI on your computer, then ask the agent to use it. Roder requires version 0.4.10 or later for process cleanup and interrupted-session recovery.

Scheduled check-ins starts on when you add a computer. It lets your private agents check the computer’s connection during their hourly heartbeat or a custom routine. Open a computer in Devices to change its setting. Scheduled coding work requires separate permission.

Choose Stop to interrupt local work. A new request waits for the previous process to finish cleanup, then continues in the same local provider session. Stop does not undo file changes already made. An uncertain earlier request keeps its receipt and is not automatically repeated; if cleanup cannot be confirmed, that session remains unavailable for new work.

V2 agents keep durable memory across their conversations. When a thread grows long, older messages are summarized instead of discarded, and the agent can search and reopen the original messages from any of its own threads. An agent cannot search another agent’s conversations. The agent can also save important context to its memory notes. In Activity → Threads, select a hosted thread to read it and reply alongside the current conversation. Its composer has a separate draft. Use the back arrow to return to the list or Open as main conversation for the full workspace.

The agent’s main conversation keeps a scratchpad for work that carries across turns. Ask the agent what’s still open or tell it to drop a commitment. The agent keeps the next step and relevant thread or PR with each item and closes it once the work is verified or cancelled.

A proactive check runs every hour in its own Proactive checks thread. It uses the agent’s saved role and memory to review open commitments, follow up on stalled threads it started, and verify finished work. When something needs your attention, it posts one short message in the main conversation. Otherwise it stays quiet. Ask the agent to change or disable that schedule in chat.

Select the agent’s name in a V2 conversation to open its sidebar. Activity → Automations lists the routines the agent has created under its saved workflows, their schedules, next run, and last result. Owners and managers can switch each routine on or off. The agent’s proactive check is labelled Agent heartbeat. Ask the agent in chat to create or change a routine, then use Refresh to see the latest settings. From any conversation, the agent can list, inspect, edit, run, pause, resume or remove its own routines, including routines created in another conversation. It can inspect their run history and last error. Access stays within that agent and workspace; personal account permissions still apply. A failed scheduled run posts a notice in its owner conversation. While the agent is running, a separate check also posts a notice when a routine is overdue by more than twice its interval. Check history for saved work before retrying.

Owners and managers can change the Utility model on the heartbeat row. Automatic uses Haiku with Claude and Luna with GPT or Composal billing when the active route offers it. A model you pick applies to the next heartbeat. If that model is unavailable on your current account, the heartbeat uses the automatic choice.

To run a saved Temporal automation on web or Desktop, open Activity → Automations → Saved automations, select the automation, and choose Run now. Enter any inputs when prompted. The automation runs as the agent using the version shown on the page. Its new run opens in Run history, where you can follow its steps and respond to approvals.

If an automation turns off after repeated failures, ask your agent to check its run history. If the conversation it runs in was archived, restore it from Activity → Threads. Once the issue is fixed, turn the automation back on in Activity → Automations.

Open Activity → Library. Its Pull requests section shows PRs the agent has created or worked on across all threads and subagents. Each row shows the current GitHub state: open, draft, merged, or closed. Select the title to open GitHub, or the thread or subagent name to open its conversation. Use Refresh to check again and Check older activity to find PRs in earlier conversations. GitHub and shell PR tool activity links PRs to conversations; a PR mentioned only in chat does not appear. PRs are shown only for the agent’s currently selected repositories. If GitHub is unavailable, the row keeps its links and shows Status unavailable. Earlier tool results that were already omitted from history cannot be reconstructed.

Agents can wait for checks, a submitted review, a merge, or an Actions run without repeatedly reading GitHub. The agent pauses and resumes in the same conversation when the event arrives or its timeout expires, including in a delegated thread. A timeout is not evidence of success or failure. Authorized automatic merges stay pinned to the supplied commit; a later push stops that intent and needs a new decision. When event delivery is unavailable, agents read status at most every five minutes.

If GitHub returns only part of a PR status response, the agent keeps the available evidence. If no usable PR data is returned, it tries a REST read. The snapshot marks missing sections with missing_sections and complete=false; incomplete evidence cannot authorize an automatic merge. Refresh failures retry with bounded backoff, and the wait still resumes at its timeout even when GitHub cannot be refreshed.

Library also lists files the agent has published, grouped by date. Open images, audio, and videos for a preview, or download any file. When a reply links an image from the agent’s Library, the conversation shows the image inline; select it to enlarge or download it. Other Library files stay as links. Images generated by the agent are saved when generation finishes. Ask the agent to save other finished outputs to its library; it can publish a file from its own remote workspace or create a text file directly. Published files use private durable object storage, so they remain available when the remote workspace stops. Access follows the agent’s sharing settings. Existing workspace files appear after the agent publishes them.

Composal Pages

Your organization's first page starts HTTPS certificate setup for *.{organization}.composal.page. Issuance can take a few minutes; check HTTPS status in Library. The built-in web browser shows a waiting page and opens your page automatically once HTTPS is ready. Later pages share that certificate, and removing every page keeps it available for future pages under the same organization slug.

V2 Codex agents include the composal-pages skill for building and updating hosted artifacts. Type $composal_pages in a message or choose it from the $ skill picker. It covers publishing pages and live apps, Durable Object and KV storage, secrets, Composal sign-in, MCP connections and team apps.

Ask a V2 agent to publish a page, app, API or MCP server and it deploys it to Composal Pages at https://{name}.{organization}.composal.page. A site can be static or run code with WebSockets, Durable Object storage, KV and secrets. Each site is public, organization (members sign in with Composal) or private (only the person who owns the agent). Open the agent's side panel and select Activity → Library. Under Composal Pages, you'll find the sites you can open, with their visibility, version and HTTPS status. In Composal Desktop, select a site to open it in the built-in browser with your desktop sign-in.

The agent opens its own private and organization sites as itself, so it can check what it published and use an MCP server it serves from a site without extra setup. Site code receives the viewer in the com-page-viewer-id header and whether it is a person or an agent in com-page-viewer-kind. For a program that needs lasting access, the agent can create an access key that it sends as Authorization: Bearer <key>; keys act as the agent and last one year. The agent can revoke them, and they stop working automatically when the agent is paused or archived or its owner leaves the organization.

When an agent publishes a Composal Pages team app, every agent in the organization can find and use it on its next turn. If the app serves MCP, each agent calls the endpoint under its own identity. Agents can ask for the full list of team apps at any time.

Agents → Integrations → Team apps shows the publishing agent, source thread, owner, and MCP endpoint. Choose Install on agent to record an optional manual install for an agent you own or manage. Only organization or public Pages can be published as team apps. Ask the publishing agent to unpublish a team app before making its Page private.

For coding work, the agent delegates to a coding session. Coding sessions appear alongside its other threads. The coding session uses the agent’s remote workspace to read and write project files and run commands. Ordinary chat and model inference run outside that workspace, so sending a message does not wait for a sandbox to start.

V2 currently provides chat with persistent conversation history and an isolated remote workspace. Creating your organization’s first V2 agent starts its managed worker. The page shows Provisioning your first agent… until the worker is placed and ready, then chat becomes available. Later V2 agents reuse that worker. If provisioning fails, an owner or manager can retry from the agent page. V2 app connections use the organization integrations described below. Owners and managers can select V2 work repositories under Setup → Computer on web and desktop, granting read or write access. The V1 settings editor remains available on V1 agents. Existing agents continue to use V1.

For the Vex and e2e experiment, Agents → Integrations (/:org/agents/integrations) opens a searchable catalog of supported apps with provider logos and connected accounts. It opens inside the Agents workspace, so your agents stay in the sidebar. Its Apps, Sandboxes and Team apps tabs each open one kind of integration. Apps starts with Connected apps, Composal's own Slack, GitHub and GitLab apps, and Popular apps whose agent tools Composal has reviewed. Agents reach Slack and GitHub only through Composal's own apps. The Composio versions can't be connected or used; Composio GitHub leaves the catalog once no account remains to remove. LinkedIn is available both as Composal's LinkedIn messages and as Composio's LinkedIn app. Repository testing and team notifications stay under Verify → Integrations. Apps connects accounts that individual agents can use for their tasks. An organization admin connects an account once using Composio’s authorization link. The connection belongs to the organization and can be enabled independently for each V2 agent. V2 Slack access uses the Composal Slack app described below; Composio Slack accounts cannot be enabled for V2 agents.

In the organization catalog, choose Connect account or Manage accounts to open the app’s account dialog. Use Add account to connect an account, and Refresh after finishing authorization in the new tab. Connected accounts offer Disconnect. An app counts as connected only once its sign-in finishes; until then its card shows Finish signing in, and the account's Continue starts the sign-in again. Expired, revoked, or failed accounts offer Reconnect when available. Slack uses its native setup flow and can be disconnected while setup is pending. Open a V2 agent and select Integrations to enable its organization accounts. Its Apps, Channels and Sandboxes tabs mirror Agents → Integrations; admins add an MCP server with Add MCP server. Authorization opens separately so the chat and unsent draft stay in place. Once connected, enable the account for the agent. Disabling it removes the agent’s access immediately. Disconnecting or reconnecting an organization account invalidates previous agent selections; enable the current authorization again before use. Use Reconnect beside an expired or disconnected account to authorize that same account again. Search finds apps and connected account labels; account lists load in pages.

In the opt-in chat integration experiment, an agent can offer Connect for an eligible catalog provider directly in the conversation. An organization administrator opens the secure provider tab and completes authorization there—never enter credentials in chat. If the browser blocks the tab, allow popups and try again; no account is created by the blocked click. The callback automatically verifies the connection and closes the authorization tab where supported; the original chat updates its connection status. Direct returns and browsers that cannot close the tab return to the same agent and conversation instead. If verification fails, choose Retry verification, or Return to conversation to recover the setup. Choose Check connection in the chat if needed. Reloading the chat preserves the same setup account. A lost authorization link must expire before Retry connection can start a new attempt on that account. Connecting does not grant agent access: review the verified provider identity when available and explicitly choose Enable for agent. Details shows the exact account and generation. Cancelling the chat request does not undo provider authorization already completed. This experiment is disabled by default; the organization catalog remains available.

With catalog-enabled chat setup, ask an agent to find a supported Composio app by name. It checks existing accounts first, then reports whether the provider can be connected or needs operator configuration. Providers without managed authentication may need an operator-provided Composio auth config before setup is available; unsupported authentication is not offered as a working connection. Credentials are entered only in Composio’s secure tab. Apps that need no authentication still require a separate Enable for agent decision. Cards may have provider-specific layouts, but authorization, account verification and explicit enablement are shared. Direct Spacesheep keeps its existing setup path; registering a custom MCP endpoint is not part of catalog chat setup.

With chat setup enabled, ask an agent to connect Slack and it shows a Slack card in the conversation. If your organization hasn't added the Composal Slack app yet, an organization admin can choose Set Up Slack. Otherwise, choose Connect Slack Account to link your own Slack account. Slack opens in a new tab, and the card updates when you finish. Choose Continue to tell the agent which workspace is connected. To publish the agent in a channel, use its Slack settings as described below. After that, the agent can send Signals alerts to the channel.

Talk to named agents in Slack

Open the V2 agent’s side panel and choose Setup → Slack, then Set up. The setup shows one step at a time, each with illustrated references you can enlarge and links to the matching page of the app in Slack. Other account connections are under Setup → Integrations. Install the Composal Slack app and connect your own Slack account using Set Up Slack or Connect Slack Account. This is the agent’s Slack connection; it does not use Composio.

Choose Prepare to give an active V2 agent its own Slack bot. An organization admin who manages the agent completes setup. For a private agent, the owner sets up the bot and must be an organization admin. Private and shared agents can both receive DMs and be published in Slack channels. If the bot was set up while the agent was shared, the owner creates a new Slack app to reconnect after making the agent private.

  1. Click Create app in Slack. The generated manifest fills in the bot name, permissions and Composal event endpoint. Create it in the same workspace as the organization’s Composal connection.
  2. In Slack, select Install to Workspace and approve the app. Copy its Bot User OAuth Token from OAuth & Permissions and its Signing Secret from Basic Information → App Credentials into the protected Composal form. These credentials are encrypted and never returned in API responses.
  3. Click Connect bot, then choose Open Event Subscriptions to go to that page of the app in Slack, and enable events and retry verification of the prefilled Request URL. Wait for Verified, select Save Changes, then choose Check connection. If the signing secret was wrong, choose Replace credentials. The bot cannot be published until Slack has sent a correctly signed verification request.
  4. Under Where should it reply?, tick any mix of Direct messages, Public channels, Private channels and All channels the bot is in, then click Save. Existing bots start with direct messages and both kinds of channel on. The steps below follow what is saved. For direct messages, open the bot under Apps in Slack and send it a message. With All channels the bot is in, the agent replies in every channel of a ticked kind that the bot is a member of, so you only send /invite @bot in a channel instead of publishing it here; a Slack Connect channel still needs publishing. To publish one channel, search for it and click Publish; the bot joins a public channel itself. A private channel appears in the list only once the bot is in it: send the shown /invite command in that channel in Slack, then refresh, select it and click Publish. Turning a kind of channel off stops replies in channels of that kind that are already published. A channel shared through Slack Connect asks whether people outside your company may see replies before it can be published. Inviting the bot as a linked organization admin who can manage the agent also publishes it in Composal. Existing apps need the channels:join bot permission and a reinstall for automatic public-channel joining, and the member_joined_channel bot event subscription for invite syncing. Mention the bot in a published channel to start a thread.

Each agent has its own Slack bot identity. This setup needs no user groups, partner provisioning or distributed OAuth callback. Repeat it for additional agents. Incoming requests include the parent message and thread replies up to the request, plus up to 15 recent channel messages. Supported images attached in the thread are included as image inputs (up to five images, 4 MB each and 8 MB total); other attachments are named but not read. Images the agent attaches to its reply are posted in the thread after the reply (up to ten, 8 MB each). Existing agent apps need the files:read and files:write bot permissions and reinstallation to load and post images. Context limits and unreadable images are reported to the agent; it can use Slack reading tools for more context. Use Composal for other attachments and generated files.

New agent apps also appear in Slack's Agents entry point. For an existing agent app, enable the Agents feature in its Slack app settings, add the assistant:write bot permission, and reinstall the app to approve the permission. Slack workspace availability and access to the Composal agent still apply.

Replies use Slack formatting for headings, bold text, links and lists. Tool activity stays in the Composal conversation; Slack shows reply text and actionable prompts without repeated tool labels. Replies use a still of the agent’s current published character, including its saved Pixel shape, color, and accessory. After publishing a channel, Agent picture → Download provides a PNG to upload as the app icon under Slack’s Basic Information → Display Information. App-directory icons require a manual update when the character changes; reply avatars update automatically.

Disconnect bot → Disconnect revokes the agent’s stored credentials and stops pending replies. Reconnecting requires verifying its Request URL again and republishing its channels. Requests and deliveries from before the credential change are not replayed under the new credentials. Disconnecting one agent leaves the shared Composal app and other agents connected.

Slack Connect participation remains a per-channel setting. When you select a Slack Connect channel, turn on Let people outside your company see its replies to publish it, or change the channel’s switch later. Everyone in a published channel can see replies, including external participants in Slack Connect. Sending requests requires a linked account in the installed workspace and current permission to message the agent. Paused, archived or revoked agents cannot run through Slack.

Existing shared-app handles continue to work. They use Slack user groups through @Composal and require a plan and workspace permissions that support user groups. /composal agent connect agent-slug agent-handle :robot_face: publishes a shared handle; /composal agent list, /composal agent disconnect agent-handle and /composal agent slack-connect agent-handle on|off manage it. These shared handles have no separate DM inboxes. Preparing and connecting a dedicated app replaces that agent’s shared identity; it does not silently fall back to the shared app after disconnecting.

Ask a V2 agent to list its published Slack channels, read recent messages, or send a message. Its Slack tools can access published channels, every channel its bot is in when All channels the bot is in is on, and authorized DMs established with its own bot. Sends return a delivery receipt; the agent checks its status before claiming a message was sent. When Slack or the agent's reply settings refuse a send, the agent gets the reason and what to do, such as inviting the bot to the channel or reinstalling the app for a missing permission. If delivery is uncertain, inspect Slack before sending again.

Post in Slack as yourself

Setup → Slack offers two ways in: As the agent, its own bot described above, or As you. As you lets the agent post with your own Slack account, under your name, without a Slack admin. Only the agent’s owner can choose it. It follows the rule for your other personal accounts: it always works while the agent is private, and on a shared agent only if your organization lets shared agents use personal accounts, since anyone chatting with the agent can then make it post as you. Sharing a private agent stops it unless you keep your Slack account in the share review. Choose As you, then Connect your Slack account and sign in to Slack in the window that opens. If you already connected Slack for your own apps, that account is used straight away.

Two switches apply to everything it sends as you:

  • Ask before sending (off by default). Each message waits in the conversation as a card showing the channel and the exact text. Choose Send to post it once or Don’t send to drop it. Only you can approve it.
  • Show “Sent using Composal” (on by default). Adds an unlinked “Sent using Composal” footer under each message.

Disconnect stops the agent posting as you; your Slack account stays connected for your other apps.

Repeat tasks with workflows

Workflow proposal and run cards appear in web chat and Composal Desktop on Mac and Windows, including the thread pane. On desktop, expand a run card to inspect its steps and output, retry a step when offered, or send an answer when the run needs one. After a chat approval starts a Verify run, its desktop card shows progress and the result; choose Open run in Verify for the live browser and recordings.

Ask a V2 agent to turn a repeatable task into a workflow. The agent proposes it first: a card in the conversation shows its ordered steps, the model for each, conditions and approval or input checkpoints. Nothing is saved yet. To save it, choose Save workflow on the card, or ask the agent to save it. Either way the saved file is exactly the proposal you reviewed. Select a step to read its full prompt. Before saving, you can choose the model and reasoning its agent steps use from the card; the card shows the changed proposal, and that is what saves. To change anything else, tell the agent what to change and review the new proposal. A proposal cannot be saved if the workflow changed after it was made, or if it no longer passes its checks; ask the agent for a new one. Only people who can manage the agent see Save workflow.

A workflow can also start on its own, from one of the agent's event subscriptions, such as Sentry errors, or on a schedule. The card then shows what starts it above the steps, and saving the proposal turns that on, so a separate step isn't needed. When the agent isn't subscribed to those events yet, the proposal includes the new subscription, and saving creates it and the trigger together, or neither. A schedule that repeats every few minutes or hours counts from when you save. If it can't be turned on, for example because the subscription was removed, the workflow is still saved and the card says it won't start on its own. When nothing else has changed, choose Turn on on the card to try again; otherwise ask the agent to set it.

Open Activity → Automations beside the conversation and select a saved workflow. A run card’s Change… button opens that workflow directly. Choose View source to see the saved definition. Reopen Automations to see edits the agent has made. The diagram shows the saved workflow. Select a recent run below it to see the recorded steps and their results. People who can manage the agent can choose Edit source to change the file. Saving checks the source against the rules for hosted workflows and fails if the file changed after you opened it, so reload the latest source and edit again. Saving does not run the workflow.

Ask the agent to run the saved workflow in chat. The run continues in the background, and a run card appears in the conversation when it finishes or pauses at an approval or question. Reply with your decision or answer so the agent can resume. Results pass between steps, and completed steps are kept. Editing a workflow changes future runs; a run that has started keeps its original definition, and the agent says so when you edit one mid-run.

If a workflow needs approval before making changes, have it prepare the changes in one step, pause at an approval checkpoint, and apply them in a later step. Approve the checkpoint on the run card. A review card from an ordinary chat cannot resume a workflow.

When a step can't finish without you, for example because it needs information only you have or access you must grant, the run waits and its card shows Needs you with the step's question. The same card appears at the end of the agent's main conversation, above the composer, even when the run works in a thread of its own; Open thread opens that thread, or Open run shows a run that has none. People who can manage the agent can type an answer on the card and send it, or answer the agent in chat. Once answered, the card folds to one line saying what you answered. The step runs again with the answer and gets the run's whole budget again, and the run carries on. A run that waits more than 7 days stops and says so. When a run stops without finishing, because a step failed, its worker went away, it used its budget or nobody answered in time, the agent's owner gets a Stopped card in the main conversation naming the workflow and why it stopped, with Open thread or Open run and Dismiss. Composal Desktop also shows a system notification when notifications are on. Retrying the run clears the card, and it goes away on its own after 14 days. A run that finds nothing to do, such as a duplicate of an earlier event, finishes normally; its run detail says why.

Automations lists recent runs with each step's status, output and spend. A failed run's detail says a step failed; open Error details for the raw error. People who can manage the agent can choose Retry step on a failed, interrupted or over-budget step; earlier steps are not run again. If you or the agent fixed the workflow since, the retry uses the fix when the steps before it are unchanged. Retrying an over-budget run lifts that run's own budget. Coding steps use separate sessions of the same agent and share its remote project workspace. On a private agent with Sandbox threads turned on, each run a trigger starts works in a workspace of its own, so two runs never change the same checkout. That workspace is deleted as soon as the run ends and nothing can continue it: when it succeeds, is cancelled, or stops with no step left to retry. A run that stops where it can go on keeps its workspace for seven days from then, and retrying, answering or approving it keeps it for another seven. Once the workspace has been deleted the run can't continue: it no longer offers Retry step, and approving it ends the run, so run the workflow again. An agent's runs can have 25 such workspaces at once; a run started beyond that, or while many finished runs' workspaces are still being deleted, uses the agent's shared workspace. A run carries on through routine restarts: a step that was cut off continues in its own session, and a brief model service error gets one more try. Check the step's output before relying on work that was interrupted.

When thread delegation is enabled for your organization, a background workflow step can start a child thread with its own repository sandbox and selected model. Scheduled and event-triggered runs act as the bot, using only its configured repository access and eligible platform models; they do not borrow a person's subscriptions or permissions. This works for shared bots too, but only through the bot-authorized workflow: ordinary chat and chat-started workflows still need a private bot to create sandbox threads. Chat-started runs keep the original sender's authority. Each logical step can create one child; retrying that step returns the same creation rather than starting another. A thread wait suspends the step and resumes it with the child reports, without starting a separate chat turn. Existing task and sandbox limits still apply. Workflow-started threads cannot start another workflow or install a trigger. Archiving the bot, disabling delegation or removing its repository access prevents further use of the affected workflow sandboxes.

For steps that must verify their prerequisites, add --prerequisites to openclaw.agent. The step must return missing_prerequisites, either an empty list or the tools, access, dependencies or evidence it lacks. A nonempty list stops the run even if the agent reports success or nothing to do. When only you can supply what is missing, the step asks you and the run waits as Needs you; otherwise the step fails and the agent that runs the workflow works around it or tells you. Unfinished checks are not prerequisites, and the agent checks whether its own browser is already signed in to an app before listing access to it. Missing dependencies are not a successful no-op; coding threads should install and run the repository's test setup in their own sandbox, then report the exact checks and results.

Ask the agent to start a workflow on a schedule, or on each event from one of its event subscriptions. Triggers in the panel lists them, and people who can manage the agent can remove one. A trigger stops when its workflow file changes; ask the agent to set it again after an edit. A run can have a dollar budget and a running-time limit. A trigger can also cap its spend per day, week or month. Events that arrive while a trigger is paused, or after it reaches its daily limit, are listed under skipped today with Run now; when the daily limit skips events, the conversation it reports to shows Needs you in the thread list until you raise the limit, run them, or the day resets. The reset time shows in your local time. Spark checks dollar budgets before each step, so a step can finish over budget. Spark stops a run as soon as it reaches its time limit. Time spent waiting at an approval or question does not count. Steps whose model reports no cost are priced at list rates.

People who can manage the agent can choose Add from catalog to add a vetted workflow: bug fix, bug fix and merge, pull request review or failing CI fix. The dialog shows any repository access the agent is missing. A workflow merges a pull request only when it says to, and the agent checks its conditions, such as passing checks and a review score, against the exact commit it merges. Bug fix and merge merges only at a Greptile score of 5/5 with every check passed, and its run records the score and the commit it merged. Otherwise it leaves the pull request open and asks you. It tells you when the change touches security, without waiting for you.

Each step of a catalog workflow runs on the agent's own model. To use a different model for a step, ask the agent to change the workflow and name the model; it must be one the agent has.

A workflow can repeat a group of steps, such as a fix and its review, until a condition holds, for up to five rounds. The run card lists every round's steps. In the bug fix and failing CI fix workflows, the fixing step says whether its change's full effect is obvious at a glance, such as a comment or wording edit, and the run card shows its answer. An obvious change skips the review. Otherwise a fresh session reviews it. Problems with one clear fix are fixed and reviewed again, for up to three rounds in all. Problems that need a decision, or that remain after the last round, wait for a person before anything is published.

Work with other agents

Type @ in the web or desktop message composer to find a shared agent in your organization by name or handle. Use the arrow keys and Enter or Tab to insert the handle, or select an agent from the suggestions. For example, send “Ask @windy to review the Windows installer.”

Agents can also reach out to teammates when that helps with work you have already assigned, without waiting for another prompt. The recipient works in a separate conversation in its Threads, and the requesting agent reads the reply and continues. A mention identifies the teammate; it does not forward the whole chat or attachments. Agents can contact active shared teammates they are authorized to message in the same organization. When working on your current request, they can also message your own private agents in that organization. This shares the request and its reply with the sending conversation; it does not grant access to the private agent’s existing threads, memory or settings.

Share with your organization

In the web sidebar, choose All, Private or Team to filter the agent list. Private includes agents you own and private agents you have been granted access to; Team shows agents shared with your organization. The filter applies across all pages and stays in the URL when you reload or share a link. An open conversation stays open when you switch tabs, but its agent disappears from the sidebar if it does not match the filter.

New agents are shared with their organization by default, including future members. Current organization members can view their history, memory and files, and send messages. The owner and explicitly granted managers control settings, activation and other management actions. Sharing does not grant management rights to organization administrators.

Use Setup → Who can use it to change access. Private agents remain available only to their owner and explicitly granted members. Existing agents become organization-shared when this feature rolls out. Owners and managers can switch them to private afterward. Organization sharing never makes an agent public on the internet.

Messages and workflows use the agent's configured tools and selected app accounts under its owner's execution identity. Only the owner can change those account grants. Share agents whose configured capabilities and retained information are appropriate for your organization. Changing an audience can invalidate provider-event consent; the owner must review and authorize the new audience.

Add and publish agents in the marketplace

The marketplace lives at composal.com/marketplace for everyone; Agent marketplace on the Integrations page (the grid button at the foot of the Agents sidebar) opens it. Signed in, it shows your active organization's catalog: public agents plus your organization's own listings, with Your organization to filter to them and Publish an agent. Browse ready-made V2 agents by category or search. Each category has its own page, such as /marketplace/tag/engineering, and each listing has a readable address, such as /marketplace/ci-autofixer. From Composal collects the agents Composal maintains, such as CI Autofixer, CI Speed Tuner, Standup Scribe and PostHog Morning Digest. Each listing shows the instructions the agent starts with, the memories it already knows, the skills it can run and the apps it uses, including which of those apps your organization has already connected.

Select Adopt on a listing's card, or Adopt this agent on its page, to create your own private copy. On a listing page the Adopt button follows you as you scroll. It starts with the listing's instructions as its SOUL.md, its memories in MEMORY.md and each skill under skills/. Your organization's existing accounts for the listed apps are turned on for it; connect any missing app from Integrations. The copy is yours: later edits to the listing do not change it, and you can share it with your organization like any other agent.

To publish, open an agent you manage and select Publish to marketplace, or choose Publish an agent in the marketplace to start from scratch. Publishing from an agent starts with its current instructions and enabled apps; add memories and skills before you publish. About this agent is an optional Markdown write-up shown on the listing page: what it does, how it works, the apps it needs and what it won't do. Choose who can find it:

  • Your organization: members can find and add it.
  • Anyone with the link: hidden from the catalog; anyone with the share link can open it, even signed out, and add it to their own organization.
  • Public: listed in every organization's marketplace and on the public composal.com/marketplace, where anyone can read it without signing in. Adopt there adds a private copy to your active organization and opens it; if you're signed out you sign in first and come back to the page. Share links for organization-only listings ask members to sign in.

A listing is a copy too: editing the source agent later does not change it. The publisher and organization administrators can edit a listing, copy its share link or remove it. Removing a listing hides it and disables its link; agents already added keep working. Listings never include account credentials or conversation history, but anything written in their instructions, memories and skills is visible to everyone who can open them, so leave out secrets and private details.

Ask a V2 agent to use composal-marketplace-publish for guided publishing. It helps select reusable instructions, memories, skills, connected app requirements and Composal Pages core to its workflow, then opens the existing publishing form for your review. You choose the contents and visibility before selecting Publish.

For each Page you include, the agent prepares a separate code template and checks it for embedded private data, uploads, exports and credentials. Select the prepared apps under Composal Pages apps in the form. The listing pins that revision. Each adoption creates new organization apps with separate Workers and empty KV/Durable Object storage before queued agent work starts. Live records, secrets, access keys and publisher account connections are never copied. The new owner configures required secrets and connects their own accounts. Review the template's code and static assets too: records embedded directly in a report or HTML must be removed before publishing.

Choose what it can use

Each V1 agent has its own private repository for configuration and durable state. Its work repositories are a separate set you select. Adding a work repository gives read and write access; repository permissions and branch protections still apply. Instructions and memory stay with the agent rather than being added to each work repository.

GitHub-connected work repositories also give the agent an authenticated gh api tool. It can read pull requests, issues, checks, files and commits, and use the repository's granted write permissions for actions such as comments and reviews. This tool works directly in chat without starting a sandbox or connecting a separate GitHub account. Credentials stay on the platform and are restricted to the selected repository.

V2 agents use the same repository-scoped GitHub tool through their connected tools. No project or source import is required. Open Agents → Integrations → GitHub to connect a GitHub organization and see its configured repositories. Open an organization to manage GitHub access and refresh its repository list, then grant each agent the repositories it needs in Computer settings. They can create pull requests, manage issues, review PRs, inspect checks, and use GitHub’s file and Git APIs within their selected grants. Ask the agent to list its work repositories before starting. Open Setup → Computer on web or desktop. Search the repositories allowed by your connected GitHub App, add the ones the agent should use, choose Read or Read and write, and select Save repository access. New write grants default to * · All branches. You can instead choose All except the default branch or Specific branches with exact branch names. Excluding the default branch checks GitHub before each file or ref write, so renaming the default branch does not bypass the restriction. Branch-restricted grants keep direct Git pushes and automated merges disabled; agents can still prepare changes through GitHub’s file/ref APIs and open pull requests for review. Remove a repository and save to revoke its access. Reload saved access discards unsaved edits and loads the latest grants. These settings are also available through the V2 repository API. The agent can then subscribe to incoming GitHub events with a purpose, event types, destination conversation and daily limit, and list or remove those subscriptions in chat. New subscriptions receive future events; they do not replay older events. Incoming events require the platform’s integration-event feature to be enabled and the GitHub App to deliver the selected webhook types. Removing a repository grant or stopping a subscription prevents queued events from waking the agent. GitHub writes with an uncertain response are reported for inspection before another attempt.

Where inline chat requests are enabled, you can also ask a V2 agent to add an organization repository without opening settings. For example: “Add ComposalAI/vex with read access,” or “Allow writes to ComposalAI/vex except its default branch.” The agent searches connected repositories and presents a Repository access request with the actual repository, permission and write branches. An owner or manager must select Allow repository access before the saved grant becomes available for subsequent coding work. Conversation alone is never approval. Decline leaves access unchanged. If settings change while a request is open, ask for a fresh proposal. A confirmation replaces only that repository's grant, preserving the others. Revoke access in Setup → Repositories as before; retrying an old approval cannot restore it.

Repository access requests can be approved in the desktop chat, including its thread pane. If saving a decision loses its connection, use Refresh status or Retry same decision on the card; reopening the conversation retains the original decision for the same signed-in account.

In a repository Sandbox thread, native commands and coding tasks use that thread's machine and start inside its checkout. The agent receives the recorded repository, checkout path and setup state, plus the environment's machine size. If setup has not recorded a checkout yet, the first native command prepares it. Explicit command working directories still work. Ask the agent to start the recipe's services with ensure_services and share the returned private preview links. The sandbox_runtime tool can inspect this machine but cannot resize or replace it; change the repository recipe and prepare a new environment instead.

On machines in US regions, each service port has a stable address such as p3000-….us-was-1.preview.composal.page. Opening it signs you in with your Composal account, and only people who can manage the agent can open it. The address stays the same for the life of the thread, and the service receives it as COMPOSAL_PREVIEW_URL, so it can build links and allow the host. A preview that has had no use for 20 minutes goes to sleep so its machine can stop: an open tab's live-reload connection does not count as use, and the page shows Wake to start it again. Pages that poll the server on a timer count as use and keep the machine awake.

To test a recipe change before it merges, push it to a branch and check that branch. In the agent's Setup → Repositories, enter the branch in Check setup on a branch and choose Check branch, or run com agent env prepare AGENT REPOSITORY --branch BRANCH. The agent builds the recipe on that branch and tests the image on a fresh machine in a new thread, where it reports what passed or failed. Nothing is promoted, so existing and new Sandbox threads keep the current environment until the branch merges and the default branch is prepared. A branch check needs an agent only you can use, and a repository runs one check or setup at a time.

Preparing the default branch reports the build it started. While that build runs, the answer is Building, even though Sandbox threads still start from the previous ready environment. If the newer recipe fails to build, the environment stays ready on the previous one, and the agent is told in each Sandbox thread which recipe failed and why, with the end of the build log. Prepare builds it again; fix the recipe in a pull request when the log points at a step in it. A build that fails because a registry or the network was unavailable is retried automatically within its 20-minute limit.

A thread sandbox started from a repository environment keeps its checkout, dependencies and build output on a separate 32 GB workspace disk, so they do not use the machine's memory. The disk is deleted with the machine. A machine created without this disk keeps its files in memory for as long as it exists.

Blaxel repository sandboxes with a supporting runtime report low memory and disk space in command results and the thread's Sandbox resources notice, even when tool activity is collapsed. A warning means at most 10% of memory or disk space was available when the machine was sampled before or after a command. Reduce parallel work, remove disposable build files, or select a larger machine.class in the repository recipe and prepare a new environment. These samples are not continuous monitoring; a short-lived peak can occur between them.

Fresh-machine checks retain the first recognized failure context and report observed process signals and kernel out-of-memory kills when available. An exit code of 137 alone is not proof of an OOM kill. If the supervisor itself is killed, its termination receipt may be unavailable.

If a reply stops because the AI service is unavailable, rate limited, or out of credits, the chat identifies that cause when available. Failed replies are not retried automatically. Completed tool steps remain in the conversation.

V2 subscriptions process matching events in isolated background runs. The notification conversation is a destination for attention reports, rather than the execution context. Background work waits while the agent is busy, has a five-minute execution timeout, and keeps routine results out of your conversation. GitHub subscriptions can filter exact actions such as opened or review_requested before starting a model run.

When you ask the agent to wait for a GitHub check, review, merge, or Actions run, the agent resumes in the same conversation when the event arrives or the wait times out. The chat shows the agent's follow-up. The status snapshot goes directly to the agent.

Ask the agent to subscribe to Signals with signals_subscribe. Choose signal kinds, minimum severity, source providers and hosted apps, plus a purpose, notification conversation and daily event limit. For example: “Watch new error signals for this app, investigate relevant failures in the background, and notify me only when you need a decision.” Subscriptions receive future events only and require integration events to be enabled.

To get alerts in Slack, ask for it when subscribing, for example “Send CVE alerts to #security.” The agent saves that channel as the subscription’s Slack destination. It must already be published in the channel. Each attention report is then posted there as the agent, once, and still appears in the notification conversation. If the agent is later removed from the channel, reports continue in the conversation with a note that Slack couldn’t be reached.

The shared Composal app and dedicated agent bots feed Slack message signals into this centralized stream. Publish the agent in the channels it should follow, then ask it to subscribe to those channel IDs with a clear purpose and daily limit. For example: “Follow this support channel for unresolved signup problems, investigate relevant cases quietly, and notify me when a decision is needed. Reply in the source thread only when you have an authorized, useful followup.”

The agent uses signals_subscribe with filters.slack_channel_ids, kinds: ["slack.message"] and sources: ["slack"]. slack_channels lists its published channel IDs. Broad Signals subscriptions do not implicitly receive Slack messages. New messages, including thread replies and other apps' bot notifications, are eligible; Composal's own replies are excluded to prevent feedback loops. DMs, old messages and message-edit/delete events are not ingested in this release.

Slack signals contain references only. slack_read_signal reads the captured message through current channel permissions; slack_read_messages reads more recent channel context and includes reply counts. Pass the parent message timestamp as thread_ts to read its replies, and use next_cursor as cursor with the same channel and thread timestamp to continue through a longer thread. The same published identity sends authorized followups. Disconnecting the channel or app, disabling Slack access, or retiring the subscription stops pending work. Slack Connect participation remains a per-channel setting. Captures expire with the normal Slack receipt retention and may differ from subsequent edits in Slack.

Each background run checks relevance against the saved role and subscription purpose before doing work. Unlike exact filters, this semantic check uses model tokens. It records an ignored, informational, completed or attention outcome with event_report. Only attention queues a concise follow-up after current conversation work; it does not steer or abort the current run. A native execution failure is also recorded for attention if the run could not report an outcome.

Background runs stop after five minutes. For longer authorized work, such as fixing a Sentry issue and opening a pull request, the run hands the task to a coding child, reports delegated, and finishes. The event stays open quietly until the child reports the final outcome with the same delivery ID; a pull request ready for review is an attention result. The child shares the event's admission, so retiring the subscription also stops it. If no outcome arrives within six hours, the event is recorded for attention.

Ask for event history with event_deliveries_list; native automation history retains the execution details. There is no scheduled digest in this release.

Stop a subscription with github_unsubscribe or signals_unsubscribe. Runtime admission rechecks the subscription before inference and tool calls. Removing access also stops pending attention reports. These background features require compatible Rails and Clawder worker deployments.

Select the agent’s name or Agent activity to open its workspace. The panel has three tabs. Activity holds threads, automations (saved workflows and routines) and library files. Computer shows the agent’s screen and processes. Setup lists everything you configure, grouped as profile, what the agent can do, where you reach it and how it runs; each row shows its current state and opens that setting, and the header of an open setting goes back to the list. Owners and managers can rename the agent under Setup → Name and avatar. The name updates across the workspace while existing links and history remain available. Sharing is under Setup → Who can use it. On the web, session details are at the foot of the Setup list. Activity and Computer remember the view you last used there; Setup opens on its list.

Wide browser windows open with Activity → Threads beside chat. Drag its divider to resize it, or focus the divider and use the arrow keys. Double-click the divider or press Enter while it has focus to restore its default width. On a narrow screen, close the panel to return to chat.

Open Setup → Skills to enable hosted research, document, media and coding skills. Custom agent skills are also available. Skills that need additional setup are marked in the list. Open Setup → Integrations to switch connected accounts on or off. Choose Add at the top of Integrations to browse and search the catalog in its own dialog and connect another service. Choose the model and reasoning effort in the composer.

When inline skill installation is enabled, paste a public skills.sh or GitHub skill link into chat and ask the agent to add it. A copied npx skills add owner/repo --skill skill-name command works too; Composal reads the source without running the command. The chat review card shows the pinned source, skill instructions, and included text files. Deselect skills you do not want, then choose Install. Only owners and managers can approve installation. Nothing is installed before approval, and the card reports each selected skill's result. Installation applies only to this agent and does not replace a different existing skill. Private repositories, binary files, and sources exceeding the preview limits are not supported.

You can also ask by topic or publisher, such as “Install the Anthropic skills” or “Find a PDF skill.” The agent searches skills.sh and opens the same review card for the matching skills, or lists the matches and asks which you want. Searching installs nothing. Large collections can exceed the preview limit; if that happens, choose fewer skills.

To share an imported skill, ask the source agent: “Share your release-review skill with @release-bot.” The destination must be a shared, active V2 agent in the same organization. Its main chat shows a review card naming the sender, with the exact saved instructions, companion files, and pinned source. Someone with management access to the destination can deselect skills and choose Install, or decline. Offers expire after 24 hours; refreshing or resetting the conversation does not approve or remove them. Approval alone is not success: the card reports the verified installation result for each selected skill.

Agents use team_skills_list to find their saved, successfully imported skills, team_skill_share to offer a selection, and team_skill_shares to check incoming or outgoing decisions and installation results. Results are available on request, not automatically delivered as new bot messages. Sharing copies the reviewed import, not later workspace edits, credentials, or conversation history. Bundled skills and custom skills without a saved successful import cannot be shared this way yet. Making the destination private, pausing either agent, or revoking the approver's access blocks a pending installation.

Organization skill library. Open Skills at the foot of the Agents sidebar to manage skills for every V2 agent in one place. Your skills lists what your organization has added; Discover finds more. Organization admins pick a source — skills.sh search, the Claude, Cursor or Codex plugin marketplaces, or a public GitHub or skills.sh link (an npx skills add command works too) — and review the skills found at a pinned commit. Only a plugin's skills are added, not its commands, hooks or MCP servers.

When adding a skill, or later on its page under Who has this skill, choose All agents (every agent, including ones created later) or Selected agents: pick one agent, several, or none, and choose whether new agents also get it. Admins decide what new agents get; anyone can turn a library skill on or off for agents they own or manage. Each agent shows whether the skill is installed, still applying, or failed with the reason. The skill's page also shows its instructions and files. Removing a skill turns it off on every agent; the agents keep its files but stop using it. Skills with binary files, nested skills, or more than 256 KB are not supported, and a skill name can only be in the library once.

To use a personal subscription, open the composer’s model picker, choose Claude, ChatGPT, or Grok, then select Connect or Manage subscription. On desktop, connection, device codes, saved accounts and model selection stay inside the model picker. Make private asks for confirmation inline before continuing to connection. On the web, the Model subscriptions dialog provides these controls and is also available in Settings.

If you’re looking for a newly released model, choose the connected provider in the model picker and select Refresh models beside the account menu. This reloads the models your agent can use and keeps your current model and billing. Some new models require an agent runtime update before they appear.

Your saved accounts are personal to you across all your workspaces. Open subscription setup on another private agent you own, choose your saved account and model, then select Use subscription on this agent. You do not need to sign in again. Each agent keeps its own model and effort; provider plan limits apply across them.

ChatGPT and Grok connect with device codes. Desktop opens the provider’s sign-in page in your browser; return to the app to finish connecting and apply a model. Choose Use a device code for ChatGPT or Grok, copy the displayed code, and enter it on the provider’s sign-in page. Desktop checks for completion while you sign in. xAI may call the consent application Grok Build. For Claude, run claude setup-token locally, paste the result into Subscription token, then choose Save Claude subscription. Choose an account and model, then select Use subscription on this agent. Existing agent-local sign-ins are saved to your personal accounts when you apply a model. If the subscription is already in use, choose Save for your other agents to keep its current model and effort. Connecting another account keeps the agent’s current plan selected. Open the new provider’s tab and choose a model to switch plans.

If applying a model is interrupted, refresh subscription setup to check and finish the saved connection. Setup confirms the model only when its account binding is ready. If a message is refused with Your plan is disconnected, select Reconnect plan to apply the agent's chosen plan again, or Use Composal billing to switch to platform models. When the saved sign-in no longer works, reconnecting asks you to sign in to that plan again. After applying, the composer shows a Subscription badge. The selection governs future messages, routines, and delegated work, including older conversations. Change its effort from the composer’s model picker, or choose Use platform billing to return to platform models. Where per-thread models are enabled for an Enterprise agent, a delegated thread can instead name any model and effort the same plan offers. It keeps that choice for all its turns and stops, rather than switching models, if the plan no longer offers it.

Detach stops this agent from using an account while keeping it available to your other private agents. Remove account revokes that saved connection for every attached agent; your agents and conversation history stay.

Sharing a personal account with other people is prohibited by the OpenAI, Anthropic, and xAI consumer terms. Composal therefore requires a private agent so only you can use your personal subscription. Shared agents and Project agents cannot use it. On an eligible agent you own, choose Make private directly in the desktop model picker or the web subscription dialog, then confirm Stop sharing and make private to remove team and individual access while keeping its history and settings. Sharing an agent suspends subscription use. You can still choose a Composal usage-based model from the composer for a shared agent.

The Agent activity button in the upper-right corner toggles the workspace. A dot appears while the agent is working. Open Setup → More settings to see the session’s status, model, connection and sharing. Use Browser in the conversation header to open a page alongside chat.

Subagents also appear at the end of the main conversation, with their names, status and latest progress. Select one there, under the agent’s name or in Activity → Threads to open its conversation beside yours. The conversation shows up to three; choose All subagents for the full list. Use Back to threads to return to the list. Each conversation keeps its own draft.

While subagents are running, or finished in the last two minutes, they show in a small card under the agent's name; select one to open it. If the agent's worker restarts while subagents are running, the conversation resumes on its own and the agent checks each subagent's state before repeating any work. The agent's row in the sidebar shows how many are running. The sidebar count updates for agents you have opened in this window, and keeps updating for them while their subagents run.

Computer → Screen shows the agent’s computer, named for the agent. Each agent has one computer, shared by all of its threads. An owner or manager can choose Start computer to prepare a browser and desktop in the agent’s existing Blaxel sandbox. This keeps its project files in place. The first start installs the graphical runtime and can take longer. Owners and managers can choose Take control on the screen to open the computer beside your current conversation and click, move the pointer, drag, scroll and type directly in the same desktop the agent uses. Your messages and unsent draft stay in place. While you have control, the screen is outlined and its header says You have control; choose Stop control to go back to watching. Click the desktop to use it directly. Paste text with Cmd V on Mac or Ctrl V on Windows and Linux. The current VNC clipboard supports Latin-1 text; unsupported characters show an error instead of being changed. Leaving the desktop or switching tabs releases held keys and mouse buttons. Press Ctrl Shift Space to return keyboard input to the viewer controls; click the desktop to continue. Choose Enter fullscreen for more room and Exit fullscreen to return to chat alongside the desktop. Reconnecting keeps the same agent computer and its running apps. When the agent needs you in its browser, for example to sign in, it can open this live view for you. Other viewers keep read-only access. On smaller screens, the computer appears below chat.

Under the agent’s name, Computer → Screen shows the computer’s memory, CPUs and disk. While the computer is running, two small graphs show its CPU and memory use over the last two minutes; they update while the screen is open and never start or wake the computer. Below the screen, Machines counts the agent’s managed machines that are running: its own computer and the machines its threads run on. It shows about how many agent minutes an hour they use and how many agent minutes they have used this billing period, which trails by about an hour. Expand the list to see each machine’s state, size and the thread working on it. The agent’s own computer runs the main thread and any thread without its own machine. Machines in standby use no agent minutes. For an agent with many thread machines, only the most recent are checked; the count then reads At least and the rest are listed as not checked. Machines on your organization’s own sandbox provider are not shown.

In Composal Desktop, New tab opens the home page. Pick Local browser or Remote browser there. Each tab shows where it runs. Local tabs use your computer and sign-ins. Remote tabs use the Chrome session shared with the agent on supported Linux computers. Choose Full desktop in the tab row to see the agent’s desktop, then Browser view to return to its Chrome tabs. Expand to window fills the app window with the browser pane. Choose Restore split view to bring the conversation back alongside it.

On supported Linux computers, the remote desktop resolution follows the Full desktop pane as you resize the app or enter fullscreen. Computers that keep a fixed resolution scale the desktop to fit.

The remote browser sharpens text and images when the page settles. On high-density displays, the settled frame can use extra pixels while the page layout stays the same.

With the browser pane open, select a tab and send a message like “Use this page.” On supported workers, the message includes the selected tab and a short list of other open tabs. The agent can inspect the selected remote tab directly. For local tabs it gets titles and website addresses as reference, while page contents and sign-ins stay on your computer. Shared addresses omit query strings and fragments. Close the browser pane before sending to leave out browser context.

An older retained agent computer may require a restart before enabling browser routing. Contact your administrator or Composal support to restart that retained computer, then reconnect its browser. The computer controls do not currently offer a restart action. Refreshing the Composal window or choosing Start computer for an already running computer does not update its graphical runtime.

Blank tabs open a home page with shortcuts and recent pages. Local and remote recents are kept separately on your device. Selecting a recent opens it in the current browser.

To install an extension in the agent’s remote Chrome, open Extensions → Visit Chrome Web Store. Choose an extension and use Install in Full desktop to see Chrome’s install prompt. Select Add to Chrome, review the permissions, and confirm. Return to Browser view and open Extensions to see the install.

The live viewer uses noVNC over a private, expiring connection; it needs no separate VNC application. Access is checked again when the connection renews, and the server closes each connection after at most five minutes. After renewal you keep the choice you made: in control, or watching after you released it. The computer remains shared with the agent while you use it. Choose Pause preview to stop the screenshot preview, Stop control to stop live control, or Back to chat to close the computer view. Switching browser tabs keeps an established desktop connection open and pauses screenshot polling. Returning to the tab rechecks access and reuses the live connection while its ticket remains valid. Viewing stops when you close the panel or leave it untouched for five minutes. While the agent is working, an open view keeps updating, and one that paused for inactivity resumes; the five minutes count from when the agent finishes. Choose Resume preview or Take control to view it again. Automatic screenshots and connection renewals do not count as activity. Pausing the view does not stop the agent’s work. Processes lists the sandbox’s process names and statuses. Its updates also pause after five minutes without input; choose Resume to restart them.

These workspace panels require a compatible Spark runtime. Opening a panel does not create a missing sandbox; starting the computer acquires compute explicitly.

For browser tasks, the agent uses computer_browser to start and control this same visible browser. Navigation, clicks, typed text and existing sign-ins are shared with your computer view. The tool returns the browser's current URL and a fresh page snapshot so the agent can check the result. Each task works in its own window behind the page you are viewing, with the same sign-ins, so up to three tasks run at once without changing your page. Task windows stay open for 15 minutes after their last task for follow-up work, then close when a new task starts. A page that opens a pop-up can still bring its task window forward. The worker's separate host browser is disabled. If an action fails or its result is uncertain, the agent must inspect the current page before considering another action.

To show Processes, enable Show computer processes in Setup → Computer. In Computer → Processes, select Open terminal to run commands in the agent’s sandbox with chat beside it. The terminal supports interactive programs, Ctrl+C, text selection, paste, and resizing. Large pastes show an error and leave the shell running; paste a smaller amount of text to continue. Use Shift+Tab to leave terminal input. Workspace managers with access to the agent can open terminals; other viewers can inspect the process list.

Each terminal opens a new shell in the same sandbox filesystem. Disconnecting, closing the workspace, or hiding the browser tab ends that shell. Open a new terminal to reconnect; commands are never replayed automatically. Sessions expire after 30 minutes. This opens a separate shell rather than attaching to a running process’s input.

Open Integrations at the foot of the Agents sidebar for the full-screen organization catalog. Organization Connections contains Slack, GitHub and GitLab settings; Sandboxes and Team apps have their own tabs. Agents-only workspaces include the catalog without a separate integrations rollout grant. Settings retain their existing permissions.

Choose a provider, then change Account access for an account you hold. Choose Private to you to use it only with agents that only you can access. Choose Shared with team to let teammates enable it for their agents. Making an account private suspends existing team access. Sharing it again restores saved selections for the current sign-in.

Open an agent’s Integrations to switch an account on or off for that agent. A private agent automatically includes connected accounts you hold unless you switch them off. Sharing the agent or granting someone access ends automatic inclusion. For a Team agent, select shared accounts under Integrations this Spark can use during creation or in the agent’s settings later. Organization administrators can also connect a custom HTTPS MCP server for the team.

Agents run with Full Access by default. This applies to their authorized tools and resources; it does not give access to another user's private agent or an unselected repository/account.

V2 Full Access includes native command execution and installed OpenClaw tools. An agent can create command routines and manage its own automations from any of its conversations, including a scheduled run. Commands and files use its assigned Blaxel sandbox, which starts only when needed. The harness and model inference run outside that sandbox so ordinary conversation starts immediately.

In Settings, configure instructions, skills, tools, work repositories, app accounts, memory policy, model policy and spending/execution limits. Saving creates a configuration revision. Activate that revision to use it for new work; an already admitted task keeps its pinned configuration and limits.

Use Connections to connect supported Composio apps or add a custom HTTPS MCP server, then select the exact account in the agent's Settings. The catalog includes supported Composio apps. Custom server credentials are collected during connection setup. An integration's available agent tools and its support for incoming provider events are separate capabilities.

Run without an open chat

Configure Triggers for schedules, incoming webhooks and supported platform/provider events. A trigger delivers an input to the agent; it does not require a user to keep the conversation open. Use the preview and authorization steps shown for each trigger before activating the revision.

For GitHub, select a work repository and subscribe to its platform events, such as github.pull_request, github.issue_comment, github.push or github.check_run. The agent can add or remove subscriptions itself to match its role and instructions; you can also ask it to change them in chat. Enabling the feature does not subscribe every agent to every event. Events come from the platform's existing GitHub App webhook connection; users do not need to create a separate webhook URL for each agent. Event details include the action and delivery identity, and duplicate deliveries do not create duplicate wake messages. The platform must receive that event from GitHub for a subscription to fire.

Where relevance screening is enabled, subscribed external events are checked against the agent's instructions and the subscription's purpose before starting agent work. Only clearly unrelated events are filtered; uncertain or oversized events remain eligible. Screening uses the same daily spending limit as other agent work. Temporary provider failures defer the event for bounded retries, then allow a normal wake. You can ask the agent to change its screening setting in chat. Direct messages, routines and helper results bypass this screening.

For V2 bots with the proactive inbox enabled, open Setup → Webhooks. Name the connection in the sidebar form and tell the agent how to judge incoming events and which workflow to use, then choose Create webhook URL. Copy the Webhook URL into PostHog or another provider and send its normal JSON payload with an HTTP POST. The URL contains a private token; only the agent’s owner and managers can retrieve it. You can copy it again after reopening the connection. No custom signature or envelope is required. Events per day caps accepted events for each webhook, with a default of 100 and a maximum of 1,000. Extra events receive HTTP 429 until the quota resets at midnight UTC. This caps intake, not workflow runs. Generic callbacks use the event type event; the form sets this automatically. Each named connection appears as an app on that bot; you can add several. Setup requires permission to manage the bot, not permission to connect organization-wide OAuth accounts.

For custom senders, Advanced sender setup shows the separate signed endpoint URL and one-time signing secret. Send UTF-8 JSON up to 64 KB with schema: 1, type, optional subject and an object-valued data. Supply X-Composal-Event-Id, X-Composal-Timestamp (Unix seconds within five minutes), and X-Composal-Signature: v1= followed by the hex HMAC-SHA256 of timestamp + "." + eventId + "." + exactBody, using the signing secret. Retries reuse the same event ID and exact body. Other event types are recorded as filtered, and still count toward the receipt limit.

Generic callbacks accept a JSON object or array. They can optionally supply X-Composal-Event-Id to deduplicate retries; without it each request is a separate event. The payload plus its internal event envelope must fit within 64 KB. Providers that support headers may instead POST to the signed endpoint URL with Authorization: Bearer <token> using the token from the private receiver URL.

Open a saved webhook to copy its URL under Connection, inspect Recent events, send a Test endpoint request, or Manage its status. Recent events show the delivery state, event ID and receipt time; expand a row for details. In inbox means the event is available for review, not that the bot has acted. The test panel sends your JSON to the real receiver and shows its HTTP response. Test events count toward the limit and may start agent work. If a request times out, check Recent events before retrying. The bot reviews events when idle; optional Jev assessments advise it without controlling its decisions. Incoming payloads never grant additional permissions.

Pause events stops new intake but preserves accepted backlog. Rotate URL and secret replaces the private receiver URL and signing secret; the previous credentials work for five more minutes. Update the URL in your provider after rotating. Remove revokes the endpoint and prevents queued events from starting work, while retaining delivery history. Already started work is not cancelled. If inbox access is disabled, webhook intake stops and accepted unpublished receipts wait for recovery; they never fall back to immediate execution.

Webhook connections belong to the native bot. Retired legacy webhook endpoints are not reactivated; create a named connection and configure its new URL and signing secret in your sender.

Pause an agent to stop admission of new execution. Archive it when it should no longer run. Stopping a task is a separate action: effects already started can still require reconciliation. These lifecycle actions do not delete its history.

Archive a workspace agent

In a V2 agent conversation, click the agent name, open the Setup tab, then choose Delete agent at the foot of the list and confirm. Only the agent's owner or an explicitly granted manager can archive it. Project agents are not eligible for this action.

Archiving removes the agent from the workspace and revokes its access and execution authority. Runtime cleanup happens asynchronously; already-started external effects may still need reconciliation. Audit records are retained, not permanently erased. Saved links no longer open the archived agent.

Where inline confirmations are enabled, you can also ask a V2 agent to archive a specific shared teammate. The agent uses request_agent_archive to show the exact target in an Archive agent request. A signed-in user with management access to that target must approve the card; ordinary chat, another bot's instruction, or management of only the requesting agent is not authorization. A changed target or revoked permission requires a fresh request. An agent cannot archive itself or discover private agents through this tool. Decline leaves the target untouched.

V2 agents also include the composal-agent-create skill. Ask an agent to create a teammate and describe its role, model, sharing preference, repository access, connected accounts, and team apps. It prepares one Create agent card with the proposed settings. Review the details and click Create agent to create a V2 agent that you own. Declining creates nothing.

The card can enable current connected organization accounts and install published team apps on the new agent. It rechecks access when you approve, so changed accounts or unavailable apps require an updated request. New provider connections still use secure sign-in. Skills, routines, Slack channel publication, subscription logins, and computer access have separate setup flows; existing memory, conversation history, credentials, and private Pages are not copied. A private agent can use its owner's own connected accounts under the usual private-agent rules. Agent creation starts setup in the background; the creation receipt does not mean setup has finished.

Follow work and replies

Scroll up in a V2 conversation to load older messages automatically while keeping your place. Earlier messages start loading before you reach the top. The floating agent name temporarily changes to Loading…, then returns when loading finishes. In web and desktop conversations, the same button shows Connecting… while establishing a connection or Reconnecting… while restoring one. Connection status takes priority over history loading; the agent name returns when connected and history loading has finished. You can still open the agent workspace while it loads or reconnects. If history loading fails, scroll up again to retry. Conversation history shows messages without repeated sender names. Time markers appear at the start, when the local day changes, and after a gap of 30 minutes. Your message appears in the conversation immediately when you send it. An activity indicator shows sending, queued and working states as delivery and execution progress. If delivery cannot be confirmed, retry the original message to keep the same identity.

Message acceptance is a durable receipt, not a completed answer. A conversation shows the accepted input, its task status and the saved result when available. An agent can also wait for your answer or an approval. A failed, cancelled or blocked task is not a successful reply; inspect its reason.

Limits can stop a task before it finishes. A lost provider acknowledgement can require reconciliation. Keep the original task/input identities when investigating, and avoid submitting the same work as a new message merely because its answer has not arrived.

Choose an integration surface

  • HTTP API: create, configure, message and manage agents from your application. Read conversations, task outcomes and versioned state.
  • CLI and MCP: manage the same agents using com agent or the local MCP server's com_command tool.
  • Coding-agent setup: install skills and tools into an external coding assistant. This is separate from creating a persistent agent.

The HTTP API is the integration contract today. composalai/agent-sdk is planned; no dedicated agent SDK is available yet.

Archived agents keep their history. Owners and managers can still make that history private; this does not reactivate the agent or restore messaging.

To remove an account, open its app on Agents → Integrations, choose the account’s trash icon, then confirm Delete account. Organization admins can delete connected or revoked accounts. Deletion removes the account from the list and stops every agent from using it; connection history is retained. To use the account again, add it as a new account.

Spacesheep

On Agents → Integrations, choose Spacesheep, then Add account. Sign in to Spacesheep and approve Composal's OAuth connection in the new tab, choose Finish connection, then refresh accounts. Composal connects directly to Spacesheep's MCP server, stores credentials on the server, and refreshes them there. No Composio connection, API key or custom server setup is needed. Organization admins connect accounts.

The legacy Composio integration has been removed and its accounts disconnected. Connect a Spacesheep account for direct access and subscribe your agents to it. Legacy OAuth credentials cannot be transferred. Reconnect if an interrupted token refresh leaves the connection unavailable; Composal does not replay an uncertain rotating-token exchange.

Connect once for the organization, then ask any V2 agent to subscribe to the shared Spacesheep account. The agent discovers available accounts with integrations_list and selects the account’s current generation with integration_subscribe (enabled: true). No separate OAuth sign-in is needed per agent. Ask it to find tools to publish a page, read or search spaces, or collaborate on comments. Use enabled: false to unsubscribe, or manage access in the agent’s Integrations settings. Disconnecting or replacing the account authorization invalidates existing subscriptions. Other integrations still require explicit selection in settings. Shared integrations are currently available to enabled pilot organizations.

Show me where a setting is

In the desktop app, ask a V2 agent where to change an app setting, such as your theme or your devices. The agent can use app_ui_show to open the right settings section and point at the control with a cursor labelled with its name. It only shows you the setting; you make the change. Click, press a key, or scroll to stop it at any time. Other clients show nothing, so the agent also says where the setting is in its reply.

Open artefacts beside a conversation

Select Browser in the header of a V2 agent chat to show the browser in a separate panel beside your messages. Paste a full website or artefact URL in its address bar, or click a link in the conversation to view it alongside your messages. This also works with Spacesheep artefact links. Use Back, Forward, Reload, or Open in external browser from the panel toolbar. Close the panel to return to the full chat.

Composal Artefact team links for your current organization use your Composal sign-in in the web and Desktop panels. The link opens the selected version and file if you have access.

In Desktop, a Markdown Artefact link in a Spark conversation opens the Library editor beside the chat. You can edit and comment when the version allows it.

Agents can use chat_browser_open to open or navigate this panel for you. Only live requests in the conversation you are viewing open it automatically; earlier messages and reconnect snapshots do not reopen a panel you closed. The tool requests presentation and cannot read your page, cookies, or signed-in session. Ask the agent to include a normal link as well if you may read its reply later.

In the web app, pages appear in an embedded frame. Previous opened address and Next opened address track links opened from chat or the address bar. Navigation inside other sites may not update the displayed address; external-open opens the address shown in the toolbar. Sites that block embedding must be opened externally. On desktop, the panel uses an embedded Chromium browser with its own login session, separate for each Composal account and organization. Closing the panel destroys its page; website sign-ins remain in that organization's browser profile. The desktop browser requires a client version that includes this feature.

Bring your own sandbox

V2 agents can run commands, work with project files, check out repositories and publish library files from your own Freestyle, exe.dev, E2B, Daytona, Vercel Sandbox or Modal account. Composal managed compute (Blaxel) remains the default.

For a V2 agent created in the web or desktop app, Composal uses the creator's time zone to pick a nearby region for new managed Linux sandboxes. Northern Virginia is the default when the time zone has no matching region. An explicit operator region takes precedence. Existing sandboxes and their volumes keep their region.

  1. In Agents → Integrations → Sandboxes, choose a provider to open its setup page. Expand Machine settings to customize resources. An organization admin saves the provider credentials and a named machine profile, such as “Freestyle large.” Credentials are encrypted and cannot be read back from the form.
  2. Choose the machine settings for that profile. Freestyle supports vCPUs, memory and disk; E2B uses a hardware template; exe.dev uses an existing Cloud Pool. Daytona custom resources require a container image. Vercel sizes memory with vCPUs. Modal accepts vCPUs, memory and an optional registry image. Provider quotas and available sizes still apply. Sandbox runtime shows the memory configured in your selected provider profile.
  3. Open the V2 agent’s Setup → Computer → Machine profile, choose the profile and select Save machine profile. The next sandbox operation acquires the machine. Saving a profile alone does not verify credentials or start paid compute.

Each agent gets its own workspace. Switching profiles starts a separate workspace and does not copy files or delete the previous machine. The previous machine may keep accruing charges: stop or delete it in the provider account when you no longer need it. Conversation history and agent memory stay with the agent. Machine settings are fixed for each profile; create another named profile to change them. Admins can rotate credentials or disconnect a profile. Disconnecting blocks new agent operations for every agent selecting it; it does not stop already-running processes or delete provider resources.

For faster file tools on Freestyle, keep Node.js 24.22.1+ (24.x) or 26.12.1+ available on the VM’s PATH. File tools still work without a supported Node version, but require more network requests.

Freestyle workspaces automatically pause after ten minutes without network activity; a shorter provider timeout is kept. The next file or command operation wakes the same machine with its files and processes retained. This first operation can take longer while the machine resumes. Existing Freestyle machines receive this policy when the worker next acquires them. Blaxel managed sandboxes use the provider's automatic standby and wake when a command or computer view needs them. Standby storage and retained volumes can still incur charges.

Worker restarts reconnect to the saved machine. Provider lifetime and storage-retention limits still apply. Modal machines run for at most 24 hours; Composal enables Modal's beta exit snapshots so their filesystem can be recovered for 30 days after exit. Snapshot recovery requires an explicit restore in your Modal account; Composal does not automatically allocate a replacement. Modal does not guarantee exit snapshots after rare hardware failures. Custom Modal images must include Python 3 and a POSIX shell; repository work also requires Git.

The embedded visible computer, interactive terminal and shared preview links currently require Composal managed compute. With your own provider, use agent commands for execution and the provider dashboard for previews and machine cleanup.

An interrupted allocation is reconciled by its stable machine identity. In Setup → Computer → Machine profile, copy the Current workspace key and look for that name or composal-workspace label in your provider account. The panel also shows the allocation status and the provider machine ID once recorded; select Refresh to update them. Composal does not automatically repeat an unconfirmed paid creation. If no machine can be found, inspect your provider account before switching to another profile. An allocation in progress can be abandoned by selecting a new profile after 15 minutes; any machine created by the earlier request remains in the provider account. If a previously assigned VM disappears, Composal reports the missing workspace instead of replacing it silently.

Collaborate on a team agent

Open the same shared agent with a teammate to see who is there. Teammate avatars appear beside the agent name in the conversation and in the agent list, including teammates viewing it in the desktop, iOS, or Android app. Native presence follows the app’s live conversation connection and clears when that connection closes. In the web conversation, live pointers show where others are working, and the prompt is one shared draft: everyone who can send messages can edit it together. Simultaneous edits merge automatically.

Each conversation has its own draft. Sending submits that draft once and keeps text teammates add while the request is running. Attachments and model choices remain local to the person sending. People with read-only access can see presence but do not receive or edit unsent prompts.

Presence fades when a viewer leaves or loses their connection. Drafts reconnect while a tab is open and are retained when navigating between agents. Unsent drafts are not saved permanently; keep a tab open until you send the prompt.

Automatic browser IP routing

V2 agents prefer a connected desktop’s IP by default. When Composal Desktop is running and signed in to the agent owner’s organization, it automatically connects to their running managed Linux agent browsers. You do not need to open the browser panel. Websites then see the desktop’s home, office or VPN address; the browser and agent continue running in the cloud.

If no desktop is connected, the browser uses the sandbox’s IP. It switches back automatically when a desktop becomes available. If several desktops are online, the current one keeps serving until it disconnects. Switching IPs closes existing connections; pages may need to reconnect.

For Enterprise agents, automatic routing follows agent work and computer viewing. The route stays connected while a turn runs, while someone views or controls the computer, and for ten minutes after the last of these, so the browser keeps its connections between turns and while a task waits. After ten minutes with no work and no viewer, the desktop route disconnects so the computer can enter standby. Standby retains files and running processes; the next computer action wakes the machine. If the browser closed meanwhile, the next browser task reopens it with its saved profile and says so. Routing reconnects automatically when work or viewing resumes, and never restarts the browser while a browser task runs. Automatic routing renewals alone do not keep an idle computer awake. Explicit manual browser connections and open terminals can still keep it awake.

In Composal Desktop, select an agent and choose Devices from your account menu. Under Browser network, turn off Prefer desktop IP to keep that agent’s browser on the sandbox’s IP. The preference is saved with its browser profile. This supports hosted and OCE enterprise managed Linux browsers, and requires an updated worker and desktop app. Preparing a retained running browser may reopen it with its saved profile; a closed browser is not opened automatically.

The desktop route supports public HTTP and HTTPS destinations on ports 80 and 443, including WebSockets. Private and local-network addresses stay blocked on this route. Desktop network or DNS failures fall back to sandbox egress; a rejected private destination does not. Terminal commands keep their normal route, and the cloud browser keeps its own fingerprint and cookies.

Sandbox environment and memory

In Setup → Computer, choose Browser for Linux with a browser the agent drives, or Full desktop for a Linux desktop it can click and type in, such as for Electron and native GUI apps. Then choose its memory. For macOS, connect your own Namespace API key under Agents → Integrations → Sandboxes → Namespace, then select that connection in Machine profile. Your Namespace account supplies a persistent Apple Silicon Mac with 6 cores and 14 GB memory and bills its usage directly. Its Devbox and Mac quotas apply. Stop active work and acknowledge the replacement before applying a change. Files outside an attached persistent volume may be lost. New Linux sandboxes include a 16 GB volume by default; existing sandboxes keep their current storage; ask the agent to add one when a large checkout, Rust caches or persistent data need it. The agent can also prepare its own image with its runtime tool.

New Desktop-profile Linux computers include an Xfce desktop with Google Chrome, Files (Thunar), Terminal, a text editor (Mousepad), and Calculator (Galculator). Use a window's maximize button or Chrome's F11 shortcut to fill the remote screen. The viewer's Enter fullscreen button fills your own screen. You can also ask the agent to maximize or fullscreen its browser window. Closing Chrome leaves the desktop and its other apps running; use the Browser button in the dock to reopen the same browser. Its profile and desktop preferences survive image replacement when the computer has a persistent volume. Five Composal wallpapers are included. A new desktop picks one randomly; you can change it in Desktop Settings and keep your choice. Existing computers retain their selected image until you apply a runtime change.

Full desktop also includes preconfigured Cua.ai computer use, connected to the agent's OpenClaw/Codex tools. The agent can inspect windows and screenshots, click, type and use the keyboard on the same desktop shown in Computer → Screen. Ask it to start your Electron app using the project's dependencies. Cua runs inside the assigned sandbox. Selecting Desktop on an existing machine requires applying the profile before starting computer use.

Mac preparation takes several minutes; refresh settings until it is ready. Use native agent commands and Cua computer use on that Mac. Mac terminals open in Terminal.app on the shared desktop. Switching between Linux and Mac retains each machine separately. Their files and volumes are not shared. Macs use persistent Namespace Devboxes. Keep source and build output in the Namespace workspace (normally /Users/runner/workspaces) to retain them across stops. Other files may be lost. Desktop preparation runs again after a new boot, and saved secrets are restored for new commands.

Sandbox secrets and command-line access

In Setup → Secrets → Add variable, add private environment variables such as AWS credentials. Saved values are hidden and encrypted. They survive sandbox replacement even without a persistent volume. New native and legacy shell commands and new terminal sessions use the current values; restart a running process to pick up changes.

Development sandboxes include GitHub CLI (gh), AWS CLI (aws) and Composal CLI (com). GitHub authentication uses only repositories assigned to the agent. With multiple repositories, select one with --repo OWNER/REPO or work in its checkout. With unrestricted repository write access, coding helpers can push branches, open and merge pull requests, submit reviews and comments, manage issues, change workflow files, and dispatch, rerun or cancel workflow runs through gh, within the installed GitHub App's permissions and repository branch rules. They can also read checks, statuses, deployments, packages and security alerts the app can see. They can't set check runs or commit statuses, change repository settings, or read webhooks or secrets. Read-only and branch-restricted grants keep sandbox credentials read-only; use the agent's GitHub tool for writes allowed by a branch-restricted grant. Composal authentication is restricted to the agent's own environment and metadata, organization selection, and read-only source APIs for its granted repositories. Other CLI operations are denied. Personal account credentials are never injected.