Operations

Run any operation with devboxes invoke <operation> --input @<file>, or ask your coding agent to run it. devboxes describe <operation> shows what the operation takes and returns.

Account and Organization

Operation	What it does
`account.inspect`	Shows the account you are signed in with.
`organizations.create`	Creates an Organization with you as owner.
`organizations.list`	Lists your Organizations.
`organizations.inspect`	Shows one Organization, the managed regions devboxes offers, and the hosts it allows its managed tasks to reach.
`organizations.update`	Renames an Organization, or changes where its tasks run or which hosts they reach, or whether Chat threads can take tasks over with `sessions.handoff`.
`organizations.delete`	Deletes an Organization you own, with everything it holds, once its Sessions are erased or marked for erasure and no Chat conversations remain. Its paid plan ends at once.
`roadmap.interests`	Lists the roadmap features your Organization asked for.
`roadmap.mark-interest`	Tells devboxes your Organization wants a roadmap feature, such as Redis-compatible stores.

Members and invitations

See Create an Organization and invite your team.

Operation	What it does
`members.list`	Lists the members and their roles.
`members.change-role`	Changes a member's role.
`members.remove`	Removes a member.
`members.update-setup`	Saves how setup guides you and whether you skipped connecting a model subscription.
`invitations.create`	Invites a person by email address.
`invitations.list`	Lists the Organization's invitations.
`invitations.received`	Lists the invitations sent to you.
`invitations.respond`	Accepts or declines an invitation.
`invitations.cancel`	Withdraws an invitation.

Delegations

A delegation token has fine-grained permissions. The token runs only the operations in its operations list, in one Organization.

With expiresInSeconds, the token expires after that many seconds, from one minute to ten years. Without it, the token never expires and works until you revoke it with delegations.revoke. The result of delegations.create then contains a warning. The CLI prints it on stderr, and with --json it stays in the result. delegations.list shows expiresAt as null for such a token, and for the delegation of a queued Run until the Run starts. A Run's delegation is revoked when the Run ends, and erasing its Session deletes it. Store a token without an expiry as a secret, and revoke it when you no longer need it.

An owner sees the delegations of every member in delegations.list, and can revoke any of them with delegations.revoke. The member stays in the Organization, and the token stops working at once. An owner's list also includes the delegation of every Run. Revoking the delegation of a running Run cuts that Run off from the API before it ends. Other members see and revoke only their own delegations. The list never contains a token.

See Connect Claude Code or Codex and Start tasks from CI.

Operation	What it does
`delegations.create`	Creates a token that can run only the operations you list.
`delegations.list`	Lists your delegations, or every member's for an owner.
`delegations.revoke`	Ends one of your delegations, or any member's for an owner.

Approvals

In Chat, an operation that changes access, acts outside devboxes, or can't be undone waits for a person's approval, for up to an hour. A member with a role the request names decides it, signed in within the last 10 minutes; a delegation token can't. A request asked in a direct conversation with devboxes is only for the person who asked.

Operation	What it does
`elevation.inspect`	Shows a request you may decide: the operation, its input, and who asked.
`elevation.approve`	Approves a request, so the same call from Chat runs once within 10 minutes.
`elevation.refuse`	Refuses a request.

Model accounts

See Connect a model account.

Operation	What it does
`connections.add`	Connects a model account with an API key.
`connections.list`	Lists your model accounts.
`connections.inspect`	Shows one model account.
`connections.usage`	Shows the usage limits the provider reports for a model account, and the Runs that started on it in the last 30 days with their tokens.
`connections.update`	Renames a model account or replaces its key.
`connections.delete`	Deletes a model account and frees its name. Refused while a Project or the Chat policy selects the account, or while queued or running work uses it. Past Runs and Chat turns keep the account's id.
`providers.list`	Lists the model providers you can connect.
`providers.connect-start`	Starts signing in to a model provider.
`providers.connect-complete`	Finishes signing in to a model provider.
`providers.models`	Lists the models your accounts offer.
`providers.select`	Shows a model that a model selection could use for new work: one weighted pick, without the account a task or thread keeps.

Repositories

See Connect a repository.

