Machine API Reference

Complete API reference for the Machine class.

Constructor

new Machine(config: MachineConfig)

Machine(config: MachineConfig)

Static Methods

create()

Create and start a machine in one call.

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

// Usage
const machine = await Machine.create({ name: 'my-machine' });

@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.

async start(): Promise<void>

async def start(self) -> None

stop()

Stop the machine.

async stop(): Promise<void>

async def stop(self) -> None

delete()

Delete the machine permanently.

async delete(): Promise<void>

async def delete(self) -> None

status()

Get current machine information.

async status(): Promise<MachineInfo>

interface MachineInfo {
  name: string;
  state: MachineState;
  created_at?: string;
  started_at?: string;
}

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.

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

interface ExecOptions {
  timeout?: number;  // milliseconds
  env?: Record<string, string>;
  workdir?: string;
}

async def exec(
    self,
    command: List[str],
    env: Optional[Dict[str, str]] = None,
    workdir: Optional[str] = None,
    timeout: Optional[int] = None  # seconds
) -> ExecResult

run()

Run a command in a container image.

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

async def run(
    self,
    image: str,
    command: List[str],
    env: Optional[Dict[str, str]] = None,
    workdir: Optional[str] = None,
    timeout: Optional[int] = None
) -> ExecResult

createContainer()

Create a managed container.

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

interface ContainerCreateOptions {
  image: string;
  command?: string[];
  env?: Record<string, string>;
  workdir?: string;
  mounts?: ContainerMount[];
}

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.

async listContainers(): Promise<ContainerInfo[]>

async def list_containers(self) -> List[ContainerInfo]

getContainer()

Get a container by ID.

async getContainer(id: string): Promise<Container>

async def get_container(self, id: str) -> Container

pullImage()

Pull a container image.

async pullImage(image: string): Promise<void>

async def pull_image(self, image: str) -> None

listImages()

List available images.

async listImages(): Promise<ImageInfo[]>

async def list_images(self) -> List[ImageInfo]

Types

MachineConfig

interface MachineConfig {
  name: string;
  serverUrl?: string;
  mounts?: MountSpec[];
  ports?: PortSpec[];
  resources?: ResourceSpec;
}

@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

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

  assertSuccess(): void;  // throws if exitCode !== 0
}

@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

interface MountSpec {
  source: string;
  target: string;
  readonly?: boolean;
}

@dataclass
class MountSpec:
    source: str
    target: str
    readonly: bool = False

ResourceSpec

interface ResourceSpec {
  cpus?: number;
  memoryMb?: number;
}

@dataclass
class ResourceSpec:
    cpus: Optional[int] = None
    memory_mb: Optional[int] = None

MachineState

type MachineState =
  | 'created'
  | 'running'
  | 'stopped';

class MachineState(Enum):
    CREATED = "created"
    RUNNING = "running"
    STOPPED = "stopped"