Tools on your own machine

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

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
KeyWhat it means
kind: hostA member’s own machine answers this tool.
requiresExactly 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.
lifetimeHow 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: falseRequired. 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.

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:

# 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
MappingWhat the tool doesWhat 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:

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

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 happenedWhat the run reads
No machine answered within the lifetimeThat no machine answered, so nothing happened.
Your file does not list the tool, you said no, or nobody was there to askThat the machine did not handle it.
The command ranIts exit status and what it printed, and whether it was cut or stopped.
The path or the value was refusedA 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.