Operation	What it does
`repositories.connect`	Connects GitHub with an access token.
`repositories.github-connect-start`	Starts installing the devboxes GitHub App.
`repositories.github-connect-status`	Reads how connecting the devboxes GitHub App went.
`repositories.github-connect-complete`	Connects one of the GitHub accounts that the devboxes GitHub App offers.
`repositories.connections`	Lists your repository connections.
`repositories.disconnect`	Removes a repository connection.
`repositories.catalog`	Lists the repositories a connection can reach.
`repositories.pulls`	Lists open pull requests.
`repositories.review`	Shows a pull request with its description, changes, and review comments.
`repositories.checks`	Shows the checks of a pull request.
`repositories.github-write`	Opens, updates, closes, and comments on GitHub pull requests.
`repositories.merge`	Merges a reviewed or approved GitHub pull request on request.

Issues of every tracker, GitHub included, go through issues.read and issues.write.

Projects

See Create a Project.

Operation	What it does
`projects.create`	Creates a Project.
`projects.configure`	Changes a Project's Runner, machine size, models, commands, fix rounds, tool cache, and connection.
`projects.configure-merging`	Turns on or off whether devboxes merges a Project's pull requests after Review.
`projects.list`	Lists your Projects.
`images.configure`	Changes the packages and services in a Project's workspace.
`images.inspect`	Shows whether a Project's workspace is ready.
`secrets.set`	Sets a variable or a secret.
`secrets.list`	Lists variables and secrets, without secret values.
`secrets.inspect`	Shows one variable or secret and its Projects.
`secrets.scope`	Gives a Project an Organization variable or secret, or removes it.
`secrets.delete`	Deletes a variable or secret.

Runners

See Add a Runner.

Operation	What it does
`capacity.register`	Registers a machine as a Runner.
`capacity.list`	Lists your Runners and whether they are ready.
`capacity.configure`	Turns a Runner on or off and sets its cost.
`capacity.remove`	Removes a Runner.

Billing

See Choose a plan and buy credit. Plans and billing lists the plans, their limits, and the billing errors.

Operation	What it does
`billing.inspect`	Shows your Organization's plan, this month's included and extra usage, its prepaid credit, and what its running and parked work cost.
`billing.prices`	Lists what Basic and Premium cost a month and a year, and the credit packs.
`billing.buy-credits`	Opens a Stripe Checkout page that sells your Organization a pack of prepaid credit. Owners and admins.
`billing.subscribe`	Opens a Stripe Checkout page that subscribes your Organization to Basic or Premium, monthly or yearly. Owners and admins.
`billing.complete-checkout`	Applies the plan of a paid subscription Checkout page when you return from it, before Stripe's own confirmation. Owners and admins.
`billing.change-plan`	Moves your Organization's subscription to another plan or interval at once. Owners and admins.
`billing.set-spending-limit`	Lowers the most extra usage your Organization's paid plan bills a month, or raises it up to the plan's cap. Owners.
`billing.portal`	Opens the Stripe customer portal to cancel the plan, update the payment method, or read invoices. Owners.

Catalogue

See Start from the catalogue.

Operation	What it does
`catalogue.list`	Lists ready Blueprints, their bundles, and the tools they use, and marks which tools are connected.
`catalogue.install`	Creates and commits your Organization's Blueprints from catalogue entries, once per entry.
`catalogue.update`	Moves your Organization's Blueprints from catalogue entries to the entries' newest versions.
`catalogue.remove`	Archives your Organization's Blueprints from catalogue entries; installing an entry again brings its Blueprint back.

Integrations

See Connect an MCP server.

Operation	What it does
`integrations.detect`	Tells how a remote MCP server lets devboxes in: without credentials, through OAuth, or by a key.
`integrations.connect`	Connects a remote MCP server, and returns the sign-in URL for OAuth. Owners and admins.
`integrations.list`	Lists the connected servers, their status, and their tools.
`integrations.tools`	Returns a server's tools with their input schemas.
`integrations.refresh-tools`	Reads a server's tools again and stores them.
`integrations.call`	Calls one tool of a connected server.
`integrations.disconnect`	Disconnects a server and deletes its credentials. Owners and admins.

