ArchAstro Docs

Overview

Computer Use lets agents provision and control remote Linux machines. Agents can execute shell commands, read and write files, and complete development or operational tasks through the platform API or built-in AI tools.

Computers remain available across commands, so agents can complete multi-step workflows over time instead of starting from scratch for every action.

Provisioning a computer

Create a computer for an agent through the SDK or API:

const computer = await client.rest.createAgentComputer(agent.id, {
  name: "dev-machine",
  lookup_key: "primary",
  region: "iad",
  metadata: {
    purpose: "ci-runner",
  },
});

console.log("Computer:", computer.id);
console.log("Status:", computer.status);

Provisioning is asynchronous. The computer starts in pending, moves through provisioning, and becomes ready when it can accept commands.

Computer statuses

Status	Meaning
`pending`	Created, not yet provisioned
`provisioning`	Environment setup in progress
`ready`	Live and accepting commands
`error`	Provisioning failed
`destroyed`	Marked for deletion

Computer properties

Field	Type	Description
`id`	string	Computer ID
`name`	string	Display name
`lookup_key`	string	Unique per agent
`status`	enum	Current state
`region`	string	Deployment region
`config`	object	Custom configuration
`metadata`	object	Arbitrary metadata
`error_message`	string	Error details if provisioning failed
`last_active_at`	datetime	Last command execution time

Executing commands

Once a computer is ready, execute shell commands:

const result = await client.rest.execComputerCommand(computer.id, {
  command: "git clone https://github.com/org/repo.git && cd repo && npm test",
  dir: "/home/sprite",
});

console.log("Output:", result.output);
console.log("Exit code:", result.exit_code);
console.log("Status:", result.status);

Commands run with a timeout, and the working directory defaults to the computer's home directory.

Environment

Computers provide a Linux development environment suitable for common scripting, repository, and build tasks.

Typical capabilities include:

source checkout and file operations
package installation and dependency management
test and build execution
multi-step scripted workflows over persistent files

Use Computer Use only where it fits your security, approval, and operational model.

AI tools

Agents can use computers during conversations through three 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

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

Tool resolution

When an agent uses computer tools, the platform automatically routes the request to a ready computer associated with that agent.

Managing computers

const computers = await client.rest.listAgentComputers(agent.id);
const computer = await client.rest.getAgentComputer(computerId);

await client.rest.refreshAgentComputer(computerId);
await client.rest.destroyAgentComputer(computerId);

API reference

Operation	Endpoint	Description
Create	`POST /agents/:id/computers`	Provision a new computer
List	`GET /agents/:id/computers`	List computers for an agent
Show	`GET /agents/:id/computers/:computer_id`	Get computer details
Exec	`POST /agents/:id/computers/:computer_id/exec`	Execute a command
Refresh	`POST /agents/:id/computers/:computer_id/refresh`	Refresh status
Delete	`DELETE /agents/:id/computers/:computer_id`	Destroy a computer

Computer Use