Computer Use
Computer use lets an agent act through a managed execution environment when simple tool calls are not enough.
Overview
Computer use gives an agent a managed place to carry out interactive tasks.
Use it when the agent needs to do work that looks more like operating a computer than calling one simple tool.
The mental model is:
- a normal tool call is one clean action
- computer use is a small working environment where the agent can carry out a sequence of visible steps
That breadth is the value, and it's also why computer use carries more operational weight than ordinary tools.
A concrete example
Imagine an agent needs to walk through a browser-based admin interface that does not have one clean API.
Computer use can help the agent:
- open the interface
- navigate through the relevant screens
- gather or enter the needed information
- report the result back into the thread or workflow
That is different from a simple "call this endpoint" tool. It is closer to giving the agent a controlled workstation for a narrow task.
From the CLI, the operational loop looks like this:
archastro list agentcomputers --agent <agent_id>
archastro create agentcomputer --agent <agent_id> -n "ops-workstation"
archastro describe agentcomputer <computer_id>
archastro refresh agentcomputer <computer_id>
archastro exec agentcomputer <computer_id> -c "pwd"
That gives you a real workflow for provisioning, checking readiness, and validating the environment before you ask the agent to rely on it.
What computer use is not
Computer use is not the default way agents should operate.
It is the wrong choice when:
- one explicit API or tool call would do
- the task can be expressed as a clean workflow step
- the task is sensitive enough that a human should do it directly
The point is not to make agents click around for the sake of it. The point is to give them a controlled way to handle the cases where interactive work is genuinely necessary.
When it helps
Computer use is a good fit when an agent needs to:
- work through a multi-step interface
- inspect or manipulate a system that is not exposed as one clean API
- carry out a guided operational task
It is not the right first choice for everything. If a smaller, clearer tool will do, use the smaller tool.
If you can express the action as one explicit tool, do that first. Reach for computer use when the work is genuinely interactive.
Built-in tools
Agents can use computers during conversations through these built-in tools:
computer_exec
Execute a shell command on the agent's computer.
| Parameter | Type | Required | Description |
|---|---|---|---|
command |
string | Yes | Shell command to execute |
working_directory |
string | No | Working directory. Defaults to the computer's primary repository checkout, or its home directory when it has none. |
Returns stdout, exit_code, and status.
computer_write_file
Write content to a file on the computer.
| Parameter | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | Absolute file path |
content |
string | Yes | File content to write |
computer_read_file
Read the contents of a file from the computer.
| Parameter | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | Absolute file path |
computer_attach_file
Attach an image from the computer to the agent's reply, so the user sees it in the thread (for example a browser screenshot). PNG, JPEG, GIF and WebP up to 10 MB; the type is detected from the file's bytes.
| Parameter | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | Path of the image file on the computer |
filename |
string | No | Display name. Defaults to the file's name. |
computer |
string | No | Thread computer key, when the thread has more than one. |
Returns success, media_id, content_type, filename, size and sha256.
computer_run_start
Start a coding agent on the computer and return at once with a run_id. The default is ArchDev; Claude Code and Codex run on request. It is the same run that archdev computers run starts, so the computer's owner can follow it with archdev computers run-status, and each finished turn arrives in the agent's conversation as a follow-up.
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt |
string | Yes | What the coding agent should do. It starts with no other context. |
harness |
string | No | archdev (default), claude or codex. |
model |
string | No | Model for the run. Defaults to Platform GPT-6.1 Sol with low thinking for ArchDev and opus for Claude Code. Codex uses its own default. |
working_directory |
string | No | Defaults to the computer's primary repository checkout, or its home directory. |
computer |
string | No | Thread computer key, when the thread has more than one. |
The run needs a ready computer owned by a user, with computerd. ArchDev signs in as the computer's owner, so it uses Platform-hosted models as that user; Claude Code and Codex use the platform's model keys. The agent needs no GitHub installation and no sub-agents tool.
An ArchDev run can also read private Intern sites as the computer's owner. When a prompt links a page under the Intern site zone (tryintern.dev) and the direct fetch is refused with 401 or 403, ArchDev's web_fetch reads it through Intern with a credential Platform delegates to Intern for that user, so a spec linked from a thread message reaches the run. Pages the owner cannot open stay unreadable; a site on a custom domain is not recognized as an Intern site.
computer_run_send
Send a follow-up message to a run the agent started. It continues the same harness conversation as a new turn, once the current turn has finished.
| Parameter | Type | Required | Description |
|---|---|---|---|
run_id |
string | Yes | Run id returned by computer_run_start |
prompt |
string | Yes | The follow-up message |
computer_run_status
Read a run's status, turn count, exit code and the end of its latest output.
| Parameter | Type | Required | Description |
|---|---|---|---|
run_id |
string | Yes | Run id returned by computer_run_start |
use_claude (removed)
use_claude no longer starts anything. The name stays registered so agents and stored sessions that mention it keep resolving, and a call returns a message pointing at computer_run_start, computer_run_send and computer_run_status.
Tool resolution
When an agent uses computer tools, the platform automatically routes the request to a ready computer associated with that agent.
Safety guidelines
Computer use increases agent capability, so it needs stronger guardrails.
Before enabling computer use, be clear on:
- what environment the agent can use
- what actions are allowed
- what approvals exist
- how a human can review the result
From the CLI:
- inspect the computer status before using it
- keep the environment narrow
- destroy computers you no longer need
Best practices
- Start with narrow tasks.
- Keep the environment limited to the work at hand.
- Put sensitive actions behind explicit approval.
- Review outputs and logs regularly.
- Prefer simpler tools when they cover the task.
Need something clearer?
Tell us where this page still falls short.
If a step is confusing, a diagram is misleading, or a workflow needs a better example, send feedback directly and we will tighten it.