Work from Linear

The Linear integration gives a coding agent the context of an assigned issue, including its description and comments. After setup, assigning or delegating an issue to boxes.dev will start the agent on a new devbox. It will report progress and results in the Linear Agent Session, the conversation with the agent attached to the issue.

Connect Linear

Use a boxes.dev project with a saved environment ready for the issue's repository. If the task needs changes to that environment, update its snapshot or saved version first. Each boxes.dev team connects to one Linear workspace.

1. In the desktop app, open Integrations → Linear.
2. If you're a boxes.dev team admin, choose Connect and approve the app in the intended Linear workspace. Otherwise, ask a team admin to connect it. A Linear admin may need to approve the installation.
3. Ask your boxes.dev team admin to check that the agent can access the Linear team containing your issues. Admins can see the list under Team connection → Linear team access.

If a team is missing, a Linear workspace admin needs to grant access through Manage in Linear. Afterward, a boxes.dev team admin should choose Check to refresh the list. Team admins can also manage the connection from Team Settings.

Link your account and activate Linear requests

The person who starts a Linear Agent Session owns the task: it runs with their linked boxes.dev account and their project's saved environment. Each person who delegates work therefore needs their own account link and their own active automation.

1. Open Integrations → Linear. If your verified Linear email matches your boxes.dev email, your account may already be linked. Otherwise, choose Link your account and sign in to Linear as yourself.
2. Choose Create automation. Your Default behavior will start paused and use the coding agent you use for new threads.
3. Choose Configure to select Codex or Claude Code, review the model, and write the instructions to use alongside each issue. Choose Save changes if you've edited the automation.
4. Choose Activate.

This default automation applies across the Linear teams and projects the integration can access. You can have only one active default automation for the same linked user and Linear workspace.

Start and follow a task

In Linear, assign or delegate an issue to the boxes.dev agent. Mentioning the agent also starts work when Linear creates an Agent Session from the mention.

boxes.dev will start your default automation on a fresh devbox from your latest Template box snapshot, or the current saved Team Template version in a member project. A link to the boxes.dev thread will appear in the Linear Agent Session, and the thread will appear in your main boxes.dev thread list, titled with the issue identifier and title when Linear provides them.

The agent receives your saved instructions and the issue context Linear provides: title, identifier, description, the comment directing the task and prior comments, acting user, suggested branch name, and any additional prompt context.

Linear will show brief progress updates and the final answer, or indicate when the agent failed, stopped, or needs input. Open the boxes.dev link to inspect the full conversation. You can send several issues at once, subject to your awake devbox and billing limits. Repeated events for one Linear Agent Session reuse the same boxes.dev thread instead of starting a duplicate run.

A Linear agent session reports progress and provides a link to the boxes.dev thread. Select the image to enlarge it.

Send a follow-up or stop work

Reply in the Linear Agent Session to send another instruction to the same boxes.dev thread. If the agent is already working, boxes.dev will queue your message. Otherwise, the agent will start working on your follow-up in that thread.

Use Linear's stop control to stop the agent. Removing the agent's delegation, deleting the issue, or marking it completed or canceled can also end the agent's work when Linear sends that event.

Attach work products

Ask the agent to attach its pull request, preview, report, or other result URL to the Linear Agent Session so you can open it directly from the issue. For example, reply in the session with:

Attach the pull request URL to this session as a work product.

To attach a URL, the agent runs this command on the run's devbox, replacing the example URL and label with its actual result:

boxes-linear attach-url "https://example.com/report" --label "Report"

The URL will appear as a work product in that session. The command works only inside a Linear-triggered boxes.dev run.

Check a failed start

Open Integrations → Linear and follow any connection or setup message shown there. If Linear asks you to connect or configure boxes.dev after you delegate an issue, check your own account link and active Default behavior.

For other start failures, confirm that the issue is in the connected workspace, the agent can access its Linear team, and your project's saved environment is usable. Check awake devbox capacity and billing if only some assignments start.

A boxes.dev team admin can reconnect a revoked app or restore missing permissions, then recheck the connection. If a work-product URL doesn't attach, confirm that it's a valid URL and that the agent is in a Linear-triggered run.