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
| 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
pagetrigger 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
| 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. runandwriteask you first, at the terminal, each time.ask: falselets one run unasked.readdoes 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 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.