Keep your copilot listening#
Your copilot is your own AI, seated in the middle of the Terminal (see The cockpit copilot). Nothing pushes to it, and a chat app cannot keep a session open, so it only reads the cockpit when something asks it to. This page shows three ways to get answers. Pick one.
| Path | You install | Answers | Costs |
|---|---|---|---|
| A. Answer when asked, from your AI's own chat | Nothing | When you tell your AI to check | Whatever your AI's plan already costs |
| B. The runner with a local agent program you are signed in to | The runner and your program | Live, within seconds | Your program's own plan; no API key |
| C. The runner with a model API key | The runner | Live, within seconds | The provider bills your key for every answer |
The copilot can read your mandates, talk, and pause or resume one with a stated reason. It cannot move money, change a limit or place an order. That is true on every path.
Before any path: seat your AI as copilot#
You do this once. You need your AI's agent number: ask it "What is your Torii agent number?" (it reads it with agent_status).
- Open Agents in the top menu. You see the Agents pages.
- Open Terminal. You see three columns, and the middle one is titled Cockpit.
- Find Register my AI. If a copilot is already seated, press Change copilot first.
- Click the Agent number box and type your AI's number.
- Press Send request. A row appears with your AI's name and Waiting for the agent.
- Copy the sentence shown in that row and paste it into your AI's own chat, then send it. Your AI accepts the request with its own key. (If your AI has lost track of what it is, press Handoff note on its row, copy the note and paste it into the chat too.)
- Wait a few seconds. The row now shows Seat as copilot. If it does not, reload the page.
- Press Seat as copilot. If another copilot is seated you are asked "Replace ... with ...?" and press Replace.
- The Cockpit now reads "Copilot: your AI's name and number". It is seated.
A. Answer when asked, from your AI's own chat#
No install. Your AI answers when you tell it to look.
- In the Cockpit, write your message in the box under Copilot and press Send. Under the box you see "Your copilot has not read this yet."
- Open Keep your copilot listening under the box. Press Copy under In your AI's chat. The sentence is:
In Torii Wallet, read cockpit_inbox and answer with cockpit_post. - Go to your AI's own chat app and paste the sentence. Send it.
- Back in the Cockpit, within a few seconds you see "Your copilot has read this.", then its answer appears in the thread.
Do steps 2 and 3 again whenever you want an answer.
B. The runner with a local agent program you are signed in to (no API key)#
The runner is one small file on your computer. For each message you write, it starts a program that you already use and are signed in to, gives it the question, and posts what it prints. You need Python 3.10 or newer, and an agent program on your computer that can answer one question and print the answer without opening a window (many have a "non-interactive" or "print" mode). Check your program's own documentation for that flag. The examples below use made-up program names, so the flags are only a pattern: replace the program name and flags with what your program's documentation gives.
-
Open Keep your copilot listening in the Cockpit and press Download torii_pilot.py. Save it in a folder you will find again, for example
Documents\torii. -
Find your agent's key. It is the one your AI already uses (if lost, the recovery code in Connect gets a new one). Keep it private.
-
Make a settings file outside any project folder.
- Windows: open PowerShell, run
New-Item -ItemType Directory -Force "$HOME\.torii", thennotepad "$HOME\.torii\pilot.env". Answer Yes to create the file. - macOS or Linux: run
mkdir -p ~/.torii && nano ~/.torii/pilot.env.
- Windows: open PowerShell, run
-
Paste these lines, put your own values in, and save.
Windows example (a program installed at a path with spaces needs quotes):
TORII_AGENT_KEY=<your agent key> PILOT_PROVIDER=command PILOT_COMMAND="C:\Program Files\MyAgent\my-agent.exe" --printmacOS or Linux example:
TORII_AGENT_KEY=<your agent key> PILOT_PROVIDER=command PILOT_COMMAND=other-agent run --stdinThe program receives the whole question on its standard input, and its standard output is posted as the answer. No model key and no model name are needed.
PILOT_COMMAND_TIMEOUT(seconds, default 120) is how long the runner waits for it. -
Try it without posting anything. In PowerShell:
python torii_pilot.py --env-file "$HOME\.torii\pilot.env" --dry-run. On macOS or Linux:python3 torii_pilot.py --env-file ~/.torii/pilot.env --dry-run. You seeagent <name> #<number>andlistening. Press Ctrl+C. -
Run it for real: the same line without
--dry-run. Leave the window open. -
In the Cockpit, write a message and press Send. Within seconds the window prints
owner message in pilotand thenanswered in pilot, and the answer appears in the thread.
How a pause works here: the program has no tools, so the runner tells it that, to pause or resume a mandate, it should end its answer with one line, ACTION pause <mandate_id> | <reason> or ACTION resume <mandate_id> | <reason>. The runner carries that out through the copilot routes, removes the line from the answer, and adds a short note saying what it did. A mandate with a vault on chain is paused by your wallet, not by a copilot, so that request is refused and the note says so. Anything else the program prints is posted as plain text.
The runner starts your program without a shell and does not pass it your agent key or any model key.
C. The runner with a model API key#
Same file, but the runner asks a model provider directly. The provider bills your key for every answer.
-
Do the B steps 1 to 3.
-
Get a model key from your provider's console (xAI, OpenAI, Anthropic, or any service that speaks the OpenAI chat format) and decide which model name you want. The runner has no default model.
-
Paste these lines, with your own values, and save:
TORII_AGENT_KEY=<your agent key> PILOT_PROVIDER=xai PILOT_MODEL_KEY=<your model provider key> PILOT_MODEL=<the model name you want>PILOT_PROVIDERisxai,openai,anthropicoropenai_compatible(then also setPILOT_BASE_URL, for example a server on your own computer). -
Do the B steps 5 to 7.
Settings#
| Name | Meaning |
|---|---|
TORII_AGENT_KEY | the agent's own key (required) |
PILOT_PROVIDER | xai, openai, anthropic, openai_compatible or command (required) |
PILOT_MODEL_KEY, PILOT_MODEL | your provider key and model name (required, except for command) |
PILOT_COMMAND | for command: the program to run (required) |
PILOT_COMMAND_TIMEOUT | seconds to wait for it. Default 120 |
PILOT_BASE_URL | the provider's address; required for openai_compatible |
TORII_API_BASE | default https://toriiwallet.com/api |
PILOT_POLL_SECONDS | how often to look while a conversation is going. Default 3, minimum 2 |
PILOT_IDLE_SECONDS | how often to look when nothing is going on. Default 90 |
PILOT_PULSE | 1 to send an hourly life signal saying the runner is listening. Off by default |
Options: --once (answer what is waiting, then exit), --dry-run, --verbose, --answer-pending (also answer a message you wrote while it was off), --env-file PATH. A missing setting is named in one line and the runner exits.
An agent key can make about 2,000 requests a day, so the runner looks every few seconds only for two minutes after you write, then every 90 seconds; your mandates' own threads are checked every 10 minutes. Your first message after a quiet time can take up to about 90 seconds to be seen.
Privacy#
Your keys stay on your computer and are never printed. The runner sends the last 20 messages of the thread and a summary of your mandates (status, budget, progress, paused or not) to your model (path C) or to your local program (path B). Nothing else leaves your computer, and nothing new is stored on the Torii server.
If it does not answer#
- "Your copilot has not read this yet." stays. Nothing has looked at the cockpit. On path A, send the sentence to your AI again. On B or C, check that the runner window is open and printing
listening. - The window says this agent is not the seated copilot (the server's reason is
tw_cockpit_no_seat). Your AI is not seated, or you replaced or removed it. Seat it again with the steps above. - Your AI was not told to read. On path A it only answers when you paste the sentence from Keep your copilot listening.
- The runner is not running. Open a new window and run step 6 again. It stops when you close the window, press Ctrl+C or the computer sleeps.
- The wrong agent is seated. The Cockpit line "Copilot: ..." shows a different name or number. Press Change copilot, then Seat as copilot on the right agent.
- "I could not reach my model. I am still listening." The runner posted this after three failures in a row (a wrong key, a model name the provider does not know, no internet, or your local program exited with an error or printed nothing). Run it with
--verboseto see the reason.
Stop it#
Press Ctrl+C in the runner window. To stop it for good, remove the copilot in the Cockpit (Remove copilot): its agent key is refused at once. Delete the settings file if you no longer need the keys there.