Turn on Chat and assign channels

After you connect a chat workspace and assign a channel to Projects, people mention @devboxes in the channel to ask for work. devboxes in Chat explains how conversations, threads, and waiting work behave.

An owner or admin connects the chat workspace: Slack, Microsoft Teams, Google Chat, Discord, or Telegram. For Slack, Microsoft Teams, Discord, Telegram, and Linear, the owner or admin can open the app's page under Integrations in the devboxes dashboard and choose Add to Slack, Add to Microsoft Teams, Add to Discord, Add to Telegram, or Add to Linear. Owners and admins assign its channels and set the Chat policy. A Telegram group works on every Project of the Organization and takes no assignment. An Organization connects one workspace or group per chat app. To move to another one, disconnect the current one with chat.disconnect first. Its channel assignments don't carry over.

Turn on Chat

Chat needs a policy before devboxes answers. A default Persona is optional and shapes how devboxes answers. Give your coding agent this prompt:

To do it yourself:

1. Set the Chat policy. The policy chooses the model for Chat:

   {
     "organizationId": "<organization id>",
     "enabled": true,
     "candidates": [{ "accountId": "<model account id>", "modelId": "claude-sonnet-4-5" }],
     "outputTokenLimit": 8192
   }

   devboxes invoke chat.configure-policy --input @chat-policy.json

   A policy without operations lets Chat use every operation that it can call, including operations that devboxes adds later. To limit what Chat may do, list the operations in operations:

   {
     "organizationId": "<organization id>",
     "enabled": true,
     "candidates": [{ "accountId": "<model account id>", "modelId": "claude-sonnet-4-5" }],
     "outputTokenLimit": 8192,
     "operations": [
       "projects.list",
       "blueprints.list",
       "sessions.dispatch",
       "sessions.continue",
       "sessions.list",
       "sessions.inspect",
       "sessions.refresh-pull-requests",
       "sessions.questions",
       "sessions.input",
       "publication.commit",
       "chat.add-waiting-work",
       "chat.resolve-waiting-work"
     ]
   }

   devboxes invoke chat.configure-policy --input @chat-policy-listed.json

   Chat then uses only the listed operations. Chat policy describes the fields, what the operations let Chat do, and the errors.

2. Optionally, create a default Persona to give devboxes a name and a way of answering:

   Prompt for your coding agentCopy prompt

   See Personas.

Assign a channel to Projects

{
  "organizationId": "<organization id>",
  "integrationId": "<integration id>",
  "channelId": "<channel id>",
  "projectIds": ["<project id>"]
}

devboxes invoke chat.configure-channel --input @channel.json

chat.integrations lists your connected workspaces with their integrationId. An empty projectIds list turns the channel off. Until an owner or admin assigns a channel, devboxes takes no work there and answers a mention there with a link to this section.

Answer every message in Discord and Telegram

In ambient mode, devboxes answers every message a person writes in a Discord channel assigned to Projects or in the Telegram group, as if it mentioned devboxes. It suits a person who works alone with devboxes. Ambient mode is off until an owner or admin turns it on, on the app's page under Integrations or with the command:

printf '{"organizationId":"<organization id>","integrationId":"<integration id>","ambient":true}' | devboxes invoke chat.configure-ambient --input -

In an unassigned channel, devboxes answers only a mention, with how to assign the channel. It never answers a bot or a system message, such as a join or a pin. "ambient":false turns ambient mode off again.

Read pull requests from Chat

People in a channel can ask @devboxes about the pull requests of the repositories that the channel's Projects work on. They name a pull request by its link, or by its repository and number, for example my-org/web-app#42.

The Chat policy must allow the reads that Pull request reads lists.

devboxes reads only the repositories of the channel's Projects, through the repository connection those Projects use. When they reach one repository through more than one connection, devboxes can't choose one and says so. An owner or admin then connects those Projects through one connection.

devboxes reads issues, GitHub issues included, in the Project's issue tracker with issues.read. See Read the issue of the work for who can read them.

Link your chat account

Some requests in Chat need to know who asks, as Knowing who asks explains. devboxes acts on them only when your chat account is linked to your devboxes account.

To link your chat account:

1. Ask devboxes to link your chat account, or ask for something that needs to know who asks. devboxes sends a link only to you: a direct message in Slack, Microsoft Teams, Discord, or Telegram, or a message in the Google Chat thread that only you can see. In Microsoft Teams, you need the devboxes app in personal scope. In Telegram, when you never started a chat with @devboxes_bot, devboxes first answers with a start link: open it and press Start, and devboxes sends the link there, to you only. The start link works once. devboxes never reads that message back, even when you reply under it.
2. Open the link and sign in to devboxes if asked. The page names the chat account and its workspace. Check that the account is yours, then choose Link. The link works once and expires after 15 minutes. Do not share it: whoever confirms it links your chat account to their own account.
3. Ask devboxes again.

Your account links one chat account per platform. When it already links another one, or the chat account is linked to another account, the dashboard asks before it replaces the existing link. To replace the link, confirm Replace the earlier link? in the dashboard. To remove your link, choose Unlink next to the chat account under Chat accounts, or run people.unlink with the platform. An owner or admin removes another member's link with their userId from members.list. Linear, Jira, and GitHub accounts cannot be linked.

Merge pull requests from Chat

Owners and admins of your Organization can ask devboxes in a channel to merge a pull request of a Project that the channel is assigned to. The Chat policy must allow repositories.merge, repositories.review, and repositories.checks, because devboxes reads the pull request to find the commit to merge, and reads its checks. An owner or admin who merges this way first links their chat account. In a GitHub conversation, they also need write access to the repository. For what devboxes checks before it merges, see Ask devboxes to merge a pull request.

Set up ways of working from Chat

Any member of your Organization can ask devboxes in a channel to set up a new way of working or change one, such as handling checks and investigations without opening pull requests. devboxes writes it as a Blueprint, and commits it only when a member asks for that change in their own words. When a conversation only suggests a change, devboxes leaves it as a draft and asks an owner to approve it. The member who asks and the owner who approves first link their chat accounts. The Chat policy decides which steps devboxes can take, as Blueprint operations lists.

When work reaches a sensitive integration, an owner approves the version first. When the policy allows blueprints.approve and integrations.configure-sensitivity, an owner who linked their chat account can ask devboxes there to approve a version or to mark an integration sensitive. Outside a task, devboxes uses a sensitive operation, such as commenting on a pull request, only when an owner who linked their chat account asks.

Follow conversations

To list, read, or close conversations, use the Chat operations. To turn Chat off, set enabled to false in the Chat policy.