Computer
The @octavus/computer package gives agents access to a physical or virtual machine's browser, filesystem, and shell. It connects to MCP servers, discovers their tools, and provides them to the server-sdk.
Current version: 2.19.0
Installation
Quick Start
The computer is passed to attach() — the server-sdk handles the rest. Tool schemas are sent to the platform, and tool calls flow back through the existing execution loop.
How It Works
- You configure MCP servers with namespaces (e.g.,
browser,filesystem,shell) computer.start()connects to all servers in parallel and discovers their tools- Each tool is namespaced with
__(e.g.,browser__navigate_page,filesystem__read_file) - The server-sdk sends tool schemas to the platform and handles tool call execution
The agent's protocol must declare matching mcpServers with source: device — see MCP Servers.
Entry Types
The Computer class supports three types of MCP entries:
Stdio (MCP Subprocess)
Spawns an MCP server as a child process, communicating via stdin/stdout:
Use this for local MCP servers installed as npm packages or standalone executables:
HTTP (Remote MCP Endpoint)
Connects to an MCP server over Streamable HTTP:
Use this for MCP servers running as HTTP services:
Shell (Built-in)
Provides shell command execution without spawning an MCP subprocess:
This exposes a run_command tool (namespaced as shell__run_command when the key is shell). Commands execute in a login shell with the user's full environment.
Shell Safety Modes
| Mode | Description |
|---|---|
'unrestricted' | All commands allowed (for dedicated machines) |
{ allowedPatterns, blockedPatterns } | Pattern-based command filtering |
Pattern-based filtering:
When allowedPatterns is set, only matching commands are permitted. When blockedPatterns is set, matching commands are rejected. Blocked patterns are checked first.
Lifecycle
Starting
computer.start() connects to all configured MCP servers in parallel. If some servers fail to connect, the computer still starts with the remaining servers — only if all connections fail does it throw an error.
Stopping
computer.stop() closes all MCP connections and kills managed processes:
Always call stop() when the session ends to clean up MCP subprocesses. For managed processes (like Chrome), pass them in the config for automatic cleanup.
Chrome Launch Helper
For desktop applications that need to control a browser, Computer.launchChrome() launches Chrome with remote debugging enabled:
Pass the browser to managedProcesses for automatic cleanup when the computer stops:
ChromeLaunchOptions
| Field | Required | Description |
|---|---|---|
profileDir | Yes | Directory for Chrome's user data (profile isolation) |
debuggingPort | No | Port for remote debugging (auto-allocated if omitted) |
flags | No | Additional Chrome launch flags |
ToolProvider Interface
Computer implements the ToolProvider interface from @octavus/core:
The server-sdk accepts any ToolProvider on the computer option — you can implement your own if @octavus/computer doesn't fit your use case:
Complete Example
A desktop application with browser, filesystem, and shell capabilities: