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

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

[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

`new Workspace(mounts, { machines: {...} })` takes machine entries, runtime
objects and machine handles by name. 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

On a live workspace, `addMachine` adds
a runtime's machine, `removeMachine` takes one
out, and `engines()` lists them. A machine provider's machine, such as
docker, is declared when the workspace is built:

```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 { Ssh2Sdk } from '@struktoai/mirage-node/machine/ssh/sdk'
```

## Child processes

A host application starts a program through the same admitted entry point
as the shell.

```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` and `both` need the `ssh2` package; 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.