Quick Start

The Machine class runs against the local embedded engine by default (no server) or the smolfleet cloud — same API, backend chosen via ConnectOptions. TypeScript is async; Python is synchronous.

Machine Lifecycle

Create a machine, run commands on it, and clean it up. In TypeScript, use try/finally; in Python, the Machine is a context manager that deletes itself on exit.

import { Machine } from 'smolmachines';

// Create and auto-start a machine (local embedded engine)
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.delete();
}
from smol import Machine, MachineConfig

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

# Context manager handles cleanup automatically
with Machine.create(config) as machine:
    # Execute multiple commands
    result1 = machine.exec(["uname", "-a"])
    print(result1.stdout)

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

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

Running on the Cloud

The same code runs on the smolfleet cloud — pass a ConnectOptions (or set SMOL_CLOUD_TOKEN). image is required on the cloud target.

import { Machine } from 'smolmachines';

const machine = await Machine.create(
  { image: 'python:3.12' },
  { target: 'cloud', apiKey: 'smk_...' }
);
try {
  const res = await machine.exec(['python', '-c', 'print(2 ** 10)']);
  console.log(res.stdout); // "1024"
  console.log(await machine.url()); // public ingress URL
} finally {
  await machine.delete();
}
from smol import Machine, MachineConfig, ConnectOptions

with Machine.create(
    MachineConfig(image="python:3.12"),
    ConnectOptions(target="cloud", api_key="smk_..."),
) as machine:
    res = machine.exec(["python", "-c", "print(2 ** 10)"])
    print(res.stdout)      # "1024"
    print(machine.url())   # public ingress URL

Working with Results

Command execution returns an ExecResult object:

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();
result = 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