Runner guide
LQ / 05
Your machine, your key,the rail's rules.
The runner is a small open-source Node script in the repository (examples/runner.mjs). It never leaves your machine and it sends nothing to Launiq.
Run it
# Node 20+, in the repository folder npm install # values in your own shell, never in a committed file RUNNER_KEY=0x… RAIL=0x… AGENT=1 \ MANIFEST=./my-agent.manifest.json \ node examples/runner.mjs
Try it without real money first: start a local test chain with anvil (Foundry), deploy the rail there with forge create, point RPC_URL at it, and launch a test agent from a local build of this site.
| Variable | Need | Value |
|---|---|---|
| RUNNER_KEY | required | Private key of the runner address in the manifest (0x + 64 hex). A key made only for this agent, with a little ETH for gas. |
| RAIL | required | LauniqTaskRail address. |
| AGENT | required | The agent number shown after launch. |
| MANIFEST | required | Path to the manifest file from the studio. Its hash must match the agent on chain, or the runner stops. |
| RPC_URL | optional | Robinhood Chain RPC. Default: the official public endpoint. |
| POLL_SEC | optional | Seconds between passes (default 30, minimum 5). |
| ONCE=1 / DRY_RUN=1 | optional | One pass then exit; or plan and check without sending. |
Each pass
- 01Reads the agent on chain and stops if the key is not its runner or the manifest file does not match the hash.
- 02Finds the agent's tasks, at most 500 new task numbers per pass.
- 03For each task: done, cancelled, failed, waiting for approval or not due yet means skip, with the reason in the log.
- 04Builds the call data from the manifest: fixed values, or a number fetched over HTTPS. Free arguments need your own decideArgs().
- 05Asks the contract's check() for a reason code, simulates the call, and only then sends it with the task's gas limit plus a margin.
- 06Tasks that need approval are proposed instead, and run on a later pass once the owner approves that exact call.
Refusal codes from check() and execute()
Limits
- No hosted runner. If your machine is off, nothing runs; queued tasks wait or pass their deadline.
- The runner key can run anything your rules allow until you pause the agent. Give it its own key, and keep only gas money on it.
- A wide rule is a wide permission. Prefer fixed arguments; keep approval on for anything that moves tokens (the contract forces it when arguments are free).
- Tasks cannot send plain ETH to an address; only contract calls. Withdrawals are the owner's job.
- An HTTPS value is only as good as its source. The rail checks the call, not the truth of the number.
The owner's powers
The rules limit the runner, never the owner. The owner's wallet can pause, resume, cancel, change the runner key, replace the manifest (voiding every older rule) and call anything from the agent wallet, including withdrawing all of it. That makes your wallet the real key to the agent: keep it safe.
The contract
LauniqTaskRail deploys one LauniqAgentWallet per agent and holds no funds itself. It has no owner, no fee and no upgrade. It was written for this project and tested with 31 Foundry tests: unit tests, hostile targets (reverts, return bombs, gas hogs, re-entry, false-returning and blocking tokens), a fuzz test and two invariants (spend never above budget; ETH leaves an agent wallet only through counted runs or the owner).
It moves real funds from agent wallets and has had no independent security review. Use small amounts first, and expect that a review should come before real volumes.
Status: not deployed yet on Robinhood Chain.