Skip to main content
A machine is where programs such as python3 and node run: inside Mirage (in_process with a runtime), on the host, or in a container or sandbox. Machines explains routing, captures and each provider. This page covers what is particular to the TypeScript SDK; each machine’s page has its install and a runnable example.

Declare machines

Each entry in new Workspace(mounts, { machines: {...} }) is a config object, a runtime object or a machine handle. By default, the first machine whose captures names a program runs it:
Config objects are camelCase in code (sandboxId, mountType); YAML spells the same keys in snake_case.

Change them on a live workspace

Machine providers such as docker and ssh can only be set in the constructor. On a running workspace, addMachine(name, spec) adds a runtime or a host or remote machine, removeMachine(name) removes one, and engines() lists them:
python3 moves to the new machine at once. A running line finishes before its removed runtime closes, a removed instance cannot be added again, and workspace cannot be removed. registerRuntime(name, cls) makes your own runtime class available by name in YAML. The @external capture is also exported as EXTERNAL_COMMANDS. A machine subclass that overrides loadSdk() imports the SDK type from the provider’s sdk module. The E2B one needs pnpm add @struktoai/mirage-core:

Child processes

ws.spawn starts a program from your code with the same policy checks as a shell command.

TypeScript SDK notes

  • Local: in @struktoai/mirage-node only. With neither home nor MIRAGE_LOCAL_HOME, python3 is the one on PATH.
  • Machines: in @struktoai/mirage-node; e2b also runs in browsers. mountType ssh needs the ssh2 package, and mirage and both need Node; a browser serves no files into a machine. The ssh machine authenticates through SSH_AUTH_SOCK when there is no identityFile, and username defaults to the local user.