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: 4.1.0
Installation
Quick Start
Dynamic tools are registered after attaching via session.setDynamicTools(). Pass the computer directly - the session extracts schemas and handlers from the ToolProvider. Tool schemas are sent to the platform on the next execute() call, 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.
Dynamic Entries
You can add or remove MCP entries on a running Computer after start() has returned. This is useful when MCP configurations arrive after construction - for example, when a session-manager receives per-session entries from a dispatch payload and wants to wire them into the existing computer instead of rebuilding it.
addEntry(namespace, entry, options?)
Registers a new MCP entry under namespace. By default, connects immediately:
Pass { deferred: true } to register the entry without connecting. The entry starts in a degraded state and connects on the next restartEntry(namespace) call - useful for lazy MCPs the agent activates on demand:
addEntry throws if the namespace already exists. To replace an entry, call removeEntry first.
If the immediate connection fails, addEntry does not throw - the entry is registered as degraded with the error message attached. Inspect via getHealth() or restartEntry() to retry.
removeEntry(namespace)
Closes the entry's connection (if any) and drops it from the configuration. No-op when the namespace doesn't exist:
restartEntry(namespace)
Closes the existing connection (if any) and reconnects with the current configuration:
Use this to bring a deferred entry online for the first time, or to recover an entry that became degraded mid-session.
Detecting dynamic-entry support
Consumers that work with arbitrary ToolProvider implementations can detect dynamic-entry capability with isDynamicMcpProvider:
Computer always passes this check.
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:
setDynamicTools() accepts any ToolProvider directly - the session extracts schemas and handlers automatically:
You can also pass a custom ToolProvider:
For cases where you need explicit control, setDynamicTools() also accepts a DynamicTool[] array:
Complete Example
A desktop application with browser, filesystem, and shell capabilities: