# Tools on your own machine

> Host tools — let a loop read a file or run a command on your own machine, through rxr, and only what a file on that machine allows

A loop runs on plutonium.io, not on your computer. A **host tool** is how a loop reaches your
own machine all the same: it reads a file there, writes one, or runs a command. It does so
through [`rxr`](/docs/guide/command-line.md), and only as far as a file on that machine allows.

- The **loop's document** names the tool and its arguments. It never contains a command.
- A file on **your machine**, `rxr.host.yml`, says what each tool name does there.
- A name the file does not list does nothing. There is no free shell.

plutonium.io runs nothing on your machine and holds no key to it. Your machine asks plutonium.io
for the calls that wait, and answers them. Nothing connects in to your machine.

## 1. Declare the tool in the loop

```yaml
capabilities: [host_act]

tools:
  - kind: host
    tool_id: run_tests
    description: Runs the project's tests and returns what they printed.
    display: note
    requires: [host_act]
    lifetime: 10m
    input:
      schema:
        type: object
        properties:
          filter: { type: string, description: "Only tests whose name has this text." }
    output:
      schema: { type: object }
      trusted: false
```

| Key | What it means |
| --- | --- |
| `kind: host` | A member's own machine answers this tool. |
| `requires` | Exactly one of `host_read` (it reads from the machine) or `host_act` (it runs a command or writes a file there). Add the same name to the loop's `capabilities`. |
| `lifetime` | How long a run waits for a machine to answer. `60s` when you leave it out. When no machine answers in time, the run goes on and is told so. |
| `trusted: false` | Required. What a machine answers is outside content, as a web page is. |

Three rules keep a host tool to your own use:

- **Only a loop with no delivery may declare one.** A loop that visitors reach (a chat on your
  site, an API key) cannot have a host tool, so a stranger's run never reaches your machine.
  Publish refuses it, and says so. A loop with a `page` trigger cannot have one either.
- **It needs no approval gate.** The file on your machine is the consent. You may add a gate
  with `approve: operator`, and then a member also approves each call on the console.
- **An agent that reads your private data cannot also hold `host_act`.** See
  [the Rule of Two](/docs/guide/permissions-and-trust.md).

## 2. Say what the name does on your machine

In the directory you work in:

```
rxr host init
```

This writes `rxr.host.yml`, with every key explained. Change it for your machine:

```yaml
# The loops that may call this machine.
loops: [repo_helper]

tools:
  run_tests:
    run: [cargo, test, --quiet, "{filter}"]
    timeout: 5m
  read_notes:
    read: ./notes
  save_report:
    write: ./reports
    ask: false
```

| Mapping | What the tool does | What the loop sends |
| --- | --- | --- |
| `run: [program, argument, …]` | Starts that program with those arguments. | A `"{name}"` item is the loop's argument of that name. |
| `read: <directory>` | Reads a file under the directory, or lists it. | `path` |
| `write: <directory>` | Writes a file under the directory. | `path` and `content` |

`rxr host check` reads the file and says what each name would do. It runs nothing.

What `rxr` does, and will not do:

- **No shell reads a command.** Each item is handed to the program as it is, so nothing the loop
  sends is read as syntax. A placeholder is one whole item: `"{filter}"`, never `"-k{filter}"`.
- **A value that starts with `-` is refused**, because the program would read it as an option
  you did not write.
- **A shell with a placeholder is refused** (`[sh, -c, "{command}"]`): that is a free shell.
- **A path stays under its directory.** A path that starts at the root, goes up with `..`, or
  passes through a link that leaves the directory is refused.
- **A command is stopped at its `timeout`** (60 seconds when you leave it out), and long output
  is cut. The result says when either happened.
- **`run` and `write` ask you first**, at the terminal, each time. `ask: false` lets one run
  unasked. `read` does not ask.

The file is yours and stays on your machine. Keep it in the project it serves: every relative
path in it, and every command, starts from the directory the file is in.

## 3. Answer the calls

**While you work.** Start a run from the directory that holds the file:

```
rxr run repo_helper "Run the tests and tell me what failed."
```

`rxr` follows the run. When the run calls `run_tests`, `rxr` shows you the command, asks, runs
it, and sends back what it printed. `rxr chat` and `rxr dev` do the same.

**With nobody there.** A run on a schedule, or one a webhook starts, has no terminal following
it. Leave this running on the machine:

```
rxr serve
```

`rxr serve` reads the calls that wait, every few seconds, for every run in your account, and
answers the ones your file lists for the loops it names. With nobody at the terminal, a tool
that asks first is answered "not handled", so give `ask: false` to each tool that may run
unasked. `rxr host check` names the ones that still ask.

`rxr serve` also starts the runs your file's `triggers` name:

```yaml
triggers:
  - loop: repo_helper
    on_change: [src]
    message: "These files changed. Run the tests."
  - loop: digest
    every: 30m
    message: "Write the digest."
```

Each is an ordinary run as you, one at a time for each trigger
([Triggers and Schedules](/docs/guide/triggers-and-schedules.md#from-your-machine)).

## When more than one machine listens

A machine **takes** a call before it runs anything, and plutonium.io lets only one take it. A
second machine is told the call is taken and runs nothing. A machine answers only the loops
its own file names, and only the tool names it lists; every other call it leaves alone.

A machine that takes a call and then stops (a closed laptop) does not give the call back. The
run waits out the tool's `lifetime`, is told that no machine answered, and goes on.

## What the run is told

Every failure reaches the model as the tool's answer. It never ends the run.

| What happened | What the run reads |
| --- | --- |
| No machine answered within the `lifetime` | That no machine answered, so nothing happened. |
| Your file does not list the tool, you said no, or nobody was there to ask | That the machine did not handle it. |
| The command ran | Its exit status and what it printed, and whether it was cut or stopped. |
| The path or the value was refused | A `refused` line that says why. |

While a run waits, its record on the console reads "Waiting on a machine", with the tool's
name. No button on the console answers a host call: only a machine does. Members who can
only read cannot answer one.
