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

# Route Machine

> Run each line or command on the machine that fits it, chosen by a policy.

An agent types into one shell, and a [machine](https://docs.mirage.strukto.ai/home/setup/machine/overview.md)
runs its programs. Without a route, each program goes to the first machine
whose `captures` name it. A route picks by what the line does instead: a
quick Python snippet stays on Monty inside Mirage, a training job goes to the
GPU, and each agent gets its own container. The agent types the same
commands either way.

The [Multi-machine Terminal](https://docs.mirage.strukto.ai/home/examples/multi-machine-terminal.md) example
routes each Python command across four machines by the library its code
uses.

## Route a line

`pre_execute` places a whole line. Here the jobs under `/jobs/` run on a CPU
container, the GPU jobs on a GPU container, and everything else on Monty:

```yaml theme={null}
mode: exec
machines:
  py:
    provider: in_process
    runtime: monty
  box:
    provider: docker
    container: my-box
    captures: ["@python"]
  gpu:
    provider: docker
    container: my-gpu
    captures: ["@python"]
route_policy: {script: ./route.py, runtime: monty}
```

```python route.py theme={null}
def pre_execute(ctx):
    paths = [p for c in ctx["commands"] for p in c["paths"]]
    if any(p.startswith("/jobs/gpu/") for p in paths):
        return {"kind": "route", "machine": "gpu"}
    if any(p.startswith("/jobs/") for p in paths):
        return {"kind": "route", "machine": "box"}
```

`python3 /jobs/gpu/train.py` runs in `my-gpu`, `python3 /jobs/train.py` in
`my-box`, and `cat data.csv | python3 -c "..."` stays on Monty. A line that
names no machine runs where `captures` sends it.

`route_policy` answers for every session. To give each agent its own
machine, route by the session:

```python route.py theme={null}
def pre_execute(ctx):
    return {"kind": "route", "machine": ctx["session_id"]}
```

## Route a command

`pre_command` places one command, so the rest of the line stays where it
is: in `ls; python3 train.py`, only `python3` moves. As a profile's program,
it routes that profile's sessions:

```yaml theme={null}
profiles:
  agent:
    policy:
      pre_command:
        - {script: ./route.py}
```

```python route.py theme={null}
def pre_command(ctx):
    if ctx["command"].startswith("python") and "torch" in " ".join(ctx["argv"]):
        return {"kind": "route", "machine": "gpu", "reason": "PyTorch trains on the GPU"}
```

The Multi-machine Terminal's
[route.py](https://docs.mirage.strukto.ai/home/examples/multi-machine-terminal.md#routing) also reads the
script a command runs, to route `python3 train.py` by its imports.

## In code

`route_policy` also takes a function, which returns a machine name or
nothing:

```python Python theme={null}
from mirage.policy import RouteContext

def route(ctx: RouteContext) -> str | None:
    paths = [p.virtual for c in ctx.commands for p in c.paths]
    return "gpu" if any(p.startswith("/jobs/gpu/") for p in paths) else None

ws = Workspace(mounts, machines=machines, route_policy=route)
```

```typescript TypeScript theme={null}
const ws = new Workspace(mounts, {
  machines,
  routePolicy: (ctx) =>
    ctx.commands.some((c) => c.paths.some((p) => p.virtual.startsWith('/jobs/gpu/')))
      ? 'gpu'
      : null,
})
```

A [policy class](https://docs.mirage.strukto.ai/home/policy/policies.md) returns `Route(machine=...)` from
[`pre_execute`](https://docs.mirage.strukto.ai/home/policy/line#pre_execute) or
[`pre_command`](https://docs.mirage.strukto.ai/home/policy/command), and a caller can name the machine for
one line: `ws.shell(line, machine="gpu")`, or `{ machine: 'gpu' }` in
TypeScript. [Explain](https://docs.mirage.strukto.ai/home/policy/explain.md) shows the machine each command
would run on.

## Ask a model

A route script can ask an LLM where a line should run. Scripts on Monty have
no network, so the model call is a
[host function](https://docs.mirage.strukto.ai/home/policy/scripts.md#host-functions). See the example in
[Python](https://github.com/strukto-ai/mirage/tree/main/examples/python/policy/llm_routing)
and
[TypeScript](https://github.com/strukto-ai/mirage/tree/main/examples/typescript/policy/llm_routing).


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