Blueprints

See Write a Blueprint.

Operation	What it does
`blueprints.create`	Creates a Blueprint and its first, empty draft.
`blueprints.read`	Returns the graph of one version.
`blueprints.replace-draft`	Replaces the graph of a draft.
`blueprints.place-group`	Copies a group of nodes from any version into a draft.
`blueprints.commit`	Commits a draft as the Blueprint's next version.
`blueprints.approve`	Approves a committed version that reaches a sensitive integration.
`blueprints.draft`	Copies a version into a new draft.
`blueprints.discard`	Deletes a draft.
`blueprints.list`	Lists Blueprints, their versions, and the Projects bound to them.
`blueprints.bind`	Limits a Blueprint to a Project, or lifts it.
`blueprints.archive`	Retires a Blueprint.
`integrations.sensitivity`	Lists the sensitive integrations.
`integrations.configure-sensitivity`	Marks an integration sensitive, or not.

The Blueprint graph reference describes the graph that these operations read and write.

Sessions

See Start and follow tasks.

Operation	What it does
`sessions.dispatch`	Starts a task in a new Session. With `grill`, it first asks open decisions in batches; you or your chat thread get a question session.
`sessions.continue`	Gives an existing Session more work.
`sessions.list`	Lists recent Sessions.
`sessions.inspect`	Shows a Session, its Runs, and their progress.
`sessions.refresh-pull-requests`	Reads the pull requests of Sessions from the code host again.
`sessions.unexpected-issues`	Lists unexpected issues across Sessions.
`sessions.events`	Shows the agent's messages and tool calls.
`sessions.questions`	Lists the agent's open questions.
`sessions.input`	Sends the agent a message or an answer.
`sessions.inputs`	Lists your messages and answers to the agent.
`question-sessions.open`	Opens a link and a password that let people without an account read a Session and answer its questions for 12 hours.
`question-sessions.list`	Lists a Session's question sessions and who entered each.
`question-sessions.close`	Closes a question session, so its link and password stop working and its waiting questions go to the Session's thread, when it has one.
`sessions.cancel`	Stops a task.
`sessions.hold-merge`	Keeps devboxes from merging a Session's work.
`sessions.handoff`	Moves a Session into the Chat conversation that asks for it. Only a running Chat turn can run it.
`sessions.artifacts`	Lists the files the agent attached.
`sessions.artifact-download`	Returns a download link for one attached file.
`sessions.usage`	Shows the tokens and the cost of a Session.
`sessions.erase`	Erases a Session.

Review

See Review pull requests.

Operation	What it does
`review.request`	Starts a Review of a task's pull request.
`review.inspect`	Shows a Session's Reviews and their findings.

Schedules

See Run a request on a schedule.

Operation	What it does
`schedules.create`	Sets up a request that runs in a chat thread at the times of a cron pattern or on every new GitHub issue.
`schedules.list`	Lists Schedules with their next fire time and what the latest one did.
`schedules.pause`	Stops a Schedule from firing.
`schedules.resume`	Lets a paused Schedule fire again from its next fire time, or for issues opened after it resumes.
`schedules.run`	Runs a cron Schedule's request once now.
`schedules.delete`	Deletes a Schedule.

Chat and issue trackers

See Connect Slack, Microsoft Teams, Google Chat, Discord, or Telegram and Connect an issue tracker.

