smol machines

Quick Start ​

One-Shot Execution ​

The simplest way to run code in a machine:

typescript
import { quickExec, quickRun } from 'smolvm';

// Execute a command in the microVM
const result = await quickExec(['echo', 'Hello from microVM!']);
console.log(result.stdout);

// Run code in a container
const pyResult = await quickRun(
  'python:3.12-alpine',
  ['python', '-c', 'print("Hello from Python!")']
);
console.log(pyResult.stdout);
python
from smolvm import quick_exec, quick_run

# Execute a command in the microVM
result = await quick_exec(["echo", "Hello from microVM!"])
print(result.stdout)

# Run code in a container
py_result = await quick_run(
    image="python:3.12-alpine",
    command=["python", "-c", "print('Hello from Python!')"]
)
print(py_result.stdout)

Machine Lifecycle ​

For more control, manage the machine lifecycle explicitly:

typescript
import { Machine } from 'smolvm';

// Create and auto-start a machine
const machine = await Machine.create({ name: 'my-machine' });

try {
  // Execute multiple commands
  const result1 = await machine.exec(['uname', '-a']);
  console.log(result1.stdout);

  const result2 = await machine.exec(['whoami']);
  console.log(result2.stdout);

  // Run in a container
  const pyResult = await machine.run(
    'python:3.12-alpine',
    ['python', '-c', 'print(2 + 2)']
  );
  console.log(pyResult.stdout); // "4"
} finally {
  await machine.stop();
  await machine.delete();
}
python
from smolvm import Machine, MachineConfig

config = MachineConfig(name="my-machine")

# Context manager handles cleanup automatically
async with Machine(config) as machine:
    await machine.start()

    # Execute multiple commands
    result1 = await machine.exec(["uname", "-a"])
    print(result1.stdout)

    result2 = await machine.exec(["whoami"])
    print(result2.stdout)

    # Run in a container
    py_result = await machine.run(
        "python:3.12-alpine",
        ["python", "-c", "print(2 + 2)"]
    )
    print(py_result.stdout)  # "4"
# Automatically stops and deletes

With Helper Function ​

For short-lived tasks, use the helper for automatic cleanup:

typescript
import { withMachine } from 'smolvm';

const result = await withMachine(
  { name: 'temp' },
  async (machine) => {
    return machine.exec(['whoami']);
  }
);
console.log(result.stdout);
// Machine automatically stopped and deleted
python
from smolvm import with_machine, MachineConfig

async with with_machine(MachineConfig(name="temp")) as machine:
    result = await machine.exec(["whoami"])
    print(result.stdout)
# Machine automatically stopped and deleted

Working with Results ​

Command execution returns an ExecResult object:

typescript
const result = await machine.exec(['ls', '-la']);

console.log(result.exitCode);  // number
console.log(result.stdout);    // string
console.log(result.stderr);    // string
console.log(result.success);   // boolean (exitCode === 0)

// Throw if command failed
result.assertSuccess();
python
result = await machine.exec(["ls", "-la"])

print(result.exit_code)  # int
print(result.stdout)     # str
print(result.stderr)     # str
print(result.success)    # bool (exit_code == 0)

# Raise if command failed
result.assert_success()

Next Steps ​