> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Machines in TypeScript

> Declare machines in TypeScript, change them on a live workspace, and start programs from code.

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](https://docs.mirage.strukto.ai/home/setup/machine/overview.md) 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:

```ts theme={null}
import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace(
  { '/data': new RAMVFS() },
  {
    mode: MountMode.EXEC,
    machines: {
      py: { provider: 'in_process', runtime: 'monty' },
      box: { provider: 'docker', container: 'my-sandbox' },
    },
  },
)
await ws.shell("python3 -c 'print(1 + 1)'")
```

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:

```ts theme={null}
await ws.removeMachine('py')
ws.addMachine('py', { provider: 'in_process', runtime: 'pyodide' })
```

`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`:

```ts theme={null}
import type { E2bSdk } from '@struktoai/mirage-core/machine/e2b/sdk'
import type { DaytonaSdk } from '@struktoai/mirage-node/machine/daytona/sdk'
import type { SshSdk } from '@struktoai/mirage-node/machine/ssh/sdk'
```

## Child processes

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

```ts theme={null}
const child = ws.spawn({ argv: ['cat'] })
const result = await child.communicate(new TextEncoder().encode('hello\n'))
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.