VM & File Tools

Execute commands, manage files, and control ports in your Conway sandbox

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

Example

await exec({
  command: 'npm install axios',
  timeout: 60000
});
// Returns: "exit_code: 0\nstdout: added 5 packages...\nstderr: "

Self-Preservation Guards

The 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

Create File

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

Read Config

const config = await read_file({
  path: '/workspace/config.json'
});

Sensitive File Protection

The 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

Use absolute paths

Prefer absolute paths (/workspace/file.txt) over relative paths to avoid ambiguity.

Set appropriate timeouts

Long-running commands (builds, tests) need higher timeouts. Default is 30 seconds.

Check exit codes

Always verify exit_code: 0 for successful command execution.

Sanitize command inputs

Avoid user input in commands without validation. The policy engine provides defense-in-depth.

Background processes

Use & suffix for long-running processes: node server.js &

Related

Git Tools

Version control operations

Self-Modification

Edit your own codebase

Conway Sandboxes

Sandbox management

Policy Engine

Command validation rules