smol machines

Machine API Reference ​

Complete API reference for the Machine class.

Constructor ​

typescript
new Machine(config: MachineConfig)
python
Machine(config: MachineConfig)

Static Methods ​

create() ​

Create and start a machine in one call.

typescript
static async create(config: MachineConfig): Promise<Machine>

// Usage
const machine = await Machine.create({ name: 'my-machine' });
python
@classmethod
async def create(cls, config: MachineConfig) -> Machine

# Usage
machine = await Machine.create(MachineConfig(name="my-machine"))

Instance Methods ​

start() ​

Create and start the machine.

typescript
async start(): Promise<void>
python
async def start(self) -> None

stop() ​

Stop the machine.

typescript
async stop(): Promise<void>
python
async def stop(self) -> None

delete() ​

Delete the machine permanently.

typescript
async delete(): Promise<void>
python
async def delete(self) -> None

status() ​

Get current machine information.

typescript
async status(): Promise<MachineInfo>

interface MachineInfo {
  name: string;
  state: MachineState;
  created_at?: string;
  started_at?: string;
}
python
async def status(self) -> MachineInfo

@dataclass
class MachineInfo:
    name: str
    state: MachineState
    created_at: Optional[str]
    started_at: Optional[str]

exec() ​

Execute a command in the microVM.

typescript
async exec(
  command: string[],
  options?: ExecOptions
): Promise<ExecResult>

interface ExecOptions {
  timeout?: number;  // milliseconds
  env?: Record<string, string>;
  workdir?: string;
}
python
async def exec(
    self,
    command: List[str],
    *,
    timeout: Optional[float] = None,  # seconds
    env: Optional[Dict[str, str]] = None,
    workdir: Optional[str] = None
) -> ExecResult

run() ​

Run a command in a container image.

typescript
async run(
  image: string,
  command: string[],
  options?: ExecOptions
): Promise<ExecResult>
python
async def run(
    self,
    image: str,
    command: List[str],
    *,
    timeout: Optional[float] = None,
    env: Optional[Dict[str, str]] = None,
    workdir: Optional[str] = None
) -> ExecResult

createContainer() ​

Create a managed container.

typescript
async createContainer(options: ContainerCreateOptions): Promise<Container>

interface ContainerCreateOptions {
  image: string;
  command?: string[];
  env?: Record<string, string>;
  workdir?: string;
  mounts?: ContainerMount[];
}
python
async def create_container(
    self,
    image: str,
    *,
    command: Optional[List[str]] = None,
    env: Optional[Dict[str, str]] = None,
    workdir: Optional[str] = None,
    mounts: Optional[List[ContainerMount]] = None
) -> Container

listContainers() ​

List all containers in the machine.

typescript
async listContainers(): Promise<ContainerInfo[]>
python
async def list_containers(self) -> List[ContainerInfo]

getContainer() ​

Get a container by ID.

typescript
async getContainer(id: string): Promise<Container>
python
async def get_container(self, id: str) -> Container

pullImage() ​

Pull a container image.

typescript
async pullImage(image: string): Promise<void>
python
async def pull_image(self, image: str) -> None

listImages() ​

List available images.

typescript
async listImages(): Promise<ImageInfo[]>
python
async def list_images(self) -> List[ImageInfo]

Types ​

MachineConfig ​

typescript
interface MachineConfig {
  name: string;
  serverUrl?: string;
  mounts?: MountSpec[];
  ports?: PortSpec[];
  resources?: ResourceSpec;
}
python
@dataclass
class MachineConfig:
    name: str
    server_url: str = "http://127.0.0.1:8080"
    mounts: List[MountSpec] = field(default_factory=list)
    ports: List[PortSpec] = field(default_factory=list)
    resources: Optional[ResourceSpec] = None

ExecResult ​

typescript
interface ExecResult {
  exitCode: number;
  stdout: string;
  stderr: string;
  success: boolean;
  output: string;

  assertSuccess(): void;  // throws if exitCode !== 0
}
python
@dataclass
class ExecResult:
    exit_code: int
    stdout: str
    stderr: str

    @property
    def success(self) -> bool: ...

    @property
    def output(self) -> str: ...

    def assert_success(self) -> None: ...  # raises if exit_code != 0

MountSpec ​

typescript
interface MountSpec {
  source: string;
  target: string;
  readonly?: boolean;
}
python
@dataclass
class MountSpec:
    source: str
    target: str
    readonly: bool = False

ResourceSpec ​

typescript
interface ResourceSpec {
  cpus?: number;
  memoryMb?: number;
}
python
@dataclass
class ResourceSpec:
    cpus: Optional[int] = None
    memory_mb: Optional[int] = None

MachineState ​

typescript
type MachineState =
  | 'pending'
  | 'starting'
  | 'running'
  | 'stopping'
  | 'stopped'
  | 'failed';
python
class MachineState(Enum):
    PENDING = "pending"
    STARTING = "starting"
    RUNNING = "running"
    STOPPING = "stopping"
    STOPPED = "stopped"
    FAILED = "failed"