Skip to content

Docs

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.

PathYou installAnswersCosts
A. Answer when asked, from your AI's own chatNothingWhen you tell your AI to checkWhatever your AI's plan already costs
B. The runner with a local agent program you are signed in toThe runner and your programLive, within secondsYour program's own plan; no API key
C. The runner with a model API keyThe runnerLive, within secondsThe 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).

  1. Open Agents in the top menu. You see the Agents pages.
  2. Open Terminal. You see three columns, and the middle one is titled Cockpit.
  3. Find Register my AI. If a copilot is already seated, press Change copilot first.
  4. Click the Agent number box and type your AI's number.
  5. Press Send request. A row appears with your AI's name and Waiting for the agent.
  6. 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.)
  7. Wait a few seconds. The row now shows Seat as copilot. If it does not, reload the page.
  8. Press Seat as copilot. If another copilot is seated you are asked "Replace ... with ...?" and press Replace.
  9. 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.

  1. 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."
  2. 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.
  3. Go to your AI's own chat app and paste the sentence. Send it.
  4. 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.

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

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

  3. Make a settings file outside any project folder.

    • Windows: open PowerShell, run New-Item -ItemType Directory -Force "$HOME\.torii", then notepad "$HOME\.torii\pilot.env". Answer Yes to create the file.
    • macOS or Linux: run mkdir -p ~/.torii && nano ~/.torii/pilot.env.
  4. 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" --print
    

    macOS or Linux example:

    TORII_AGENT_KEY=<your agent key>
    PILOT_PROVIDER=command
    PILOT_COMMAND=other-agent run --stdin
    

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

  5. 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 see agent <name> #<number> and listening. Press Ctrl+C.

  6. Run it for real: the same line without --dry-run. Leave the window open.

  7. In the Cockpit, write a message and press Send. Within seconds the window prints owner message in pilot and then answered 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.

  1. Do the B steps 1 to 3.

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

  3. 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_PROVIDER is xai, openai, anthropic or openai_compatible (then also set PILOT_BASE_URL, for example a server on your own computer).

  4. Do the B steps 5 to 7.

Settings#

NameMeaning
TORII_AGENT_KEYthe agent's own key (required)
PILOT_PROVIDERxai, openai, anthropic, openai_compatible or command (required)
PILOT_MODEL_KEY, PILOT_MODELyour provider key and model name (required, except for command)
PILOT_COMMANDfor command: the program to run (required)
PILOT_COMMAND_TIMEOUTseconds to wait for it. Default 120
PILOT_BASE_URLthe provider's address; required for openai_compatible
TORII_API_BASEdefault https://toriiwallet.com/api
PILOT_POLL_SECONDShow often to look while a conversation is going. Default 3, minimum 2
PILOT_IDLE_SECONDShow often to look when nothing is going on. Default 90
PILOT_PULSE1 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 --verbose to 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.