Operation	What it does
`chat.configure-policy`	Turns Chat on or off and sets what it may do.
`chat.policy`	Shows the Chat policy.
`chat.connect-slack`	Starts connecting Slack.
`chat.connect-teams`	Starts connecting Microsoft Teams.
`chat.connect-google-chat`	Starts connecting Google Chat.
`chat.connect-discord`	Starts connecting Discord.
`chat.connect-telegram`	Creates a link that connects a Telegram group.
`chat.connect-linear`	Starts connecting Linear.
`chat.connect-jira`	Connects Jira.
`chat.connect-github`	Connects the GitHub issues of a GitHub App installation.
`chat.integrations`	Lists your connected chat and tracker workspaces.
`chat.disconnect`	Disconnects a workspace.
`chat.discover-slack-channels`	Lists the Slack channels devboxes can see.
`chat.channels`	Lists your channels and the Projects assigned to them.
`chat.configure-channel`	Assigns a channel to Projects.
`chat.configure-ambient`	Turns ambient mode on or off for a Discord or Telegram workspace: devboxes answers every person's message in the Telegram group, or in the Discord channels assigned to Projects.
`chat.configure-google-chat-delegation`	Names the Workspace member whose domain-wide delegation devboxes reads a Google Chat workspace's spaces as, to follow thread replies and read thread history, or clears it.
`chat.conversations`	Lists Chat conversations.
`chat.inspect-conversation`	Shows a conversation and the tasks it started.
`chat.zoom`	Opens a line of a conversation's Chat log, or of Organization memory, into its two halves, or a message whole.
`chat.erase-messages`	Erases anyone's messages of a conversation's Chat log, their text and who wrote them, with the Organization memory entries they saved. Owners and admins call it.
`chat.erase-own-messages`	Erases messages that you wrote in a conversation's Chat log, their text and who wrote them, with the Organization memory entries they saved.
`chat.close-conversation`	Closes a conversation and can erase it.
`chat.web-post`	Posts your message to devboxes in a web chat, or starts a new one.
`chat.web-messages`	Shows the messages of your web chat and the tasks it started.
`chat.tell`	Asks the Chat participant the questions that a work-starting turn needs answered. Only a running Chat turn can run it.
`chat.cite-content-request`	Records a person's own request for code or a file, in their whole words, so that the reply and the replies that report the work it starts show code blocks and post media other than images. Only a running Chat turn can run it.
`chat.skip-reply`	Ends a reply that needs no answer, such as thanks, without posting. When the reply must be posted, it refuses with `CHAT_REPLY_OWED` and a `REPLY_OWED_*` code in `details.replyOwed`. Only a running Chat turn can run it.
`chat.post-artifact`	Posts images of the thread's work, or other media that a person asked for, into its Slack thread as one message, or at the top level of its Channel when a person asks. Only a running Chat turn can run it.
`chat.link-account`	Sends the person who asked a private link that links their chat account. Only a running Chat turn can run it.
`chat.add-waiting-work`	Records a request that starts only after other work finishes. Only a running Chat turn in a chat channel can run it, when the Chat policy also allows `sessions.dispatch`.
`chat.resolve-waiting-work`	Removes a waiting request. A Chat participant removes their own requests in their thread; an owner or admin removes any.
`issues.configure`	Binds a Project to a Linear Team, a Jira Project, or a GitHub repository.
`issues.configuration`	Shows a Project's tracker binding.
`issues.disconnect`	Removes a Project's tracker binding.
`issues.read`	Reads issues in the bound Team, Project, or repository.
`issues.write`	Creates, updates, moves, and comments on issues. From Chat, a comment with a code block needs a cited request.

Personas and memory

See Set up Personas and memory.

Operation	What it does
`personas.create`	Creates a Persona.
`personas.list`	Lists active Personas and their channels.
`personas.configure`	Renames a Persona or makes it the default.
`personas.assign`	Uses a Persona in one channel.
`personas.unassign`	Returns a channel to the default Persona.
`personas.deactivate`	Stops a Persona from shaping Chat.
`memory.create`	Adds an entry to Organization memory.
`memory.list`	Lists Organization memory.
`memory.update`	Replaces an entry with new text, credited to you.
`memory.erase`	Erases an entry's text.
`people.policy`	Shows whether personal preferences are on.
`people.configure-policy`	Turns personal preferences on or off.
`people.identify`	Returns your Person, creating it on first use.
`people.link`	Links the chat account in a link from Chat; with `preview`, only names it.
`people.links`	Lists the chat accounts linked to your account.
`people.unlink`	Removes your chat account's link, or an owner or admin removes another member's.
`people.remember`	Stores one of your preferences.
`people.preferences`	Lists your preferences.
`people.correct`	Changes one of your preferences.
`people.forget`	Deletes one of your preferences.

Operations

On this page