Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Conway-Research/automaton/llms.txt

Use this file to discover all available pages before exploring further.

VM tools provide core infrastructure operations for interacting with your agent’s execution environment.

​
Command Execution

​
exec

Execute a shell command in your sandbox.
​
command
string
required
The shell command to execute
​
timeout
number
default:30000
Timeout in milliseconds
Risk Level: caution Returns: Exit code, stdout, and stderr as formatted string 
await exec({
  command: 'npm install axios',
  timeout: 60000
});
// Returns: "exit_code: 0\nstdout: added 5 packages...\nstderr: "
Self-Preservation GuardsThe following command patterns are blocked:
  • rm -rf .automaton - Self-destruction
  • kill automaton - Process termination
  • cat wallet.json - Credential harvesting
  • sed injection-defense - Safety bypass
See full list in source code (lines 38-66).

​
File Operations

​
write_file

Write content to a file in your sandbox.
​
path
string
required
File path (relative or absolute)
​
content
string
required
File content to write
Risk Level: caution Returns: Success message with file path 
await write_file({
  path: '/workspace/config.json',
  content: JSON.stringify({ env: 'production' }, null, 2)
});
Protected files (injection-defense, audit-log, policy engine core) cannot be overwritten. Use edit_own_file with proper auditing for self-modification.

​
read_file

Read content from a file in your sandbox.
​
path
string
required
File path to read
Risk Level: safe Returns: File contents as string 
const config = await read_file({
  path: '/workspace/config.json'
});
Sensitive File ProtectionThe following files are blocked from reading:
  • wallet.json - Private keys
  • .env - Environment secrets
  • automaton.json - Agent configuration
  • *.key, *.pem - Cryptographic keys
  • private-key* - Any private key files

​
Port Management

​
expose_port

Expose a port from your sandbox to the internet.
​
port
number
required
Port number to expose (e.g., 3000, 8080)
Risk Level: caution Returns: Public URL for the exposed port
Example
const result = await expose_port({ port: 3000 });
// Returns: "Port 3000 exposed at: https://abc123.conway.run"
Use this to host web services, APIs, or webhooks from your agent. The URL is publicly accessible and persists until removed.

​
remove_port

Remove a previously exposed port.
​
port
number
required
Port number to remove
Risk Level: caution Returns: Confirmation message
Example
await remove_port({ port: 3000 });
// Returns: "Port 3000 removed"

​
Usage Patterns

​
Install and Run Service

// 1. Install dependencies
await exec({
  command: 'npm install express',
  timeout: 60000
});

// 2. Write server code
await write_file({
  path: '/app/server.js',
  content: `
const express = require('express');
const app = express();
app.get('/', (req, res) => res.json({ status: 'alive' }));
app.listen(3000);
`
});

// 3. Start server
await exec({
  command: 'node /app/server.js &',
  timeout: 5000
});

// 4. Expose port
await expose_port({ port: 3000 });

​
Deploy Script

// Write deployment script
await write_file({
  path: '/scripts/deploy.sh',
  content: `#!/bin/bash
set -e
git pull origin main
npm install
npm run build
npm test
`
});

// Make executable and run
await exec({ command: 'chmod +x /scripts/deploy.sh' });
await exec({
  command: '/scripts/deploy.sh',
  timeout: 180000
});

​
File Processing Pipeline

// Read input
const input = await read_file({ path: '/data/input.json' });
const data = JSON.parse(input);

// Process
const processed = data.map(item => ({
  ...item,
  timestamp: new Date().toISOString()
}));

// Write output
await write_file({
  path: '/data/output.json',
  content: JSON.stringify(processed, null, 2)
});

​
Error Handling

// exec returns exit codes
const result = await exec({ command: 'test -f /missing.txt' });
if (result.includes('exit_code: 1')) {
  console.log('File does not exist');
}

// read_file returns error messages
try {
  const content = await read_file({ path: '/nonexistent' });
  if (content.startsWith('ERROR:')) {
    console.log('File not found');
  }
} catch (err) {
  console.error('Read failed:', err);
}

​
Best Practices

Prefer absolute paths (/workspace/file.txt) over relative paths to avoid ambiguity.
Long-running commands (builds, tests) need higher timeouts. Default is 30 seconds.
Always verify exit_code: 0 for successful command execution.
Avoid user input in commands without validation. The policy engine provides defense-in-depth.
Use & suffix for long-running processes: node server.js &

Git Tools

Version control operations

Self-Modification

Edit your own codebase

Conway Sandboxes

Sandbox management

Policy Engine

Command validation rules

Build docs developers (and LLMs) love

Get started for freeTalk to us