# Reactor documentation > How Reactor works, and how to build on it **You build the agent. We run it.** Give an AI agent any job, from answering your customers to writing the Monday report. Describe it in plain words, or write it as a file. Reactor runs it, shows what every run costs, and keeps it inside the limits you set, whatever a customer types. We call each agent a loop, and each loop does one job. We run the loop. You own the data. **Reactor** names a family of two products. Each works on its own, and they work together. - **Reactor loop** is loops as a service. You define a **loop**: what it is for, what it may read and call, and what each run may cost. Your users run it where you put it — a chat on your web page, or your own interface over the run API. The platform keeps every run inside the limits of the version you published, and shows you every run and every cent. - **Reactor search** makes your content searchable: a website, files you upload, or a collection's records. You search it on the console, your visitors search it on your site, and your servers search it with a search key, with no loop at all. **Together:** a loop can search your indexes, so it answers from your docs, your files or your records. See [Letting a Loop Search](/docs/guide/search-indexes.md). **Looking for something?** Press `/` on any docs page, or press **Search or ask** over the page list. **Search** finds the pages that hold your words, and opens a result at its section. **Ask** is a loop that plutonium.io runs on these docs: it answers a question from these pages and names the page it used. ## Reactor loop ### Start here - **[Getting Started](/docs/guide/getting-started.md)** — from signing in to your first run - **[Core Concepts](/docs/guide/concepts.md)** — loops, versions, runs, subjects, gates, budgets and deliveries ### Guides - **[Building a Loop](/docs/guide/building-a-loop.md)** — write a loop with LoopAssistant or by hand, try the draft, and publish it - **[Testing a Loop](/docs/guide/testing-a-loop.md)** — try a draft on the bench, and the test cases that must pass before a version publishes - **[Agents](/docs/guide/agents.md)** — the workers a loop runs, their roles, and how to add your own - **[Tools](/docs/guide/tools.md)** — the built-in tools, and how to give your loops your own HTTP endpoints - **[Asking the User](/docs/guide/asking-the-user.md)** — questions, forms no model reads, email checks, and consent before the loop acts - **[Collections and Outputs](/docs/guide/collections-and-outputs.md)** — where a loop keeps its records, and where it sends a result when a run ends - **[Pages](/docs/guide/pages.md)** — markdown pages that show your collections, previewed as each reader sees them and published like a loop - **[Embedding the Chat](/docs/guide/embedding-the-chat.md)** — put a loop's chat on your own web page, for anonymous visitors or for users your site signs in - **[Letting a Loop Search](/docs/guide/search-indexes.md)** — name a search index in a loop, and let the loop's visitors search it - **[Triggers and Schedules](/docs/guide/triggers-and-schedules.md)** — start runs with no person: on a schedule, from a webhook, from a new record, from your server, or from your own machine - **[Identity and Keys](/docs/guide/identity-and-keys.md)** — who a loop's user is, which sites may load it, and the API keys your server uses - **[Connect an AI tool](/docs/guide/connect-an-ai-tool.md)** — work in your account from an AI tool that speaks MCP, such as Claude or Cursor - **[The Command Line](/docs/guide/command-line.md)** — `rxr`: describe or write a loop, try it as you edit, test, publish and run it from a terminal, as a person or as an AI agent - **[Tools on Your Own Machine](/docs/guide/your-machine.md)** — let a loop read a file or run a command on your own machine, through `rxr`, and only what a file there allows - **[Operating Loops](/docs/guide/operating-loops.md)** — watch runs, stop one, take over, answer the decisions a loop waits on, and read Metrics - **[Money, Limits and Members](/docs/guide/money-limits-members.md)** — the wallet and the four budgets, the limits on who may start runs, and the people in your account ## Reactor search - **[Search Indexes](/docs/search/overview.md)** — what Reactor search is; create an index from a crawl, your files or a collection, search it, and what it costs - **[Writing a Search](/docs/search/writing-a-search.md)** — words, an exact phrase, a typo, a pattern, words or meaning, and what each searcher may send - **[Search API](/docs/api/search.md)** — search from your server with a search key, or through a loop ## API reference - **[API Overview](/docs/api/overview.md)** — the run API your server or page calls, how it authenticates, and what its limits answer - **[Identity](/docs/api/identity.md)** — the doors that give one of your users a token - **[Runs](/docs/api/runs.md)** — start a run, read it, talk to it and follow it - **[Search](/docs/api/search.md)** — search your indexes with a search key, or what a loop searches - **[Collections](/docs/api/collections.md)** — read a collection's records from your server - **[Webhooks](/docs/api/webhooks.md)** — start a run with a signed request, and receive a loop's outputs ## For AI tools A program can read this site as easily as a person can. - **Markdown.** Every page has a markdown form at its own address with `.md` added: this page is `/docs.md`, and the home page is `/index.md`. A request that sends `Accept: text/markdown` to a page's own address gets the same markdown. - **An index.** [`/llms.txt`](/llms.txt) lists every page with one line on what it holds. [`/llms-full.txt`](/llms-full.txt) is the whole documentation in one file. - **Your account.** [Connect an AI tool](/docs/guide/connect-an-ai-tool.md) to work in your account from a tool that speaks MCP: draft, test, publish and run your loops. An agent in a terminal can use [the command line](/docs/guide/command-line.md), `rxr`, which has a `--json` output and a guide written for it. --- # Getting Started > From signing in to your first run This is the path an admin takes from an empty account to a loop that a user can run. Only the people of your account (owners, members and viewers) sign in to Reactor. The people your loops serve never do — they meet a loop on your page or in your product. ## Try one first This is a loop that plutonium.io runs on these docs. Ask it a question: it answers from these pages and names the page it used. A loop you build meets your users the same way. Not sure what to build? [What Loops Are For](/docs/guide/what-loops-are-for.md) lists the jobs a business hands a loop, with a person in the conversation or with nobody at all. ## 1. Get an account, and sign in Reactor is not open for sign-up yet. Join the waitlist on the home page: we add people by hand, and we email you when your account is ready. You are its owner, and its wallet starts with $5.00 of starter credit. Then sign in to the console with Google, at the address we wrote to. The console opens on **Home**: your credit, what needs you, what is running, and this month against its budgets, under a line that names the account and your role. A new account's owner sees **Getting started** first: try a demo loop, set up your first loop, then publish it. Each step ticks itself when it is done, and **Hide** puts the list away. **Choose a demo** offers four of the demos on our home page: sort a support message, qualify a lead, meeting notes to actions, and file an expense. **Copy it as a draft** puts that demo's loop, its collection and its page into your account as drafts, named "Demo: …". A copy speaks for Larkspur, an example software company: change its prompt to speak for your own. Nothing runs or spends until you try it: Home then says it is in your account, and **Try it in Chat** opens a new chat with it. A press first reads what your account holds and writes only what is missing, so copying the same demo again keeps the copy you already have. **Describe it to LoopAssistant** opens **My conversations** on **LoopAssistant**, a loop plutonium.io owns that helps you write your own. After your first publish, Home shows **Your loop is live**. Press **Show the code for your site** there for the code to put it on your site. Each screen shows its title. Press the **?** beside a title to read what that screen is for. If a screen fails to draw, it shows "Something went wrong on this screen. Reload to try again." and a **Reload** button in its place. The menu and every other screen keep working. ## 2. Check the wallet Nothing runs until the account's wallet holds money: every call a run makes is reserved against it first. A new account starts with its $5.00 of starter credit. Adding money by card opens soon; until then, we add credit to your account. **Wallet & budgets** shows the wallet, what each loop has spent this month and the caps you set. ## 3. Describe the loop to LoopAssistant Tell LoopAssistant what the loop is for. It interviews you and proposes the loop as a record you read and edit before anything runs — its instructions, the tools it may call, what it must produce, who may use it and what a run may cost. The model that drafts the loop never publishes it by itself: it can ask, and your press on its card publishes. You can also start a loop yourself: **Loops → New loop**. ## 4. Know what a loop is built from A loop does its work through parts you can see and manage on their own pages, in the **Build** group of the console: - **Agents** — the workers a loop runs: their instructions, the tools they may call, their model and their role. The console lists plutonium.io's own agents beside the ones you create. Publishing a loop pins the agent version it uses. - **Tools** — your own HTTP endpoints. Install one once from a form, and several loops can declare it. A header secret you give it is stored and never shown again. - **Collections** — the records your loops write, collection by collection. - **Indexes** — what your loops can search: a crawl of a website, files you upload, or one of your collections. A loop's page lists the indexes its runs may search, and an index that a published loop uses cannot be deleted. ## 5. Test it, then publish A loop is written as a **draft**, and a draft never serves a user. Try it from **My conversations**: a new conversation lets you pick the loop and the version it runs in, draft included. If the loop declares test conversations, the version publishes only after they have run against it. **My conversations** lists only the conversations you started. Those of other members, and runs that users, keys and triggers start, are on **All runs**. Then publish the version. What you published is what runs, and it does not change afterwards: the next change is the next version. Publishing gives the loop its **public id** (`pl_…`), which is how the world outside the console names it. ## 6. Choose where it runs A loop reaches users only through the deliveries it declares, and only from the web origins it allows. On **Loops**, a published loop's **Keys** tab shows its public id, and what each delivery needs from you: - **Embed** — a chat on your own web page. For a loop that declares it, the tab is called **On your site**: it lists the sites the chat can load on, adds one, and shows the snippet to paste. - **API** — your own server or interface calls the run API. Mint a key on the Keys tab with the `create_runs` scope; the key is shown once. See [Runs](/docs/api/runs.md) in the API reference. Keys are for owners. A key can do only what its scopes allow, and only within what the loop declares. ## 7. Watch it run **All runs** shows every run live: who it was for, what it did, what it cost, and why it ended. You can stop any run from there. **Metrics** shows how each loop is doing across its versions, or for one version you choose: its runs, how they ended, what they cost and how long people waited. ## Ask the Assistant The **Assistant** answers questions about the console from these docs. It is not a general assistant: to a question that is not about Reactor, it answers "The docs do not cover that. I can help with Reactor." Under each answer, **Sources** links to each page its search found. On a desktop it is a panel at the right of every screen; on a phone it is a sheet that opens over the bottom 60% of the screen. Press or drag its handle up to make it full screen, and drag it down to make it smaller or to hide it. It is open on **Home**. On any other screen, press **Assistant**: at the bottom right on a desktop, and at the right of the bar under the header on a phone. **Hide** closes it, and the console remembers that choice in this browser. On **My conversations** the panel folds to its **Assistant** button, so the screen has one box; press the button to open it there too. Each box says who answers: the chat's box reads *Message LoopAssistant* (the loop you are talking to), and the panel's reads *Ask the Assistant about publishing, roles, pages…*. When the panel leaves too little room for a list and the item it opens side by side, the screen shows one at a time, as on a phone: press an item to open it, and the link above it (**‹ Loops**, **‹ Chats**) returns to the list. Hide the Assistant to see both again. Besides answering, it can do three things: - **Take you to a screen.** "Take me to Schedules" opens Schedules, and the Assistant stays open. - **Point at a control.** "Where is the publish button?" opens the screen and outlines the control for a few seconds. If the control is not on the screen now (Publish shows only on a loop that has a draft), it tells you what to do first. - **Hand you to LoopAssistant.** "I want a loop that qualifies leads" shows a card with a short brief of the loop you asked for. Press **Send this brief to LoopAssistant**, and LoopAssistant opens in a new tab of the panel with the brief sent as your first message, and starts work. The screen behind the panel does not change. **Not now** sends nothing. To change the brief first, write in **Note to the assistant** and press **Reply**: the Assistant reads your note, and nothing is sent to LoopAssistant. A note also goes with **Not now**, so the Assistant knows why. An agent you ask for goes to AgentAssistant the same way. Each hand-off is a tab beside the **Assistant** tab, and the Assistant keeps its own conversation there. Answer LoopAssistant in its tab, or press **Open in Chat** to open the conversation in **My conversations**. Closing a tab with its **×** does not stop the conversation: it stays in **My conversations**. The tabs stay while you move between screens and when you reload the page, until you close the browser tab. The Assistant reads nothing in your account: it knows these docs and where the console's controls are. plutonium.io pays for its runs. Each member can start 60 conversations with it a day and send it 60 messages an hour. --- # What Loops Are For > The jobs a business hands a loop — answering, qualifying, booking, triage, refunds, expenses, intake, digests and more — with a person in the conversation or with nobody at all A loop takes one bounded job off your hands. You say once what the job is, what the loop may read and call, what it must produce and what a run may cost; then it does that job for each person who comes, or each time something happens. Every job below is one loop. The ones marked **(live)** run on the plutonium.io home page, so you can try them before you build your own. ## Jobs with a person in the conversation These loops talk to someone — a visitor on your site, a customer in your product, or one of your employees — and end in an answer, a record, or an action a person approved. - **Answer questions from your docs (live).** A visitor asks how your product works. The loop searches your docs site and the files you upload, answers in a few sentences, and names the page it used. When your pages do not answer a question, it says so rather than guess. The "Try one first" box on [Getting Started](/docs/guide/getting-started.md) is this loop. - **Qualify a lead (live).** A prospect says who they are. The loop asks a few questions, one at a time, and files the lead as a record you can read, export or send to your CRM. - **Book a slot (live).** A customer asks for a time. The loop offers the slots that are still open, books the one they pick, and does not offer it again; or it books through your own calendar endpoint. - **Sort a support message (live).** A customer writes in. The loop answers them like a support chat, with one next question, and behind the reply it keeps one ticket for the conversation, sorted as billing, bug or how-to. Nothing is sent until a person approves it. - **Approve a refund (live).** A customer asks for their money back. The loop decides the request and prepares the refund — and does nothing until you press **Allow**. - **File an expense (live).** An employee pastes a receipt. The loop turns it into one expense record and asks only for what the receipt does not show, such as the category. - **Turn meeting notes into actions (live).** Someone pastes the notes of a meeting. The loop writes one action item per task, each with an owner and, when the task has one, a due date. - **Help a shopper find a product (live).** A shopper says what they need. The loop narrows the product list on your page to match, recommends, and can write a cart or a quote through your own endpoint. - **Intake.** Claims, applications, patient intake, support tickets: a conversation that collects the facts and the documents a case needs and ends in one structured record. The loop can check the person's email address before the record is saved, and hand the case to your team. - **Onboard a new customer.** A signed-in customer is walked through setup. The loop reads their state from your product, tells them the next step, and records their progress. - **Help your employees.** HR policy, IT help, access and expense requests for an employee signed in with your company account: the loop answers from your policies and files the request through your internal tools. - **Surveys, interviews and training.** A loop asks a fixed set of questions, adapts to the answers, and writes one record per person — a research interview, an exit interview, a satisfaction follow-up, or a short assessment with a score. - **Consent and registration.** An agreement, an identity check or an event registration, taken as a conversation that ends in a checked record. When a conversation needs a person, you can [take it over](/docs/guide/operating-loops.md) and speak to the user yourself. ## Jobs with nobody in the conversation A loop does not need a user. A **headless run** starts on a schedule, from a webhook, from a new record or from your server, works on that record, and ends in an output. See [Triggers and Schedules](/docs/guide/triggers-and-schedules.md). - **A weekly digest.** Every Monday the loop reads the week's bookings, reviews and questions and writes the owner a summary. - **Score a new lead.** A form submission starts a run that looks the company up through your tool, scores it, writes the lead and notifies your CRM. - **Triage what comes in.** Each new ticket, email or form is sorted, routed, and answered with a draft that waits for a person before it is sent. - **Process documents.** Each uploaded contract, invoice or application is read and its fields written to a collection; one the loop cannot read is passed to a person. - **Watch a page and judge the change.** A page you care about is checked on a schedule, and a run decides whether a change matters before anyone is told. - **Reconcile two systems.** Each night a run compares two of your endpoints and writes the differences down. - **Follow up.** A conversation that ended without an answer starts a follow-up a day later that reaches the same person. ## When the same work repeats Some jobs are the same steps every time: fetch a page, pull out the fields, compare them with last time, store the result. A model does not need to think about those steps on each run. An agent you give the permission to **install automations** can propose an **automation** for such a job: the fixed steps, run on a schedule, with no model in them, so each run costs a small fraction of a loop's run. You read and approve it before it runs, and it can start a loop when what it finds needs judgement. The work you repeat most becomes the cheapest to run. ## Every loop, whatever its job - **It has a budget.** Each call a run makes is reserved against your wallet first, and you cap what one run, one user and the loop's month may spend. - **It acts only as approved.** A loop holds the tools its published version names and nothing more, and a tool that asks first waits for a person before each call. See [Permissions and Trust](/docs/guide/permissions-and-trust.md). - **It is recorded.** Every run is kept turn by turn, and you can watch one live or stop it. ## Start one Describe the job to **LoopAssistant** in the console's **My conversations**, in your own words. It asks what it needs to know and proposes the loop for you to read and edit before anything runs. See [Getting Started](/docs/guide/getting-started.md), and [Core Concepts](/docs/guide/concepts.md) for the parts a loop is built from. --- # Core Concepts > The nouns Reactor is built from ## Loop A **loop** is a bounded piece of work you define once and offer to your users: what it is for, the sources it may read, the tools it may call, what it must produce, who may use it, and what each run may cost. Loops belong to your account. For the jobs a loop can do — answering, qualifying, booking, triage, refunds, expenses, digests — see [What Loops Are For](/docs/guide/what-loops-are-for.md). ## Version and publish You write a loop as a **draft**. Publishing turns the draft into a numbered **version**, and a published version never changes. A draft never serves a user. If the loop declares test conversations, the version publishes only after they have run on it. **The record you approved is what runs.** A run holds exactly the tools its version grants. A tool the version does not offer does not exist in the run, whatever a user types. ## Run A **run** is one use of a published loop: a conversation with a user, or a headless run your server starts. Every run is recorded turn by turn, and you can watch it live and stop it at any point. A run that ends says why — for example `completed`, `over_budget`, `lapsed`, `stopped` or `check_failed`. ## Subject A run's **subject** is who it is for, as the platform verified it: an anonymous visitor, a user your own system vouches for with a signed assertion, or a member of your account testing from the console. Per-user caps, and the record of who ran what, key on it. ## Gates A run can stop and wait. It waits on its **user** when the loop asks them something, on you (the **operator**) when a step needs your decision, or on an **external** system that answers through a callback. Every gate has a lifetime. What happens when the user declines, or nobody answers in time, depends on who the run waited on: - **Your decision.** A gate you do not decide in time lapses, and the run that holds it ends with the loop's `lapsed` message. A visitor does not wait for you: in a run for somebody outside your account, the visitor's conversation ends once your decision is all that is left, so the visitor has already read the loop's closing line. - **Your card in a console chat.** When a card asks you, the member in the chat, and you do not answer it in time, it lapses and nothing is done, but the chat stays open: say to go ahead, and you get a new card without being asked your questions again. - **A form the user fills in.** If the user declines the form, or nobody answers it in time, the loop reads that the user gave nothing, and the run goes on. - **A tool on your page.** If the user declines the action, or your page has no handler for the tool, the loop reads that as the answer and the run goes on. - **An email check.** A code the user does not redeem in time ends the run with the loop's own words. ## Budgets Money is counted before it is spent. Four limits apply to every run: the account's **wallet**, a **cap per loop**, a **cap per user** and a **budget per run**. Each call is reserved against them before it is made, and a run ends at the first limit it meets. Your users never see a budget, a model or a price — only the conversation. ## Delivery A **delivery** is where a loop meets its users, and a loop declares the ones it allows: | Delivery | Where the user meets the loop | |---|---| | **Embed** | A chat on your web page, from the snippet on the loop's On your site tab | | **API** | Your own server or interface, over the run API | | **SDK** | Your own React page, through the SDK — not yet published for install | | **Console** | You, testing from My conversations — a member of your account, never a user | A loop with no declared delivery is not reachable from outside your account. --- # Building a Loop > Write a loop with LoopAssistant or by hand, save it as a draft, try it in My conversations, and publish it A loop is one document, its **record**, that says what the loop is for and everything a run of it may do. You write the record as a **draft**, try the draft in **My conversations**, and publish it. The version you publish is what runs, exactly as you approved it. ## Two ways to start **Loops** lists the loops that are yours. Reactor's own assistants, such as LoopAssistant, are not listed there: they answer the Assistant button, **New agent** on **Agents** and **Add tools from API docs** on **Tools**, and are not changed or archived from **Loops**. An account with no loop of its own opens **Loops** on **Start your first loop**: copy a demo (the same ones Home offers), write one with **New loop**, or ask the Assistant to build one. ### With LoopAssistant Open **My conversations**. LoopAssistant asks what the loop is for, who will use it, what you already have, what a run must produce and what it may cost. It always asks what you already have, such as an endpoint, a price sheet or your docs, and it does not propose a new loop until you answer. "Nothing" is an answer. It chooses the agents the loop runs itself, from the platform's agents or one it proposes for you, so it does not ask you which agent to use. When the loop needs an agent of your own, LoopAssistant starts a second agent that writes it. Its card, **Install agent**, appears in the same chat. Approving installs the agent into your account and runs nothing; LoopAssistant then names that agent in the loop it proposes. The agent's role is one of the platform's roles, or one your account defined if you name it. It then proposes the loop as a card that names, in words, every tool, collection, output and cost the loop would get. Its first lines say what the loop does, who can use it, what it saves, what it reads, and which collections are new: *"Approving creates Leads."* names each one your account does not have yet. Before you see the card, the proposal is checked against the rules publish applies to the record, so a loop that publish would refuse goes back to LoopAssistant to fix. Read the card, then press **Save as draft** to keep it or **Decline** to throw it away. The card says when it must be answered, *Answer by* a time in your own time zone, and once that time has passed it says so and that nothing was saved. The chat stays open: say "save it" and LoopAssistant shows the card again from what you already told it. After a Decline, LoopAssistant asks what to change and does not offer the same change again, and its next card is the one you declined with only that change in it; anything more it thinks the loop needs, it asks you about first. If the next card changes more than that, the card says which parts differ from the one you declined, by the card's own headings, such as "What it may spend", under **Check before you approve** above **Save as draft**, so you can decline it again. The same box says when the loop may do something no tool it calls needs, has fewer than three test cases, has a test case that expects a record saved but leaves empty an answer the loop's form requires, or promises an email that nothing sends. A test case that expects nothing saved, such as a question about prices, is not named, because its run may never show the form. Pressing **Save as draft** with a warning in that box is your answer to it: LoopAssistant keeps the draft as you approved it, and changes it only if you ask. The model that drafts a loop never publishes it by itself. Once a draft is saved and its test cases ran, the chat says so, with **Open it on Loops** and **Try it in My conversations** under that line: the second opens a new chat on the draft, so you can try it before anyone else can. **Try it in My conversations** on the loop's own page does the same. Once the test cases passed, LoopAssistant asks to publish it with a **Publish** card in the chat. A card is answered in its own conversation: in any other conversation, and on a new chat, it shows as one line, such as *Go to "Bike quote log"*, that opens the conversation it belongs to. The card leads with what the draft changes against the version people reach now, by the same headings as an edit's card, and the whole loop is one press away; a loop never published shows itself whole. Pressing **Publish** publishes that draft in your name, with the same checks as the Publish button in Loops. If the draft was saved again after the card opened, or a check refuses it, nothing is published and the card says why. **Decline** leaves the draft unpublished, and you can still publish it in Loops. While LoopAssistant works, or waits on a card or another agent, **Stop** takes the place of **Send** in the box, and Stop stays beside the chat's name too. Enter still sends a message, which it reads before its next step. While a card waits, its next step comes after you answer the card, so a line under the chat says your message is held until then. When it waits on your own answer, **Send** is back. LoopAssistant also changes a loop you already have. It proposes the change as an edit to the record, and the card leads with the change: - It names the version the edit changes: "Changes published v3. Approving saves draft v4.", or "Changes draft v3, which is not published yet. Published v2 keeps serving until you publish." - Under **What changes against** that version, it lists what the edit adds, removes and changes. A long text, such as what a run is told, shows only the words that change: added words are underlined, removed words are struck through, and the unchanged words around them are cut to "…". What a run returns, a collection's fields and the input that fills a field are said in words, such as "Now holds bike, name and email, and needs name and email." or "adds the field bike (Text)", with the definition as written under **As written**. A test is named by its first question, and a changed test says what its run must reach and what it enters when asked for details, such as "Now it must finish and save the phone in Repair requests." A change to the tests is marked **This changes what publishing tests: a test that fails stops the publish.** - A change that alters what a run is told or may do is marked **changes what a run is told or may do**. A change to who can reach the loop, such as a site you add, is marked **changes who can reach it**. - **Show the whole definition** opens the whole loop as it will be after the change. An edit names only what changes and keeps the rest: a list such as `checks` merges by the name of each entry, and a group of settings such as `end_messages` merges by key. So "change the closing message" changes `end_messages.completed` and leaves the other end messages as they were. A conversation with LoopAssistant shows what it says and what it asks you. The steps it takes on the way, such as reading your loop, are folded into the **working steps** line at the top: press **show** to read them, with what you were charged for them. Each step is named in words, such as *List files* or *Propose a loop*. A step that did not run says why in one sentence, such as *Not run — what it sent was not valid, so it was told what to fix.* Your answer to a proposal names what you decided, such as *You approved the loop proposal*. If the loop changed after the card was drawn, your approval saves nothing, and the line under it says so: *Nothing was saved: the draft changed after you approved. LoopAssistant shows the change again.* A conversation with your own loop shows every step, named in the same words, such as *Save a record — saved in demo_helpdesk_tickets*. Press a step to open what was called and the full result, because that is where you check what your loop does. A step that did not run keeps its reason on the step itself. Above the box, **Thinks before answering** or **Answers directly**, and **Asks you before it acts** or **Allows without asking (yolo)**, say how the next chat runs; hold the pointer on one to read what it changes. An answer to one of its approvals names the step in the words its card used, such as *You approved the step to save a record*. A step that saved a record opens to the record as it was saved, read from its collection, including the fields the platform filled from the person's form; a record keyed on a value the person gave links to its collection instead. ### By hand 1. Open **Loops** and press **New loop**. 2. Type a **loop id**: a lower-case letter, then lower-case letters, digits or underscores — `lead_qualification`, not `lead-qualification`. The id names the loop and never changes. 3. Press **Write its first draft**. The editor opens on a starter record that already saves. 4. Edit the record, then press **Save draft v1**. ## The record The record is YAML. Every key in the starter is required, and the starter's comments say what each one is for. The keys you will change most: | Key | What it says | |---|---| | `name`, `description` | How the console names the loop. | | `entry` | The standing instruction. The model reads it on every turn; your users never see it. Every turn is also told today's date and weekday, in UTC, so the entry can say "next Monday" or "this year" without naming a date. The console shows a line break inside a paragraph as a space, and keeps the breaks of paragraphs, lists, headings and code; the model reads the entry exactly as you wrote it. | | `agents` | The only agents a run may use. With more than one, `entry_agent` names the one a person meets. | | `capabilities` | The **ceiling**. A tool that needs anything outside this list is not available to a run, unless `grantable` lets a run ask for it. [Permissions and trust](/docs/guide/permissions-and-trust.md) says how the two combine with an agent's role. | | `collections` | The only collections a run may write. | | `tools` | Your own endpoints that a run may call. | | `sources`, `indexes` | What a run may read, and which of your search indexes it may search. | | `checks` | What a run's work must pass, including the test cases that run before publish. | | `outputs` | Where a result goes: a collection, a signed webhook, or an email. | | `gates` | Which steps wait for a decision, and who decides. | | `identity` | How a user proves who they are, and the per-address and per-user limits. | | `delivery` | Where users reach the loop, and from which web origins. | | `on_topic` | Optional. Which messages the loop answers: `about` is one sentence that names everything the loop answers, and `reply` is what a person reads when their message is not. With `refuses: true` an off-topic message gets `reply` in place of the answer; without it the topic check only records what it decided. A loop anyone can reach should declare it; see [Keep the chat on topic](/docs/guide/embedding-the-chat.md#keep-the-chat-on-topic). | | `chat` | Optional. `show_activity: true` shows the visitor each step the loop takes while it works, then folds them into one line under its reply that they can open. Absent, the chat shows the conversation alone. See [What your visitor sees](/docs/guide/embedding-the-chat.md#what-your-visitor-sees). | | `ends` | Optional. How a conversation may end. `finish: false` means the loop never ends a conversation itself: it answers each follow-up, and the conversation ends when the person goes quiet. Use it for a search or Q&A loop. `idle_minutes` (1 to 60) is how long the person may stay quiet, after a reply or with a question open, before the conversation ends. Absent, the loop may end the conversation when its job is done, and a reply waits 10 minutes. See [Asking the user](/docs/guide/asking-the-user.md#how-long-a-conversation-waits). | | `triggers` | What starts a run: a conversation, a schedule, an event, or your own server. | | `budgets` | What one run, one user and one month may spend. Per run must not be more than per user, and per user not more than monthly. Per run and per user must each cover at least one model call at pay-as-you-go prices ($0.0010), because a Pro plan can lapse and the loop must still run. | | `end_messages` | The user's last line for each way a run can end, and `otherwise` for every ending you did not name. | When the platform refuses a save or a publish, the refusal names the field and what to change. ### Help in the editor Hover a key in the editor to read what it is for. **More** shows the key's full definition, and a key with a fixed set of values lists them. Hover a capability to read what it lets a run do. The editor marks problems as you type and says each one in words: a key it does not know, a value outside its set (`` `emial` is not allowed here: `kind` must be one of: email, text, choice, choices, boolean. ``), a missing key, a capability the platform does not have, and a rule that depends on another key, such as an upload source that names no file. A yellow mark is a guess: an agent or a tool your account does not seem to have. Publishing decides it. The platform still checks the draft when you save, with every rule publish applies to the record itself, in the same words. So a draft that saves is refused at publish only for something outside the record: an agent, tool or index your account has not installed yet, a secret it has not stored, or a test case that has not passed. A gate on a step that no run of the loop can call is refused too, and the refusal names the capability or the tool that would let it fire. Each problem it names is marked on its line as well as listed under the editor. The editor changes only the text you type, so your comments stay. ## Try the draft The loop's page on **Loops** shows a draft that was never published in words, as it shows a published version: what a run in it is told, and every tool, collection, output and cost it would get once published, with the document below. A draft never serves a user. Only **My conversations** can start a run in one: start a new conversation and pick the loop and the version, draft included. The run shows on **All runs** like any other, so you can read every turn, every tool call and every record it wrote. A record whose fields the platform filled from what the person gave in a form shows as a link to its collection instead, because the run never holds the person's values. ## Publish Press **Publish…** on the loop's page (**Publish the change…** once the loop is published). The card says in plain words what the loop is told and may do; the record itself is under **Show the full definition**. If the loop has test questions, the card starts them itself when they have not run on this text, says that each costs a few cents, and **Publish** waits until every one passes, saying why while it waits. When the change is to a published loop, the card leads instead with **What changes against what runs now**, from the moment it opens, while the test questions run and after one fails: each key the change adds, removes or changes, and a mark on a change to what a run is told or may do. Everything else is under **Show the whole definition**. If the change is saved again while the card is open, the card says so and **Publish** waits: press **Cancel**, then **Publish the change…** again. Publishing does three things: - **The version is fixed.** A published version is never written again. - **The loop gets its public id** (`pl_…`) on its first publish. Your page, your server and your keys name the loop by this id, and it stays the same for every later version. - **New runs start on the new version.** Runs already in flight finish on the version they started under. Publish also refuses a record that cannot work as written. For example, it refuses: - a record whose agents cannot do the work the record declares, - a `crawl` source when no agent that a run starts lists `records_query`, or an `upload` source when none lists `read_file`, because no run could read it, - a crawl into a collection the loop does not declare, - a tool that needs approval when no gate says who approves it. Each refusal names the agent, the tool or the field, and the fix. Some things a record may get wrong are flagged instead of refused, because only the words can show them. Saving the draft and the publish review both list them, and neither press waits on them: - an entry that names a tool no run of the loop can call, such as `web_fetch` when the loop does not hold `read_web`. A run then has no such tool and writes the call as text. If the entry means not to use the tool, nothing needs to change. - indexes the loop searches, beside an entry that never says to search them. A run treats its entry as true, so a price written there wins over the price the index holds. - an end message that promises the visitor an email, such as "we'll email you to confirm", when the loop has no tool or webhook that could send it. An `email` output sends only to the one address it names, never to the visitor. If a person sends that email, nothing needs to change. LoopAssistant's card shows this one too. - an entry that mentions emailing or notifying your staff, such as "then email the shop to notify staff" or "an email is sent to the shop on each saved request", when an `email` output already emails them. A run cannot send email, and a run told about the email tells the visitor it went, even while it is held for an address that is not confirmed. Take every mention of it out of the entry and say what the run tells the visitor, such as that their request is saved. LoopAssistant's card shows this one too. - an end message that says an email went or your staff were told, such as "we've emailed the shop", in a loop with an `email` output. That email is sent after the run and is held until its address is confirmed. LoopAssistant's card shows this one too. - an entry that tells the run to ask for an approval, or describes the wait for one, such as "ask the operator to approve saving this request" or "that call will pause for the operator's approval", when `gates:` already holds that step. The platform asks the approver and holds the step by itself, so a run told this asks the person in the chat instead. Say in the entry what the run does once the step ran, and what it says if it was refused. LoopAssistant's card shows this one too. - a test case with an `agent` turn that says an approval happened, such as "Operator approves saving the request". A transcript answers no approval card: answer it under the case's `approve`, and take that turn out. LoopAssistant's card shows this one too. - a collection field for when a record was saved, such as `created_at`, `submitted_at`, `saved_at` or `timestamp`, that no `bind` fills. A run cannot know the time, so it writes a guess. Every record already keeps the time it was saved (`created_ts`) and the time it last changed (`updated_ts`), and the Collections screen shows them. Remove the field. A time the visitor gives, such as an `appointment_time`, is not flagged. LoopAssistant's card shows this one too. - a permission under `capabilities` that no tool of the loop's agents needs, such as `send_external` when no tool sends anything. Every run holds it and nothing uses it. Remove it unless a step you know of needs it. LoopAssistant's card shows this one too. While the loop names an agent your account does not have, this one is not shown: that agent's tools are not known yet. A name under `tools` that publish would refuse is flagged when you save the draft, so you learn it before you publish. The draft still saves, because you may install a tool after you name it: - a built-in tool, such as `request_inputs`. Remove it from `tools`; a run holds it when `capabilities` lists what it needs. - a capability, such as `write_records`. Remove it from `tools` and list it under `capabilities`. - a name no tool in your account has yet. Install the tool, or declare it inline, before you publish. An agent under `agents` that your account does not have is flagged the same way, first, with the agents you can choose from. Install it, or name one of those, before you publish. ## Change a published loop On the loop's page, type what you want to change under **What do you want to change?**, such as "A tune-up is now $65", and press **Ask LoopAssistant**. LoopAssistant opens in the Assistant panel, in a tab named for the change, with your words already sent. It proposes the change for your approval there; then **Publish the change…** on the loop's page publishes it. While a change waits to publish, or on a loop that was never published, what you ask adds to that change, and the box says so; **Publish the change…** and **Discard the change…** stay beside it. To change the record yourself, press **Change it yourself**: the editor opens on the published record as the next change. Save it, try it, and publish it like the first. **Discard the change…** removes the waiting change and nothing else. On a loop that visitors reach, **Try it as a visitor** opens the chat at the top of its page. A collection the loop declares can gain fields from one version to the next, and records written before simply lack the new field. Saving the draft refuses an edit that removes a field the loop declared before (in its published version or its saved draft), or changes a field's type or key. The refusal names the fields: keep them, or declare a new collection. A field the loop never declared (you added it on the collection, or a pipeline or another loop did) stays, and leaving it out refuses nothing. ## Archive a loop An owner of the account can press **Archive this loop**. An archived loop serves nobody. Runs already in flight finish, and every published version stays readable. **Reopen this loop** makes it serve again. --- # Testing a Loop > Try a draft in My conversations, and declare test cases that must pass before a version can publish You test a loop in two ways. You **try the draft yourself** in **My conversations**, and you declare **test cases**: example conversations that run against the draft and must pass before the version can publish. ## Try the draft on the bench A draft never serves a user, but **My conversations** can run it. Start a new conversation and pick the loop and the version, draft included. Talk to it as your user would: **Enter** sends and **Shift+Enter** starts a new line. The line under your message reads "Thinking", and after ten seconds it shows how long the step has taken. The run shows on **All runs** like any other, so you can read each turn, each tool call, and each record it wrote. ## Declare test cases A test case is a check in the loop's record, with the kind `test_case`: ```yaml checks: - kind: test_case name: a_prospect_who_qualifies transcript: - role: user text: We are about forty people and we need to route inbound leads automatically. expect: ending: completed leads.email: present - kind: test_case name: a_visitor_who_does_not_qualify_leaves_no_lead transcript: - role: user text: Just browsing, and I do not want to be contacted. expect: ending: completed leads.email: absent ``` | Key | What it says | |---|---| | `name` | The case's name. A failure names it. | | `transcript` | The user's turns that the case plays to the loop. | | `expect` | What must be true when the case run ends. At least one entry. | | `inputs` | What the case answers when the loop shows its form, by input id. Test data, never a secret. A required input the form asks for and the case does not give **declines** the form, which is how a case tests the loop's answer to a refusal. | | `stubs` | What a tool answers in this case, by tool id. | | `approve` | The person's answer to the approval card on a step, by the step's name in `gates:`: `true` approves it, `false` declines it, for example `approve: {issue_refund: true}`. A case run **declines** every approval a user would give that the case does not name, so this is how a case tests what happens after the user says yes. It **approves** every `approve: operator` card the case does not name, because you started the run, and the run's steps say so ("Approved by default, as test case … runs"), so `false` is how a case tests what happens after your team says no. Publish refuses a step that `gates:` does not ask a user or the operator to approve, and a case whose run never shows a card it names fails, saying so. | ### What a case can expect - `ending` — how the run must end, for example `completed`. - `.` — `present` or `absent`: whether the run wrote that field. A case that expects `absent` proves the loop can end **without** writing a record. - `.: {equals: }` — the run wrote exactly that value, for example `leads.company_size: {equals: "11-50"}`. Publish refuses it on a field the collection fills from an input, because that value never passes through the loop; expect `present` there. - `tool:` — `called` or `not_called`, or the arguments the call must carry, such as `tool:create_lead: {plan: team}`. Other arguments are ignored. ## What a case may touch Each call in a case run is checked exactly as in a real run. Then a call that would leave the platform **is not made**. A tool with external effects, and your own endpoint or code tool, answers the case's `stubs` entry for it, or `{ok: true, simulated: true}` when there is none. The run's outputs are recorded, not sent, so running the cases three times never puts three leads in your CRM. A tool that only **reads**, such as a lookup, can run for real in test cases. Declare `case_runs: live` on it. The publish review then says the tool is "called for real by test cases". Publish refuses `live` on a tool with external effects and on a tool that runs on your page. ## Run the cases On the loop's page, press **Publish…** (or **Publish the change…**). Under **Test questions**, the card starts the cases itself when none have run on the loop's current text, and says that each is a real conversation, paid from the account's wallet. A set that already ran on this text is not run again. Each case is shown by the visitor's first message, such as "My ticket is ABC123. Is it ready?", rather than its `name`; two cases that open alike are numbered (1), (2) in the order they are declared, here and in the chat's lines about the run, and a case that opens with no visitor message shows its `name`. Each result says **passed** or **failed**, and **See the conversation** shows the case's conversation. A failed case says what the case required and, under **What happened**, what the run did in plain words, such as "The run saved no run id in repair requests." When the loop's own check refused a save, the line names the rule, such as "The loop's own check refused the save in demo action items: each record needs a value for priority." That reason comes first, before what the run then failed to do, and the chat's summary of the results shows it. **The check's words** below it names the exact expectation that did not hold, which is what to change in the case or in the loop. When a spending limit stopped a case's run, the line names that limit and its fix. If the account's wallet could not cover the run, add credit on **Wallet & budgets**: a higher budget for the loop does not help, because each case run sets aside its budget for one run from the same wallet. If the loop's budget for one run is less than one step costs, the line says so, and that budget is the one to raise. **The results belong to the draft's current text.** When you edit the draft, its results are cleared, and the next time you open **Publish** the card runs them again. ## Publish waits for the cases A draft that declares test cases publishes only after they ran on its current text and passed. **Publish** stays disabled while they run or after one fails, with the reason under it; **Change this test question** opens the case in the editor. A draft that declares no test cases needs none. --- # Agents > The workers a loop runs — their instructions, tools, model and role — and how to add your own An **agent** is the worker a loop runs: its base instructions, the tools it knows how to use, and its model. The loop is the job. What a run may actually do comes from the agent's **role** and the loop's own limits, never from the agent, so changing an agent can never widen what it may touch. ## The Agents page **Agents** lists every agent in one list, each marked **Yours** or **Platform**; the chips above the list show one kind at a time: - **Yours** — the agents this account added. Any loop in the account can name one. - **Platform** — the ones every account has. You cannot change them here. Each row says what the agent does. Open an agent to see what it is for, its model by name, what it may do (its role, in words, with the role's name after it), and the tools it knows how to use. **Change** and **Delete** are at the top of your own agent; **New agent** is at the top of the list. ## The platform's agents Every account has these. The page shows each by its name; a loop names it by its id. | Name | Id | What it does | |---|---|---| | General | `general` | Talks with a person and does what its loop grants: keeps records, asks on cards, calls the loop's own tools. The agent for a chat. | | Researcher | `researcher` | Reads two job-board sites, weworkremotely.com and remoteok.com, and files what it finds into a collection. Through a [Google connection](/docs/guide/connections.md), it also lists your newest Gmail messages and one day's calendar events. | | Analyst | `analyst` | Works over your workspace and collections. No network. | | Summarizer | `summarizer` | Reads files and records and gives back a summary. Writes nothing anywhere. | | Schedule builder | `automation_builder` | Looks at what a run found — or fetches it — and proposes the schedules that keep finding it. | | Loop builder | `loop_builder` | Interviews an admin about the loop they want and proposes it as a draft they publish. The agent behind LoopAssistant. | ## Add an agent There are two ways: describe it to **AgentAssistant**, or fill in the form yourself. ### With AgentAssistant Press **Ask AgentAssistant** on the Agents page, and a chat opens on AgentAssistant, a loop plutonium.io owns. Or ask the console's Assistant for an agent: it first shows a card, "Send this brief to AgentAssistant? … Nothing happens until you answer.", with **Send this brief**, **Not now** and **Reply**. After **Send this brief**, AgentAssistant opens in a new tab of the Assistant's panel, with your request sent as the first message. Say what the agent is for in your own words. It asks for anything it still needs, such as the role it starts in or the tools it uses, and then shows the agent on a card. The card lists what its role allows. A loop that runs it can narrow this to what the loop declares, such as the one collection it reads. Approving the card installs the agent and runs nothing: an agent works only when a published loop names it. The chat then says, in the platform's words, that the agent is installed and may do what its card lists. When you want a loop that uses it, ask LoopAssistant. ### With the form Press **New agent** and fill in the form: | Field | What it is | |---|---| | **Name** | How a loop names the agent, such as `support_triage`. It cannot change later, and it cannot be a platform agent's name. | | **What it is for** | One sentence for people. | | **Its base instructions** | What every run of this agent is told, before the loop's own instruction. | | **Model** | **The default (recommended)**, or a model by its name and price, as the chat's model list shows it. | | **What it may do** | The agent's role, each offered by what it does, such as *Reads the account's records and nothing else. (reader)*, from the platform's roles and your account's own. | | **Tools it knows how to use** | Chosen from the tools your account has, each by what it does with its name after it, such as *Ask the person a question (ask_user)*. | Each field says what it is for, and a field you change says what is wrong with it as you type. Press **Add agent**. The form checks the agent first and names any field it refuses, and then the page opens the new agent at its own address. To edit an agent later, press its **Change** button, then **Save changes**. ## Roles A role is a set of permissions. The platform defines the roles below, and an owner of your account can define more ([your own roles](#your-own-roles)). Each agent starts with one. | Role | What a run in it may do | |---|---| | `general` | Reads and writes records and tells the person what happened. Reads no web until a person names a site on a card. Reads a connected service only through a tool an admin approved. Sends nothing outside the platform. | | `reader` | Reads the workspace, its collections and its search indexes. Writes nothing anywhere. | | `librarian` | Reads and writes the workspace and its collections, and searches its indexes. Reaches nothing outside them. | | `web_reader` | Reads two job-board sites (weworkremotely.com and remoteok.com), the account's search indexes and a service you connect. Writes records. Changes nothing else. | | `outbound_writer` | Sends what another agent worked out to a system outside the platform. Reads nothing. | | `service_writer` | Changes things outside through a tool an admin approved, for another agent of its loop. Reads nothing. | | `builder` | Reads what a task already found, reads the web a host at a time, and proposes software that keeps finding it. | | `connection_builder` | Reads a service's API docs a host at a time and proposes the tools that read it. It holds no key and installs nothing until the admin approves each tool's card. | | `loop_builder` | Interviews an admin and proposes a loop for them. It publishes nothing; that is the admin's separate act. | | `noop` | Grants almost nothing. What a task runs as when nobody has said otherwise. | An agent's role is its outer bound, in every run: on the console it holds what its role allows, and in a loop's run what its role allows **and** the loop's `capabilities` list, never more. Six permissions are the loop's own and need no role — `spawn_tasks`, `client_navigate`, `client_act`, `call_endpoint`, `host_read` and `host_act` ([Permissions and trust](/docs/guide/permissions-and-trust.md) says how each layer decides). An agent that needs a permission its role does not allow needs a different role, not a wider loop. ### Your own roles An owner of the account can define a role: a **name**, the **words** a person reads before trusting it, and its **permissions**, chosen from the list in [Permissions and trust](/docs/guide/permissions-and-trust.md). **Roles**, beside Agents, lists every role, each marked **Yours** or **Platform**. Open one to read its words, each permission in plain words with its id, and the agents that start with it. An owner presses **New role** to define one; the form offers only the permissions a role of your own may hold. Each field says what it is for, and a field you change says what is wrong with it as you type; the save checks the whole role again and tells you at each field what to fix. **Change** and **Delete** are at the top of your own role. A member reads the roles and changes none. The same rules hold for the roles API (`PUT /api/roles/{roleId}`; `GET /api/roles` lists every role and which agents start with it). A role is refused, in words that name the fix, when it: - uses the id of a platform role, - lists a tool, such as `web_fetch`, where a permission belongs — the refusal names the permission the tool needs, - lists an `install_` permission — only the platform's own builders hold those, - lists one of the three permissions below. Their tools must be bounded (which sites, which folder, which level), and a role of your own carries no bounds, so an agent that needs one starts with a platform role that bounds it: | Permission a role of your own cannot hold | Start the agent with | |---|---| | `read_web` (reading the open web) | `web_reader` | | `write_workspace` (writing files) | `librarian`, or `web_reader` for its `docs/` folder only | | `rehearse_claim` (trying an automation on the live site) | `builder`, or `web_reader` | A role never widens what a loop may do: a run still holds the role **and** the loop's `capabilities`, never more than both. **Publishing pins the role** with the agent, so editing the role later changes nothing for a published version until you publish again. A role that an agent starts with cannot be deleted; give that agent another role first. **Delete** shows what uses the role before anything is removed: each agent that starts with it, which stops the delete, and each published loop version that pinned it, which keeps running its pinned copy. ### Reading and sending are two agents An agent that reads your records must not also send to an outside system. When a loop does both, it uses two agents: one reads and writes records, and the other sends and reads no collection. Publish refuses one agent that holds both. [Permissions and trust](/docs/guide/permissions-and-trust.md) says why: the Rule of Two. ## Use an agent in a loop Name the agent in the loop's record: ```yaml agents: [support_triage] ``` With more than one agent, `entry_agent` names the one a person meets first. The draft uses the agent's current version at once, so you can try it in **My conversations**. A draft that names an agent your account does not have still saves; publish refuses it and names the agents you can use. A role's name in `agents`, such as `librarian`, is refused when you save, and the refusal names the agent that plays that role. **Publishing pins an agent your account added.** The published version keeps that agent's instructions, tools, model and role as they were at that moment. Editing the agent later changes nothing for that version; the next version you publish picks up the edit. --- # Tools > The built-in tools a run can call, and how to give your loops your own HTTP endpoints — installed once, used by many loops A **tool** is something a run can call. Every run has the platform's built-in tools that its role allows, and you can add your own: an **endpoint tool** is your own HTTP endpoint, which plutonium.io calls for the run. A loop gets only the tools whose permissions it holds. A tool that needs a permission the loop does not hold is left out, so no run can call it. [Permissions and trust](/docs/guide/permissions-and-trust.md) lists what each built-in tool needs. ## Built-in tools These come with the platform. A run holds the ones its agent's role and its loop allow. You do not list a built-in tool under the loop's `tools`: add the permission it needs to `capabilities`. Saving a draft that lists one under `tools` is refused, and the refusal names that permission. | Tool | What it does | |---|---| | `ask_user` | Asks the user a question and waits for the answer. | | `request_inputs` | Shows the user a form for the inputs the loop declares. | | `notify_user` | Sends a note. | | `read_file`, `list_dir` | Read files in the loop's workspace. | | `records_query`, `records_put` | Read and write records in the loop's collections. | | `finish` | Ends the run when the job is done, with the loop's closing line. Not beside a refused proposal: the run goes on so the model can fix it. | ## Your own endpoint On **Tools**, press **Add a tool** and answer its questions: | Question | What it sets | |---|---| | **What should it be called?** | The tool's name, such as *Order lookup*. Your assistant calls it by a name made from it, such as `order_lookup`; **More options** lets you change that name. | | **When should your assistant use it?** | One line your assistant reads to decide when to call the tool. Say what it is for, in at most 300 characters, and name no site other than the tool's own: every run that uses the tool reads it. | | **What address does it call?** | The `https://` address plutonium.io calls. | | **Does it only look things up, or does it change something there?** | *It only looks things up* calls with `GET`, and a loop that uses it is allowed to call the addresses of your own tools (`call_endpoint`). *It sends or changes something* calls with `POST`, and a loop that uses it is allowed to send things outside Reactor (`send_external`). | | **Does that address need a key?** | No, or yes: choose a key you saved, or save a new one with a name to find it by, such as `crm_key`. A key is kept encrypted, never shown again, and sent as `Authorization: Bearer`. Saving under a name you used before replaces that key. | | **What does it need to be told?** | Each input a run sends it: a name, its kind (text, number, yes/no or date), and whether it is always needed. **Write the JSON yourself** opens the JSON Schema instead. | | **Which loops may use it?** | Your own loops. Beside a chosen loop that is not yet allowed what the tool needs, the form says so; whether the loop can be allowed it is checked after **Add tool**, before anything changes. Choose none to keep the tool only in your account for now. | **More options** holds what a person sees when the tool runs, whether a run may act on its answers without a check (leave this off unless you vouch for the address), and what it answers, as JSON. Press **Check the tool**, read what it reaches, and press **Add tool**. The tool is now in your account, and the page opens it. For each loop you chose, plutonium.io adds the tool to that loop's waiting change, and starts one when the loop has none; it gives the loop the permission the tool needs when the loop lacks it. The page says what it did for each loop, or why a loop was not changed, with a **Review and publish** link. Nothing runs differently until you publish: a tool is called only by a loop that you publish and that uses it, and the Publish card shows the new permission before you press. A tool's page lists the published loops that use it. **Let another loop use it** asks the same question for a tool already in your account. As you choose each loop, the page checks it and says, before you press **Let them use it**, what stands in its way and how to fix it: for example, a loop that reads your collections or the web cannot also use a tool that changes things, and a loop strangers open cannot use one at all. A loop with something in its way is not changed. When a loop's own agent may not send or change things itself, plutonium.io gives the loop a helper, the **Service writer**: the loop's agent hands it each call, it reads nothing but what it was handed, and the page says it was added. Each call of a tool that sends or changes things waits for an approval, so the page also asks who approves it: **You** (the default) or **The person in the chat**. The person in the chat is offered only when every chosen loop allows it; on a loop strangers open, only you can approve. When you add such a tool from **Add a tool** with loops chosen, the tool's page opens on the same question with those loops chosen, and nothing is added to them until you answer it. A tool that only looks things up is added to its loops at once. A tool added before every tool had to need a permission shows "names no permission" on the Tools page. A loop that uses it is refused at its next publish, and no run of a loop without the permission can call it. Change the tool to need what its method calls for. A few older tools live inside one loop only; the Tools page lists them as **Only in** that loop. ### Using a tool in a loop's document A loop's document names a tool from your account with `use`: ```yaml tools: - use: order_lookup ``` **Publishing pins it**: the published version keeps the tool's definition, its address and the name of its key as they were, and a later change to the tool changes nothing for that version until you publish again. Publish refuses a name that is not in your account, and a key name that is not your account's. ## Tools from a service's API docs On **Tools**, press **Add tools from API docs**. It opens a chat with **ConnectionAssistant**. Tell it the service and the address of its API documentation. It reads the docs, checks the tools you already have, and proposes one tool for each endpoint you want, each on its own card. - **The first read of a site asks you first.** A card names the site, and ConnectionAssistant reads nothing there until you allow it. - **It proposes tools that read.** Each one uses `GET`. A tool proposed in a run that read a web page must read: any other proposal is refused before a card is drawn, and the refusal says so. A tool that changes something in the service is yours to add with **Add a tool**. - **It never asks for a key.** A tool that sends one names a secret. Save the key under that name on **Add a tool**, under **Does that address need a key?**, and the tool sends nothing until you do. When the docs say the service needs no key, the tool names none. - **Google, Slack, Notion and Linear are connections, not tools.** For those, it tells you to connect the service on **Connections**, with a link to it, where its tools come with the connection. - **A docs page is outside content.** ConnectionAssistant reads it through a reader that cannot act, and treats what it says as a description of the service, never as an instruction. You approve each tool's address and description on its card before it is installed. When a tool calls a different site from the docs it was written from, its card says so under **Check before you approve**. Approving a card installs that tool and runs nothing. A loop uses it when LoopAssistant builds or changes a loop that names it. ## What a run does with an answer An answer from your endpoint is **untrusted** unless the tool says otherwise: the model reads it with the same care as a web page. To bound how much a run accepts, add a check to the loop's record: ```yaml checks: - kind: tool_result tool: price_lookup max_bytes: 4000 ``` An answer over the bound is refused, and the model reads a sentence that names the limit. ## Code tools A **code tool** runs JavaScript in a sandbox, and reaches only the `https` hosts it declares. The Tools page form does not install code tools: LoopAssistant proposes one on a card, and you approve the card to install it. **A proposed tool's card shows what the tool calls and what a run sends it**: the full address, its host in bold, and each input with its type, marked *optional* where the tool can do without it. The description is shown as LoopAssistant wrote it. When the run read web pages before it proposed the tool, the card names their sites at the top, taken from the pages the run fetched and never from the model's words. Check the address and the inputs against what you asked for before you press **Install tool**. **LoopAssistant can also propose a change to a tool you already installed.** It first reads the tool as installed, and proposes the whole tool from that read with only what you asked changed, so a key you did not mention, such as the endpoint, stays as it is. If the tool changed after that read, the proposal is refused and LoopAssistant reads it again. Its card reads *Update the installed tool …?* and leads with what changes from the installed version; **Show the whole tool** opens its description and its code. Approving replaces the installed version. A loop you already published keeps the version it was published with until you publish it again. A proposal identical to the installed tool is refused, and LoopAssistant uses the tool by name instead. ## Tools on your own page A **client tool** is an action your own web page performs for the user, such as opening a page of your app. See [Embedding the Chat](/docs/guide/embedding-the-chat.md). ## Tools on your own machine A **host tool** is an action your own machine performs for a loop, through `rxr`: it reads a file, writes one, or runs a command that a file on that machine lists. No visitor's run can call one. See [Tools on Your Own Machine](/docs/guide/your-machine.md). --- # Permissions and trust > What a run may do, who decides, what each built-in tool needs, the Rule of Two, and what a trusted source changes A run can do only what three things allow together: the **agent** it runs as, the agent's **role**, and the **loop**. This page says how they combine, what each built-in tool needs, why plutonium.io refuses some combinations (the **Rule of Two**), and what marking a source **trusted** changes. It describes the rules as they work today. A rule that is still coming is labelled **Coming**. ## The Permissions screen **Permissions**, in the console's Account group, shows what your account's published loops and pages may do: - **Your loops**: each published loop that is not archived, with each permission its record holds, in the words its approval card used, and who reaches it (visitors through the chat on your sites, or a server of yours with an API key). A permission the loop may widen during a run says that it asks before reaching further, and who answers. **Change it on its loop** opens the loop. - **Your pages**: each published page, with who can open it and who can change its rows. **Change it on its page** opens the page. The screen reads the first 12 pages in full; for any page after those it shows who can open it, and the page itself shows who can change it. - **Reactor's own loops**: the loops Reactor runs in your account, such as its assistants, with the permissions each one holds. They are Reactor's, so you cannot change them. A draft, an unpublished page and an archived loop may do nothing, so the screen does not list them. The services Reactor can reach as you are on **Connections**. ## Permissions A **permission** (a *capability* in a loop's record) is one kind of thing a run may do. plutonium.io defines the list, and it is closed: a loop, a model or a tool cannot add one. The console names each one in words; a loop's record names it by the word in the first column. Each permission also carries up to three **marks**, which the Rule of Two below adds up: - **Outside content** — it can bring text that plutonium.io did not write into the model's context: a web page, a search result, what a stranger types. - **Your data** — it can read or change your account's data or secrets. - **Acts outside** — it can cause an effect outside Reactor that the person did not ask for turn by turn. Sending you a notification is not this; sending mail to somebody else is. | Permission | What it lets a run do | Marks | | --- | --- | --- | | `read_web` | Read any page on the web | Outside content | | `call_endpoint` | Call the addresses of your own tools | Outside content | | `read_workspace` | Read your files | Outside content, Your data | | `write_workspace` | Write to your files | Your data | | `read_records` | Read your collections | Outside content, Your data | | `write_records` | Write to your collections | Your data | | `search_indexes` | Search your indexes and read their documents | Outside content, Your data | | `notify` | Send the person a notification | — | | `install_automations` | Install an automation that runs on its own | Your data | | `install_loops` | Install a loop | Your data | | `install_tools` | Install a tool your loops can call | Your data | | `install_agents` | Install an agent your loops can run as | Your data | | `install_pages` | Draft a page your members can read | Your data | | `read_connection` | Read from a service you have connected | Outside content, Your data | | `write_connection` | Change things in a service you have connected | Your data, Acts outside | | `send_external` | Send things outside Reactor | Acts outside | | `serve_records` | Serve your collections to an outside caller with an API key | Your data, Acts outside | | `spawn_tasks` | Start further runs | — | | `run_code` | Run code | Acts outside | | `read_own_results` | Read back results it already received | Outside content | | `rehearse_claim` | Try an automation once on the live site, saving nothing | Outside content | | `client_navigate` | Open a page of your app for the person it talks to | Outside content | | `client_act` | Act in your app as the person it talks to, once they confirm each use | Outside content, Acts outside | | `host_read` | Read from your own machine, where you run rxr and allow it | Outside content | | `host_act` | Run a command or write a file on your own machine, where you run rxr and allow it | Outside content, Acts outside | The install permissions carry no **Acts outside** mark because every install tool asks a person first, each time (see the table of tools below). ## Three layers decide what a run may call 1. **The agent's tools.** An agent lists the tools it knows how to use. A tool that is not on the list is not something a run can call at all. 2. **The role's permissions.** An agent has a default **role**, a named set of permissions — one that plutonium.io defines, or one an owner of your account defines from the permissions above ([Agents](/docs/guide/agents.md) lists the platform's and says how to define your own). **The role is the outer bound, in every run:** a tool runs only when the role holds every permission the tool needs, and neither a loop nor a card can add one the role does not allow. A tool that needs one is left out of the run, and a call to it is refused in words that name the role and the permission — to give an agent more, change its role on the Agents page. **Six permissions are the loop's, not a role's:** `spawn_tasks`, `client_navigate`, `client_act`, `call_endpoint`, `host_read` and `host_act` name something only a loop has — its other agents, the page that hosts it, its own endpoint tools, the machine its host tools name — so no role holds them, the loop's `capabilities` give them to its runs, and a run outside a loop never holds them. **In your own run on the console**, a card asks you only what the role leaves to you: which site, when a role allows reading the web a host at a time, and which connection, when it allows using one. While a card waits, the run's activity line for it quotes what the agent said it was about to do, in its own words; the card itself states only what the platform computed. A published loop keeps the role as it was when you published. **A role's limits travel with it into a loop's run.** A role can hold a permission only within limits — `web_reader` reads two job sites and writes files under `docs/` only. A grant in a loop's run gives back no more than those limits, and a `grantable` entry that names wider ones is narrowed to them. A path outside a write limit is refused and nobody is asked. A site outside the role's list is refused too, unless the loop's `grantable` declares a `widen` for that permission: then the person that entry names is asked about that one site. A role whose list is EMPTY (the `general` agent reads no site until someone allows one) can read nothing in a loop without that `widen`, so saving or publishing such a loop is refused, naming the entry to add: `grantable: [{capability: read_web, kind: widen, approve: user}]`, or `read_web` taken out of the loop's `capabilities`. 3. **The loop's `capabilities`.** A loop's record lists the permissions its runs may hold — the **ceiling**. A loop only narrows the role: a run holds what the role allows **and** the ceiling lists (plus the four loop permissions above, when the ceiling lists them). A run never holds a permission outside the ceiling, whatever the role grants, and a tool that needs one is left out of the run — unless the loop's `grantable` lets the run ask for that permission (below), which it can only when the agent's role allows it. **An example.** The `librarian` role holds `write_records`, and `records_put` needs `write_records`. A loop whose `capabilities` lists `read_records` but not `write_records`, and whose `grantable` does not name it, runs a librarian agent without `records_put`: the role allows it, the ceiling does not, so the run cannot write a record and nothing offers to. When a run calls a tool anyway, the refusal tells the model which layer stopped it: - **Not one of this agent's tools** — no grant can add a tool to an agent, so the model does something else. - **Not allowed by this agent's role, or held back by the loop** — the refusal says which, and names the permission. No grant can change it inside the run: the owner changes the agent's role on the Agents page, or the loop's `capabilities`. - **Needs a permission this run does not hold** — only a person can grant one. In a loop's run this is a permission the role allows and the loop's `capabilities` hold back, or one of the four loop permissions (inside the `capabilities`, the published version grants that one at the call). If the loop's `grantable` names that permission, the run asks: a card asks the person in the conversation (`approve: user`), parks for you on **All runs** (`approve: operator`), or waits for your callback (`approve: external`). If the loop's `grantable` does not name it, nobody is asked. An entry in `grantable` grants nothing until somebody says yes, and publish refuses an entry that no agent of the loop could use, or that no agent's role allows. ## What each built-in tool needs A loop's own tools say what they need in their `requires` ([Tools](/docs/guide/tools.md)). These are the built-in tools. A tool marked **asks first** always asks a person before each call, even when the run holds what it needs. | Tool | Needs | Asks first | | --- | --- | --- | | `ask_user` | `notify` | | | `request_inputs` | `notify` | | | `notify_user` | `notify` | | | `escalate` | `notify` | | | `finish` | nothing | | | `read_file` | `read_workspace` | | | `list_dir` | `read_workspace` | | | `write_file` | `write_workspace` | | | `records_query` | `read_records` | | | `records_put` | `write_records` | | | `search` | `search_indexes` | | | `read_document` | `search_indexes` | | | `read_result` | `read_own_results` | | | `web_fetch` | `read_web` | | | `web_fetch_source` | `read_web` | | | `web_extract` | `read_web` | | | `rehearse_claim` | `rehearse_claim`, `read_web` | | | `github_search_issues` | `read_connection` | | | `gmail_list_messages` | `read_connection` | | | `calendar_list_events` | `read_connection` | | | `spawn_tasks` | `spawn_tasks` | | | `read_collection` | `install_loops` | | | `read_loop` | `install_loops` | | | `read_page` | `install_pages` | | | `read_tool` | `install_tools` | | | `propose_loop` | `install_loops` | asks first | | `propose_tool` | `install_tools` | asks first | | `propose_agent` | `install_agents` | asks first | | `propose_page` | `install_pages` | asks first | | `propose_collection` | `install_pages` | asks first | | `publish_loop` | `install_loops` | asks first | | `publish_page` | `install_pages` | asks first | | `propose_claim` | `install_automations` | asks first | `escalate` and `finish` are on no role's list: plutonium.io offers them to a run itself. `finish` needs nothing, because ending a run sends nothing: every run with a person in the conversation holds it, whatever the loop's capabilities. No built-in tool needs `call_endpoint`, `write_connection`, `run_code`, `serve_records`, `client_navigate`, `client_act`, `host_read` or `host_act`; only a loop's own tools reach those. ## The Rule of Two **No agent may hold all three marks at once.** An agent that reads outside content, touches your data and can act outside is one that a web page or a stranger's message can steer into doing something with your data that you never asked for. Any two of the marks are allowed; all three are not. plutonium.io adds up the marks of everything an agent can hold — its role's permissions, the loop's own tools, and anything the loop lets it ask for. A loop that declares any `delivery` (the embed, the SDK, the API) is **public**: what its users type is outside content too, so every agent of such a loop already carries that mark. Where the rule applies: - **Publish refuses** a version in which one agent could hold all three, and names the agent, the tool and the marks: for example, *"tool `send_report` takes agent `analyst` to all three trust properties …"*. A `grantable` entry that could only be answered by breaking the rule is refused too, because nobody could ever say yes to it. - **In a loop's run, the ask is refused before anybody sees a card.** The model is told that an action with external effects belongs to a separate agent that reads nothing. - **In a person's own run on the console**, the card that asks for a permission warns and names which permission brings which mark; the person may still approve it. **Once that run holds all three, every action with an outside effect waits for you** on a card that shows what it will send, before it runs. No card asks when you turned on yolo, or when the loop's published version answers its permissions itself. A visitor's run never gets this card: there the ask is refused, as above. - **Approving an automation warns** in the same words and does not refuse. The two usual fixes: 1. **Split the work across two agents.** One agent reads and decides; a second agent, which reads nothing, sends, given what it needs as arguments. The `outbound_writer` role (`send_external` and `notify`) exists for that second agent. 2. **Narrow the role or the loop.** Remove the permission that brings the third mark from the loop's `capabilities`, or from a tool's `requires`. ## Trusted and untrusted Some things a run reads can be marked **trusted** — content you vouch for. Untrusted is always the default. - **A loop's sources** (`sources[].trusted`). A file you upload is stored with that mark. When a run reads it, `read_file` reports the mark, and a file with no mark counts as untrusted. The model's instructions label each source *trusted* or *untrusted* and tell it to treat an untrusted source as data, never as instructions. - **A tool's answers** (`output.trusted` on a loop's own tool). An untrusted answer is read first by a separate model that has no tools, and only what that reader extracts reaches the run's model. A trusted answer reaches the model directly. A client tool's answer is never trusted, and a version that LoopAssistant proposes cannot make a tool's answers trusted: only you can. - **An index** (off by default). An **owner** of the account marks it on the index's page: press **Mark trusted…**, read what the mark changes, and confirm. A member sees the mark and cannot change it, and the account's audit log records each change with its old and new value. A search result from an index that is not trusted is marked untrusted. - **The run journal** ends each untrusted answer's line with *[untrusted]*. **What the index marks change in the Rule of Two.** Searching an index adds *outside content* unless the index is trusted, and adds *your data* unless it is public. A site crawl is public, because the crawl sends no login; uploaded files and a collection's records never are. So searching a trusted crawl adds neither mark. The loop's publish review names each index's marks and what a search of it adds. Publish checks the marks as they are and the version keeps them: marking an index trusted counts from the loop's next publish, and marking it untrusted counts at once. See [What an index lets a loop do](/docs/guide/search-indexes.md#what-an-index-lets-a-loop-do). **What the trusted mark does not change yet.** `read_workspace` and `read_records` always count as *outside content* and *your data*, whatever their sources say. ## Connections A **connection** lets plutonium.io reach another service as you, and it is not a permission: a run may use that reach only with a grant that names it. Connections have their own page, **Connections** in the console: see [Connections](/docs/guide/connections.md). --- # Connections > The services plutonium.io reaches as you — connect one with an API key or a sign-in, see how each stands, pause or remove it A **connection** lets plutonium.io reach another service as you. You make one on the **Connections** page in the console. **A connection is not a permission**: it says plutonium.io *can* reach the service, and a run *may* use that reach only with a grant that names it (see [Permissions and trust](/docs/guide/permissions-and-trust.md)). Each connection shows how it stands: **Connected**, **Needs attention** (with the reason, such as an expired sign-in), **Paused** or **Removed**, with the account it reaches, the access you allowed and who holds its secret. **With an API key.** Press **Connect a service**, name the service and the connection, and paste the key. The key is stored as an encrypted secret and no page ever shows it again. **Google.** Press **Connect Google**. Google asks you to sign in and to allow **read** access to Gmail, Google Calendar and Google Drive. You come back to the Connections page, and the connection shows as **Connected**, with the Google account it reaches and the access you allowed. If you untick an access on Google's screen, the connection holds only what you allowed. plutonium.io keeps the Google credential in a store that the tools never read. **Slack, Notion and Linear.** Under **Add a connection**, the Connections page lists every service plutonium.io can connect with a sign-in, each with what it asks for in plain words; **Find a service** narrows the list. Press **Connect** and the service's name beside one, such as **Connect Slack**: the service asks you to sign in and to allow that access, and you come back to the Connections page with the connection **Connected**. A service that shows **Not set up here yet** offers no button (see [A service that is not set up](#a-service-that-is-not-set-up)). To connect a second account of a service you have connected, give the new connection a name when the page asks for one (it suggests `slack_2`). A name uses lowercase letters, digits and `_` only. - **Slack** asks to see the public channels in your workspace and to read their messages. Your workspace's admin may need to approve the app first. - **Notion** asks you to choose, on its own screen, the pages and databases to share. plutonium.io reaches only what you chose. - **Linear** asks to read your issues, projects and comments. No tool uses a Slack, Notion or Linear connection yet: each gets its tools in a later release. **Another service (a custom provider).** An owner of the account can add a service that offers an OAuth 2.0 sign-in and is not in the list. Under **Add a connection**, **Another service, with your own app**, press **Add a service** and type the service's name. The page shows the redirect address for it (`https:///api/connections/oauth/custom-/callback`) with **Copy**: register an app at the service with that address first. Then give the service's sign-in page address, its token address, what to ask it for, and the app's client ID and secret. For a service that publishes OpenID Connect discovery, type its sign-in settings address and press **Fill in**: it fills most of these, and you check them before you press **Add the service**. A refused address is named under its own field. The service then shows in the list with the others, and anyone in the account connects to it the same way. - **Only an owner adds one, and an agent cannot propose one.** plutonium.io sends the app's secret and your sign-in to the token address, so only a person types it. - **Every address must start with `https://` and reach the public internet.** An address on a private network, on this machine or on a cloud metadata service is refused, when it is saved and again each time plutonium.io sends it a code or a token, and the refusal names the address that is wrong. - **The secret is never shown again.** To change a custom provider, remove it and add it again. plutonium.io removes one only when no connection uses it, so remove its connections first. **What reads a Google connection.** The **Researcher** agent has two Google tools: one lists your newest Gmail messages (the sender, date and subject of each, 5 unless you ask for more), and one lists one day's events on your primary calendar (today in the calendar's own time zone, unless you name a day). The first time a run uses one, a card asks you to grant it the connection. A separate reader reads the messages and events, so text inside an email or an invitation cannot direct the agent. **Coming:** a tool that reads your Drive files. While plutonium.io is in Google's **test mode**: - **Only named test accounts can connect.** Another account sees an error from Google. Ask the plutonium.io team to add your account. - **Google shows "Google hasn't verified this app".** Press **Continue** to go on. - **A connection lasts 7 days.** After that Google stops it, and the first run that uses it shows the connection as **Needs attention**. Press **Connect Google** again: the new consent replaces it. **Removing a connection.** Press **Remove**. plutonium.io deletes the stored credential; for a sign-in connection it first asks the service to revoke the access, and removes the connection even if the service does not answer. Notion offers no way to revoke, so remove plutonium.io from your Notion integrations too. A connection whose secret plutonium.io held leaves the page, and so does an MCP server that needed no sign-in, because no credential is left anywhere; one held elsewhere stays listed as **Removed**, naming who still holds it. plutonium.io keeps the record for 30 days, so a run that names it is told you removed it, rather than that it never existed. To connect Google again, press **Connect Google**: the new consent replaces the removed connection. **Pausing a connection.** Press **Pause** to stop every run from using it without removing it, and **Turn on** to let runs use it again. ## An MCP server An MCP server runs tools for plutonium.io's agents at another service. Under **Add a connection**, **An MCP server** lists the servers in the official MCP Registry that plutonium.io can connect, and **Find an MCP server** searches them. Press **Connect** beside a server: a server that needs a sign-in asks you to sign in, and you come back to the Connections page with the connection **Connected**. A public server that needs no sign-in connects at once, and plutonium.io holds no credential for it. A server you have connected shows **Connected** in the list. For a server the registry does not list, paste its address under **Or paste its address** and press **Connect**. The address starts with `https://` and is the server's MCP endpoint (it often ends in `/mcp`), not its website. If plutonium.io cannot connect a server, the Connections page says why and what to change. A connected server's card shows its name, its address and how many of its tools you approved. **Approve its tools.** A run may call only a tool you approve. Press **Review tools** on the server's card: it says whose account the calls act as, and lists each tool with the server's own description, word for word, and what it asks for (**Show the schema** has the exact form). A tool the server marks as only reading can be approved to **Read** or to **Write**; any other tool is approved as able to write. Press **Approve**. If the server changed the tool while you read it, the card says so and shows it again. **Stop it** takes an approval back. When the server changes a tool you approved, that tool stops: the card says **1 tool changed: it stops until you approve it again**, and **Review tools** shows what changed. Press **Approve again** or **Stop it**. A tool the server no longer lists says so. **Look again** asks the server for its tools now. On **Tools**, an approved tool shows with the others; you change it here, on Connections. Removing the server's connection stops every tool you approved on it: if you connect it again, you approve each tool again. **Use an approved tool in a loop.** Name it in the loop's tools, as any installed tool, by the name **Tools** shows (the connection's id, two underscores, and the tool's name). Its agent's role must allow reading connections (or writing them, for a tool approved as able to write), and the run's grant names this connection. Of the platform's roles, `general` (the agent a person talks with) and `web_reader` (the `researcher` agent's) allow reading connections. A tool its server does not mark read-only is approved as able to write, and one agent may not read your records or the web and also change things in a service. So on **Tools**, **Let another loop use it** gives a loop whose agent may not write a helper, the **Service writer**: your loop's own agent hands it each call, it reads nothing but what it was handed, and you choose who approves each call (you, or the person in the chat; only you, for a loop strangers open). Each call reaches the server through the connection, and is refused while the server describes the tool differently from what you approved. What the tool answers is never trusted: plutonium.io reads it apart from the agent first, as it reads a web page. ## A service that is not set up A service that shows **Not set up here yet** cannot connect with a sign-in here yet, and the page says *"Connecting Slack is not available here yet."* Reactor connects to a service through an app registered with that service, once for every account, and nothing you do on the Connections page changes that. When the app is registered, **Connect** appears beside the service. Until then, connect the service with an API key if it gives you one. --- # Asking the User > How a loop asks its user a question, collects details on a form that no model reads, checks an email address, and asks before it acts A loop can ask the person it serves for four things: an answer to a question, details on a form, proof of an email address, and consent before it acts on their page. Each one pauses the run until the user answers. A run with no user cannot ask anything; see [Triggers and Schedules](/docs/guide/triggers-and-schedules.md). ## A question The model asks with `ask_user`, and the user's next message is the answer. A reply that is only text also waits for the user. When the job is done, the model calls `finish`, and the user reads the loop's closing line. A loop that says `ends: {finish: false}` never offers `finish`: it keeps answering follow-ups, and the conversation ends when the person goes quiet. A `finish` in the same reply as a proposal the platform refused for its contents (a loop, page, tool, agent or claim) does not end the run: the model is told the proposal was refused, and it fixes the proposal before it finishes. The user answers one question at a time. A second `ask_user` in the same reply is refused, and the model asks it after the user answers. A question the model's text asks just before its `ask_user` is not shown, because the user reads the `ask_user` question; the run's journal counts each one it held back. A question that ends the model's last reply before `finish`, such as "Is there anything else I can help with?", is not shown either, because nobody can answer it after the run ends. When that question is all the reply says, as in "Hello there, how can I help?", the run does not end: the user reads the question, the run waits for their answer, and the run's journal records that its `finish` was overruled. When the answer is one of a small fixed set, the model passes them as `options` (two to six answers of a few words, each one a real answer). A question whose answer is free text, such as a list or an address, gets no options; an empty list of options is read as none, so the question is asked for a typed answer. An option that is itself a question ("What's your role?") is refused before the user sees a card, and the model is told to ask one question with no options; options that are all questions, each ending in "?", still get no card if they arrive: the user answers them in the box. Otherwise the user sees them on a card under the question, picks one and presses **Send**, and the model reads the picked answer's words as the reply. The user can also type an answer of their own below the card. **Skip** sends "I'd rather not answer." as the reply, so the loop goes on instead of waiting: write the loop's instructions so that it carries on without that answer. The model never asks the user to type an exact phrase. ### How long a conversation waits A conversation waits for the person, and it ends when they stay quiet: - After a reply that is only text, it waits 10 minutes, then ends as **completed**: the reply was the answer, and the loop's outputs run. The person then reads the loop's `completed` line, and the console's feed says *Ended after 10 minutes with no message from the person*. - With a question open from `ask_user`, it waits the platform's limit for a question, then ends as **lapsed**, and the person reads the loop's `lapsed` line. A loop sets both waits with `ends: {idle_minutes: N}`, from 1 to 60 minutes. Where the platform's own limit for a question is shorter, the question waits that limit instead. ## A form A form collects details that **no model reads**, such as an email address. Declare each input in the loop's record: ```yaml inputs: - id: email label: Work email kind: email required: true - id: company_size label: Company size kind: choice options: - {id: small, label: Under 50 people} - {id: large, label: 50 people or more} ``` | Kind | What the user gives | What the model reads | |---|---|---| | `email`, `text` | Typed text | Only whether it was given | | `choice` | One of `options`, or of a collection's rows with `options_from` | The chosen option's `id`, unless the input says `sealed: true` | | `choices` | Any of `options`, between `min` and `max` | The chosen ids, unless sealed | | `boolean` | One checkbox | True or false, unless sealed | The model asks for inputs by id with `request_inputs`, and the chat shows the form. `required` inputs must be filled before the form sends, but the user can always decline the whole form. A form that asks for part of a record also shows every `required` input the record is filled from that the user has not given on a form yet, even one they already said in the chat: only the form fills a record. The platform adds those inputs to the form itself, and tells the model which ones it added. **A value from a fixed list is decided first, and asked on a card only when it cannot be.** When what the user already gave settles it — a restaurant receipt is a meal — the model uses it without asking. When it does not, the model asks with `request_inputs` if the loop declares a `choice` input for it, so the user picks from the options; with no such input, it asks with `ask_user` and offers the options on a card. Declare the `choice` input for any fixed list your loop needs. **What the user already said is filled in.** When the model asks with a form and the conversation already answers part of it ("my order 1042 arrived broken"), it passes those answers in `prefill`, and the form opens with them chosen. The user changes any of them or sends the form as it is, so they never give the same answer twice. Only an input the model can see is filled in: a `choice`, `choices` or `boolean` input that is not `sealed: true`, with one of its own options (for `options_from`, one of the collection's rows). An `email` or `text` input, or any sealed input, always opens empty, because the user types it themselves. A value that cannot be used is left out, and the model is told which one and why. When the model leaves a `choice` or `choices` input empty, pio fills it itself if the user's own messages in this conversation name exactly one of its option ids as a whole word, such as `3307` in "I never got order 3307". If they name two or more, the input stays empty for the user to pick. A value the model sent always wins, a `boolean` or sealed input is never filled this way, and the model is told which inputs pio filled. **After a save that a form filled, the user reads your loop's `completed` line.** The model never sees a typed value, and what the user said in the chat is not in the record unless a field holds it: a phone number mentioned in a message, with the form's phone field left empty, is not on file. So before the form, the model never promises to note something the user said: it asks them to add it on the form, under the field's label. Under its buttons, a form with typed fields says "Send passes on what you entered. Don't send passes on nothing, and the chat goes on.", and it says who reads what: "What you enter goes to this site; the assistant never reads it." And the first reply after the save shows `end_messages.completed` in place of the model's words (see [The last line of every run](/docs/guide/money-limits-members.md#the-last-line-of-every-run)). Write it as what the user should read once their details are saved, such as "Thanks, your booking request is saved." **A refusal is an answer.** The user can press **Don't send**, or type in the chat while the form is open; typing closes the form, and the loop reads their words next. Either way `request_inputs` returns `declined`, and the loop replies to it: it carries on without a detail it does not need, and for one it does, it says in one sentence why and what the user can do instead, and ends kindly without inviting a reply, because the conversation ends there. It shows the form again only when the user's own message asks for it. A user's typed words count as their answer where they settle the question ("bath and brush, please"). Write in your loop's `entry` what it does without each required detail. ### Send a value to a tool without the model A tool receives a value through `bind`, which maps a tool argument to an input id: ```yaml tools: - use: create_lead bind: email: email ``` The bound argument leaves what the model sees, and the platform fills it in when the tool runs. Publish refuses a `bind` that names an input the loop does not declare, or an argument the tool does not have. ### Keep a value in a collection without the model A [collection](/docs/guide/collections-and-outputs.md) can take a value through `bind` too, which maps a field to an input id: ```yaml collections: - name: leads key: email fields: email: string company: string bind: email: email ``` When a run writes `leads`, the platform fills `email` from what the user typed, and the model leaves it out. A value the model sends for a bound field is ignored, the user's value is written, and the model is told which fields it should leave out. If the user leaves an input that is not `required` empty, the record is written without that field. The write waits, and tells the model to ask with `request_inputs`, only while a `required` input is empty, while the input the collection's key comes from is empty, or before the user has given any of them. A bound field is **sealed**: no model reads it back. `records_query` leaves it out of every record and says so, for every loop that reads the collection. A record keyed on a bound field shows the model its id as `[sealed:email]`. You still see the value on **Collections**, through an API key, and on a [page](/docs/guide/pages.md). A search index cannot cover a sealed field. A collection keyed on a sealed input must bind it. With no `bind`, every record would carry the same placeholder key and replace the one before it, so publish refuses it and names both fixes: bind the input, or key the collection on a field the model writes. Each input must be declared in `inputs`, and each bound field in `fields` with the type of the input's value: `string` for `email`, `text` and `choice`, `array` for `choices`, and `boolean` for `boolean`. **A seal is never lifted.** A later version without the `bind` keeps the field sealed, because the records already hold real values. ### Record who started the run A collection can also bind `run_subject`, which holds who started the run. The user does not type it, and you do not declare it in `inputs`: ```yaml collections: - name: bookings key: slot fields: slot: string visitor: string bind: visitor: run_subject ``` The platform fills `visitor` from the run itself. For a visitor who is not signed in, the value is `anonymous:` and their visitor id. A [page](/docs/guide/pages.md) with `rows: owner_field:visitor` then shows each reader only the bookings their own runs wrote. A run that an API key or a schedule starts has no subject, so its record is written without `visitor`. An input cannot use the id `run_subject`: publish refuses it. ### Keep one entry per order A collection's `key` is the thing there is exactly one entry of. Key orders on the customer's email and their second order replaces the first. Bind `run_id` instead, which holds which conversation wrote the entry, and key on that field: ```yaml collections: - name: cake_orders key: order_ref fields: order_ref: string email: string size: string bind: order_ref: run_id email: email ``` The platform fills `order_ref` from the conversation itself, so each conversation keeps one order, and a change later in the same conversation updates it. Key on `email` only when you mean one entry per person, such as a waitlist. An input cannot use the id `run_id`: publish refuses it. When one conversation files several entries, such as a meeting's action items or an order's lines, bind `run_item` instead and declare a number field `n`. The model numbers the entries 1, 2, 3 in the order it meets them, and the platform fills the bound field with the conversation and that number, so each entry has its own key, and a corrected entry written again with the same `n` updates it: ```yaml collections: - name: action_items key: item_ref fields: item_ref: string n: number task: string owner: string bind: item_ref: run_item ``` Publish refuses `run_item` on a collection with no `n: number`, and in a tool's `bind`. When each person keeps their own entries across conversations, and the same thing filed twice is one entry, such as an employee's expense receipts, bind `subject_item` instead and declare a text field `item`. The model writes in `item` what identifies the thing itself, such as a receipt's date and total, never wording it chooses. The platform fills the bound field with who started the run and that `item`, so two people filing the same receipt keep one entry each, and one person filing it twice keeps one: ```yaml collections: - name: expense_claims key: claim_ref writes: create fields: claim_ref: string item: string merchant: string amount: number bind: claim_ref: subject_item ``` With `writes: create`, the second filing of the same receipt is refused rather than replacing the first, and the loop tells the person it looks like one they already filed. Publish refuses `subject_item` on a collection with no `item: string`, and in a tool's `bind`. A run nobody started, by a key or a schedule, cannot write such a collection. ### Offer only what is open A day and a time typed as text can be anything, and a real scheduler offers only the slots it has. When what the user may pick changes while the loop runs, give the `choice` input `options_from` instead of `options`: each row of one of the loop's collections is an option. ```yaml collections: - name: slots key: at writes: none fields: {at: string, slot: string, label: string} - name: appointments key: slot writes: create fields: {slot: string, email: string} bind: {slot: slot, email: email} inputs: - id: slot label: Which slot kind: choice required: true options_from: collection: slots value: slot label: label exclude: {collection: appointments, field: slot} ``` The form reads the rows when the model asks for the input, in the order of the collection's `key`. `value` is the field that is the option's id, and `label` the field the user reads; both are `string` fields, and neither may be one a `bind` fills. `exclude` leaves out a row whose value the other collection's field already holds, so a booked slot is not offered to the next user. Key the bookings on the slot with `writes: create`, as above, and each slot is booked once: when two users were shown the same open slot, the second booking is refused, the model is told the slot was just taken, and it asks for another on a new form. `writes: none` marks a collection no run writes, such as the slots themselves; the default, `upsert`, replaces a record of the same key. When no row is open, the form is not shown: `request_inputs` tells the model so, and the model tells the user. The model reads the picked row's id in `chosen` and the label the form showed in `chosen_labels`, so a label such as an order's items and total is how the model learns them. Your loop writes the rows it offers, or you add them yourself. A `test_case` answers with an id that a row holds when the case runs, because publish cannot know which rows will be open. ### Greet the user by name A reply can use a value that the model never sees. The model writes `{{user.}}`, and the user's own chat fills it in: ```yaml entry: > Greet the visitor as "Hello {{user.name}}!" and ask what they need. ``` The names a reply may use are the loop's input ids and the claims that `identity.claims` copies from the user's token, such as `name`. The model's prompt lists them. - **Only the embedded chat fills a template**, from what the user typed into the form in that window and from their own token. No server reads the value to fill it. - **Nobody else reads the value.** The console and **My conversations** show which value the user's chat filled, such as "[the person's name]". The run's record, a tool argument (use `bind` for that) and an output keep the template as written. - **A template fills in plain text only.** Inside a link, an image or code it stays as written, so no reply can carry the value to another site. - **A value the chat does not hold reads as "there"**, such as an input the user has not filled yet, or one they filled in another tab: "Hello there!" A reply that names something the run cannot fill, or writes `{{name}}` without `user.`, is sent back to the model once, with the names it may use, so that it writes the reply again. ### Every sealed input must reach something Publish refuses a sealed input that no tool's or collection's `bind` names and no `{{user.}}` in `entry` uses. A value the user typed into it would reach nothing. The refusal names the three fixes: bind it, greet with it, or remove it. ### If the user does not answer If the user declines the form, or nobody answers it in time, the loop reads that the user gave nothing, and the conversation goes on. ## An email check A loop can ask the user to prove an email address before it acts for them: ```yaml checks: - kind: user_verification method: email ``` The run waits before the first step that writes or sends anything, and before its outputs leave. The user receives a code by email, types it into the chat, and the run goes on. If the user's identity already gives an address, the code goes there. A code that is not redeemed in time ends the run with the loop's own words. Neither the address nor the code reaches a model. A tool can receive the checked address through `bind`, as `verified_email`: ```yaml tools: - use: lookup_account bind: email: verified_email ``` ## Consent before an action A loop can ask your web page to act for the user, through a **client tool**. Before an action, the chat shows the user a card that describes it, and the user approves or declines. See [Embedding the Chat](/docs/guide/embedding-the-chat.md). --- # Collections and Outputs > Where a loop keeps what it learns — collections of records — and where it sends a result when a run ends A loop keeps what its runs produce in **collections**: named sets of records with declared fields. It sends a result out of the platform through its **outputs**: a signed webhook to your system, or an email. ## Declare a collection A run may write only the collections its loop declares: ```yaml collections: - name: leads key: email fields: email: string company: string company_size: string score: number ``` | Key | What it says | |---|---| | `name` | The collection's name, such as `leads`. | | `key` | The field that identifies a record. Its value becomes the record's id. | | `fields` | Each field and its type: `string`, `number`, `boolean`, `date`, `file` or `row`, or `generated` for the key alone. A write that carries a field the declaration does not have is refused. A `file` field holds a file a reader uploads through a page form ([Let readers upload a file](/docs/guide/pages.md#let-readers-upload-a-file)); only that upload fills it, and a loop's run or an automation that writes one is refused. | | `shared` | `true` when other loops in the account may read and write this collection too. | | `choices` | Optional. The only values a `string` field takes, by field: `status: [open, doing, done]`. See [Fixed values for a field](#fixed-values-for-a-field). | The collection is created when you save the draft that declares it, so you can try the loop on **My conversations** at once. A run writes records with `records_put` and reads them with `records_query`. ### Let the platform make the key When nothing in a record names it, such as a task or a ticket, declare the key `generated`: ```yaml collections: - name: tasks key: task_id fields: task_id: generated title: string status: string ``` - **To create a record**, the run leaves `task_id` out. The platform makes a new id, a UUIDv7, and the answer to `records_put` names it. Three writes make three records. - **To edit a record**, the run sends the `task_id` of a record it created or read, with the fields to change. The fields it leaves out keep their values, and the record keeps the time it was created. A `task_id` that no record holds is refused, and the refusal tells the model to leave the key out to create a record. So a model can never choose an id. - Only the key can be `generated`, and such a collection takes no `writes: create`, because every new record has a new key. Saving the draft refuses both, and names the fix. - A [page form](/docs/guide/pages.md#let-readers-add-a-record) on such a collection leaves the key out too: each save makes a new record. To keep what a person types in a record, see [Keep a value in a collection without the model](/docs/guide/asking-the-user.md#keep-a-value-in-a-collection-without-the-model). ### Fixed values for a field A `string` field can name the only values it takes, such as a task's `status`: `open` or `done`. On **Collections**, press **New collection**, tick **Only these values** under the field, and type them, separated by commas. The card names them before you press **Create**: "Adds status (Text, only open, done).". With the API, give the field `"choices": ["open", "done"]` in its declaration. To change the values of a field the collection already has, press **Change fields of** the collection, and edit the values beside the field. Clear them to remove them all. The card says the values now and after the press before you press **Save**: "Changes the choices of status. Now: open, done. After the press: open, doing, done.". - At most 50 values, each 1 to 100 characters. The console drops repeats. - Only a `string` field takes choices; the review refuses another type and names the fix. - A write sets a field's choices to what it sends, so a declaration that sends a field back as the collection lists it keeps them. - Removing a value does not change the records that hold it. The card says how many hold each value you remove before you press **Save**: "1 record holds “blocked”; it keeps that value and no form offers it." A collection of more than 500 records reads "At least". A page's board shows such a record in a column of its own value, said as not one of the field's values. In a loop, list them under the collection's `choices`, in the order a page shows them: ```yaml collections: - name: tasks key: task_id fields: task_id: generated title: string status: string choices: status: [open, doing, done] ``` - Saving the draft refuses a list on a field that is not `string`, an empty list, and a value listed twice, and names the fix. - A value outside the list is refused, naming the list: a run's `records_put`, a page form, a row's **Edit**, an action button and a block's `where=` all check it. - Approving a version that lists different values for a field sets that field's list to them. A field the version lists none for keeps the values it has. - A [page](/docs/guide/pages.md#blocks) shows a choice field's values as labels, asks for it with a list to choose from, and offers every value as a filter button. ### A field that refers to a row A `row` field holds the record id of one row of a collection, such as the task a comment is on, or a row of its own collection, such as a task's parent task. On **Collections**, give the field the kind **A row of a collection** and choose its collection under **A row of…**, where a new collection lists itself as "(this collection)"; the card names it: "Adds task (A row of tasks).". With the API, give the field `"type": "row", "of": "tasks"`. The claim keeps it under the collection's `refs`: `refs: {task: tasks}`. - The collection must be one the account has; the review refuses another and names the ones it has. - A collection has at most one `row` field. - A write whose `row` field names no row of its collection is refused, naming the collection, and nothing is written. ### Who may change or remove rows from a page A collection says who may change and who may remove its rows from a page, in `access`. Without it, no page changes or removes a row: ```json {"access": {"change": {"by": ["member", "user"], "rows": "own"}, "remove": {"by": ["admin"], "rows": "any"}}} ``` - `by` names the readers who hold the right: any of `anonymous`, `user`, `invited`, `member` and `admin`. An invited reader's own rows are the ones they added from a page that invited them. - `rows` is `own` (only the rows that reader added) or `any` (every row). - A record remembers who added it: the person or visitor whose run or form wrote it. Records written before 2026-10-18, by a pipeline, or by an anonymous visitor have no one who added them, so they are nobody's own. An `own` right for `anonymous` is refused for that reason. - A page may only narrow this: fewer readers, or `own` in place of `any` ([Who may change rows](/docs/guide/pages.md#the-page-document)). - Set it on **Collections**: open the collection, which says who may change and remove its rows now, and press **Who may change rows of …**. This is the place for every collection, one a published loop declares too: the loop owns its key, fields and choices, and the rights are yours. A change to the fields of a loop's collection is refused here, naming the loop. Or set it with the collection's declaration, `PUT /api/workspace/collections/` with an `access` key. A declaration without `access` keeps the one the collection has, and so does a loop that widens the collection; `"access": {}` removes it. - The card that comes before the write says who may change and remove the rows once you press, and for a change to them, who may now and who may after. A page's Edit, Delete and action buttons use it: see [Let readers change and remove rows](/docs/guide/pages.md#let-readers-change-and-remove-rows). ### One collection, one loop, unless it is shared A collection belongs to the account, and its name is its identity. If two loops declare the same name, they read and write the same records. So saving a draft refuses a name that another loop already declares, unless every loop that declares it says `shared: true`. The refusal names the collection, the other loops, and both fixes: rename it, or declare it shared everywhere. Two loops that already declare the same name can each be saved while you add `shared: true` to them one at a time; a save that adds a new clash is still refused. ### Change a collection A later version can add fields: records written before simply lack them. Saving the draft refuses an edit that removes a field the loop declared before (in its published version or its saved draft), or changes a field's type or key, and names the fields: keep them, or declare a new collection. A loop never removes a field it did not add: a field you, a pipeline or another loop added stays, and leaving it out refuses nothing. ### Ask LoopAssistant for a collection or a field You can ask LoopAssistant for a collection, or for a change to one you have: "add a due date to my tasks", "let status be blocked too". It proposes the change on a card, and approving installs it. - For a new collection, the card shows it whole: every field with its type and choices, and the field that names each record. Nobody may change or remove its rows from a page until you say so on the Collections page. - For a change, the card shows only what changes: the fields it adds, and a field's choices before and after. Every field it does not name stays as it is. - LoopAssistant never changes who may change or remove a collection's rows: you set that on the Collections page. - A change from LoopAssistant only adds. It never removes a field or a choice; to remove a choice, edit the collection on the Collections page, whose card says how many records hold each value it removes. - Create (or Save, for a change) installs it; Decline leaves the collection as it is. - The card runs the same checks as the Collections page. A change that would change a field's type or the key is refused, naming the field, and a collection a published loop declares is changed in that loop. - When a page you ask for needs a field the collection lacks, LoopAssistant proposes the field first, then the page. Saving such a page yourself is refused in words that say to add the field to the collection first. ### An automation that writes a collection An automation step that writes a declared collection is held to its field types and its [fixed values](#fixed-values-for-a-field), as a run's `records_put` is. If one row has a value of another type, or a value outside a field's list, the step fails, names the row and the field, and writes nothing. A field the collection does not declare is still written. The card you approve the automation on warns about it and names the step that makes it: declare the field in the collection, or remove what makes it. ## Read your records **Collections** in the console shows your collections, one at a time. Each one says who writes it: each loop that saves records into it, a crawl by the site it fetches, or an automation by its name. An empty one says who will fill it. **New collection** asks what the collection is called and what each record holds: each field's name and its kind (Text, Number, Yes or no, Date, A file, or A row of a collection). Each record gets its own id, so no record replaces another. To name each record by one of its fields instead, such as a customer's email, open **More options**: the form and the card then say "A second record with the same email replaces the first." **Review** says what is still missing. Your loops and pages add records, and an owner can add one by hand; the collection then says it is written by *an owner, by hand on Collections*. - **Definition** shows what the collection is: each field with its kind in words and, where it has them, its only values; what the key does to a second record; and which fields are **sealed**: filled from what a person gave, never by the model, and never read back by a model. It says what each loop fills from its inputs, which loops and pages read the collection, and who may change or remove its rows from a page. A write that does not fit it is refused. - **Records** shows the records, sorted by record id. Each row leads with its fields, then when it was written, then the ids: a field pio generates, such as a generated key, and the record id. When the key is a generated id, that one column is the record id. - **Add a record…** on the Records tab, for an owner of a collection that declares its fields, opens one input per field by its kind, the field key first: a list of its values for a field with only some values, Yes or No, a date, and the records of the other collection for a row, each named by its first text, such as **Front desk (r-1)**. Reactor gives the record its own id, and a file is added through a page's form, so neither has an input. **Add the record** saves it; anything refused is said under the field it names. A field key must be filled: it names the record, and one already saved is refused rather than replaced. To change the definition, press **Change fields of** the collection to add fields or change a field's values, or **Who may change rows of** it. Each change shows its card before you save. To show the records on a page of your own design, write a [page](/docs/guide/pages.md). To serve records to another server, create an API with **New API** on **Schedules**, then open it there and press its **Mint a key for** button, which names the API. See [Collections](/docs/api/collections.md) in the API reference. ## Outputs `outputs` say where a result goes when something happens in a run. A run with no user must declare at least one. A webhook or an email output names the `event` that sends it: - `run.ended`: once, when a run ends. - `run.escalated`: when a run, or a task inside it, hands the work to your team. - `record.written`: each time a run saves a record, while the run goes on. Two records saved make two deliveries, each naming its collection and record. `run.started` and `check.failed` are not sent yet, so publishing an output on either is refused. ### A webhook ```yaml outputs: - kind: webhook event: run.ended url: https://crm.example.com/hooks/pio ``` When a run ends, the platform POSTs a short JSON body to your `url`: the event, the loop and its version, the run, and how it ended. The body carries identifiers, never text a model wrote; read the run itself through the run API. Each delivery is signed with the loop's **webhook signing secret**, shown on the loop's **Keys** tab. [Webhooks](/docs/api/webhooks.md#out-of-a-loop) shows the body, how to check the signature, and the retries. ### An email ```yaml outputs: - kind: email event: run.ended to: sales@example.com ``` `to` is one address. To email several people, add one email output for each: a list in `to` is refused when you save the loop. When a run ends, the platform sends an email to `to`, but only to a **verified** recipient: - An address that belongs to a member of your account is verified already. - Any other address gets one confirmation email from plutonium.io when you publish the loop. It receives nothing from the loop until that person confirms. The link in the confirmation is valid for 7 days. - Every email carries a one-click **unsubscribe** link. After an unsubscribe the address gets nothing more, and adding it again needs a new confirmation. An email for an address that is not verified is **held**: it is not sent, and it is not sent later either. After the person confirms, the next run's email goes to them. A held email is not charged, and on **Loops** its output counts it as not sent and says why. While an address a published loop emails waits on a confirmation, **Home** names it under **Needs you**, with how many of the loop's emails are held. When you publish, the loop's page lists each address its email outputs name and what the publish did about it. Afterwards, under each email output, **Loops** shows where its recipient stands: confirmed, asked, lapsed, never asked, unsubscribed, or bounced. If no confirmation is waiting (it lapsed, none could be sent, or the person unsubscribed), press **Send a confirmation email** there. A confirmation that is still valid is not sent again. If the confirmation email **bounces**, the address does not accept mail. Its recipient reads "the confirmation bounced", and nothing asks that address again: correct the address in the email output and publish the loop again. An address in a loop published before confirmations existed has no recipient line; publish the loop again to send it a confirmation. A page's form can email at each save, without a loop, with the same confirmation for an address that is no member's: see [Email someone when a form saves](/docs/guide/pages.md#email-someone-when-a-form-saves). ### Delivery status On **Loops**, each webhook or email output says how its deliveries are doing: how many failed, how many are waiting or retrying, how many emails were held and not sent, and the last error. A delivery that fails never changes how the run ended. --- # Pages > Markdown pages that show your collections — written, previewed and published like a loop A **page** is a markdown document that shows records from your [collections](/docs/guide/collections-and-outputs.md): a table of orders, one customer's record, how many leads came in. You write it on **Pages** in the console, preview it as you type, and publish it. A page is a record published like a loop: you edit a **draft**, and readers see the **published version** until you publish the next one. Members and admins read pages in the console, and a published page can also be placed on your own site in a frame (see [Put a page on your site](#put-a-page-on-your-site)), where a block can hold a loop's chat or a form a reader adds a record with (see [Let readers add a record](#let-readers-add-a-record)). ## Write a page 1. Open **Pages** and press **New page**. 2. Under **Start from**, keep **A blank page**, or choose one of the [starter pages](#starter-pages). 3. Enter a **Name**, such as "Order status". A blank page is headed by it as you typed it. A starter fills in its own name until you type one. The page's short name, such as `order_status`, is made from it and shown under it; it names the page in its address and never changes. To choose another, open **More**. A short name your account already has gets a number, such as `order_status_2`. 4. Press **Make the page**. A blank page lists your account's first collection, if it has one; a starter is its own page under your name. The page is saved, not published, and its screen opens with its preview. Publish it (see [Publish](#publish)), or first press **Change it yourself** to edit its text. You can also ask LoopAssistant for changes on its screen, before or after you publish it (see [Change a published page](#change-a-published-page)). A page that is made can still warn: on its screen, it lists the same warnings the publish card shows (see [Publish](#publish)) until you press **Done**. If the page is refused, the screen names each problem, and **Change it yourself** opens the editor on its text. The editor's preview follows your typing, and a key the page does not have, or a value it does not take, is marked as you type. The save checks in two steps. First it checks the document itself, and names every problem there at once, each at its template line or at the key it is about, with the fix. Only when the document passes does it check the blocks against your account, so a second save can find problems that the first did not name. ## Ask LoopAssistant for a page You can also ask LoopAssistant for a page, for example "a page that shows my leads to my team". LoopAssistant asks who reads the page and what it shows, and then proposes it on a card. The card shows who may read the page, each collection it reads, and what each block shows. - **Approve** saves the page as a draft. Nothing is published yet. - LoopAssistant then asks to publish it, with the Pages screen's own **Publish** card in the chat, with what the draft changes against the version readers see now. Pressing **Publish** publishes the draft in your name, with the same checks; **Decline** leaves it a draft. If the draft was saved again after LoopAssistant asked, the card says so and does not publish it. - You can also open **Pages** to read the draft, and publish it there as any other draft. Until you publish a page it proposed, LoopAssistant can revise that page's draft in the same conversation. ### Change a page with LoopAssistant You can ask LoopAssistant to change a page your account already has, for example "add a Done button to my tasks page". LoopAssistant reads the page as it is published, and then proposes the whole next version with only what you asked changed. The card asks "Save a change to “Tasks” as draft v3?" and shows what changes against the version readers see: - each other change in a sentence, for example who may read the page or a collection it reads, - the template line by line. Each changed line says **Removed:** or **Added:**, and a changed line reads as the old line removed and the new line added, with only the words that change marked: struck through on the removed line and underlined on the added one. Long lines wrap, so the change shows on a phone too. One unchanged line stays beside each change, and the rest are folded with their count. A line that is one block, such as `{{collection orders}}`, reads as what the block shows ("A table of Orders …"), with its text under **As written**; a block that replaces another says **Changed:**, and **As written** shows the old and the new text. The card leads with the change. Press **Show the whole page** to read the whole page as it will be, with who may read it, each collection it reads, and the preview. **Approve** saves the change as the page's next draft. Readers keep the published version until you publish the draft on the Pages screen, and the publish card shows the same change. When a change is already waiting, even on a page you never published, LoopAssistant's change starts from that draft, yours or another run's: the card shows what this request changes in it, and **Approve** replaces it. So you can adjust a new page as often as you like before anyone sees it. If the page changed after the card was drawn — its draft was saved again, a draft was saved where there was none, or the page was published again — nothing is saved. The chat says so under your approval: *Nothing was saved: the page changed after you approved. LoopAssistant shows the change again.* LoopAssistant then reads the page again. LoopAssistant proposes pages for members, admins, anonymous visitors and invited readers. A page for visitors comes with its limits on what one address may do, and with its own public address when you want a link to send. A page for invited readers names the addresses or domains it invites, and a change to it keeps them. A page for signed-in users of your own site is set up on the Pages screen, because it needs a key you set there. When the page itself is where its records come from, such as a feedback form, LoopAssistant can create the collection with it. The card names that on its own line, for example "Creates collection `feedback` with fields message, written by anonymous.", and approving the card creates the collection as the Collections page would. A field with [fixed values](/docs/guide/collections-and-outputs.md#fixed-values-for-a-field) is named with them: "Creates collection `tasks` with fields title, status (open, doing, done), written by member.". A name your account already has is never written over. Otherwise, if LoopAssistant names a collection your account does not have, in any block or form, the card is refused with the collections you do have, and LoopAssistant proposes again with one of them or creates the collection with the page. If you ask for a loop and a page that shows what the loop keeps, LoopAssistant proposes the loop first. The loop's collections exist once you approve its card, so the page's card comes after that. If LoopAssistant does not propose the page, it says so, and you can make the page on the Pages screen. ## Starter pages Four starter pages show the common shapes. Each one reads one collection, and the FAQ also embeds a loop's chat: change each name to one your account has. | Starter | Who reads it | What it shows | What it needs | |---|---|---|---| | Tasks | Members and admins | A board of open, doing and done tasks by due date, each card with **Start**, **Done**, **Reopen**, **Edit** and **Delete**, a task's own view when you open it, a search, a chart of how many tasks are in each status, a calendar of tasks by due date, and a form that adds a task. | A collection `tasks` with `title`, `status` (with the choices open, doing and done), `owner` and `due`, whose rows members and admins may change and remove. | | Send us a request | Anyone, at its own address | A form that leaves a request or feedback, with a file if they have one, and no sign-in. Each request emails the account's owners. | A collection `requests` with `name`, `email`, `message` and a file field `attachment`. | | People | Members and admins | Your team's people, as cards, with a search, and a form that adds a person, which only admins see. | A collection `people` keyed by `email`, with `name`, `role` and `phone`. | | Questions and answers | Anyone, at its own address | Answers from a collection, a form that adds one, which only an admin sees when they open the page in the console, and a chat with one of your loops. | A collection `articles` keyed by `question`, with `answer`, and a published loop `help` for visitors. | Choose one under **Start from** on **New page**. The screen says whether your account has the collection the starter reads. If it does not, **Make the page** makes it first: the same card as on **Collections** shows what it creates, nothing is created until you press **Create**, and then the page is made. Or rename the collection to one you have, with **Change it yourself**. A collection whose key is made for each record (`tasks` and `requests`) lets a form save a new record every time. Then change the readers if you want others, save and publish. LoopAssistant starts a page you ask it for from the nearest starter, for your team or for visitors. For a page where visitors leave feedback, it starts from **Send us a request**, and it can create the collection on the same card (see [Ask LoopAssistant for a page](#ask-loopassistant-for-a-page)). A page for visitors needs an `identity` block in its `access`, as a loop's does. The two visitor starters' documents: Send us a request: ```yaml # A starter page: a public form where anyone leaves a request or feedback, with # a file if they have one, and no sign-in. It assumes a `requests` collection with # `name`, `email`, `message` and a file field `attachment`; name yours. Each # request emails the account's owners, and your team reads it on Collections. page_id: request_form title: Send us a request access: readers: [anonymous] identity: {kind: anonymous, limits: {per_ip: 30/1m, monthly_writes: 500}} delivery: {public_path: true} collections: - {name: requests, read: [admin], write: [anonymous]} template: | # Send us a request Tell us what you need. We read every request. {{form requests fields=[name, email, message, attachment] email=owners}} ``` Questions and answers: ```yaml # A starter page: public answers, and a chat for a question they do not # answer. It assumes an `articles` collection with `question` and `answer`, and # a published loop named `help` that signs visitors in as anonymous; name yours. # An admin who opens it in the console sees a form that adds an answer; visitors # never do. page_id: faq title: Questions and answers access: readers: [anonymous, admin] identity: {kind: anonymous, limits: {per_ip: 30/1m}} delivery: {public_path: true} collections: - {name: articles, read: [anonymous, admin], write: [admin]} loops: [help] template: | # Questions and answers {{collection articles fields=[question, answer] view=list sort=question}} {{form articles fields=[question, answer]}} ## Ask us Not answered here? Ask your question in the chat below. {{loop help}} ``` ## The page document ```yaml page_id: order_status title: Order status access: readers: [member, admin] collections: - {name: orders, read: [member, admin]} template: | # Order status Orders so far: {{count orders}}. The latest: {{collection orders fields=[number, customer, status] limit=20}} ``` | Key | What it says | |---|---| | `page_id` | The page's id. It must be the id you gave the page. | | `title` | The title a reader sees in the page list. | | `access` | `readers`: who may read the page, any of `member` and `admin`. A page with its own address may also name `anonymous`, or `invited` with the people it invites (see [Open a page to the people you invite](#open-a-page-to-the-people-you-invite)). | | `collections` | Each collection the page's blocks may show, and who may read it: `read: [member, admin]`. A block may show only a collection listed here. | | `collections` … `rows` | Optional. Leave it out, and a reader sees every record of that collection they may read. Write `rows: owner_field:` to show each reader who is not a member only the records whose `` holds their own identity. To fill `` with that identity when a loop writes the record, bind it to `run_subject` (see [Record who started the run](/docs/guide/asking-the-user.md#record-who-started-the-run)). A member or an admin always sees every record. | | `collections` … `write` | Optional. Who may add a record to that collection through a `{{form}}` block: any of `anonymous`, `user`, `invited`, `member` and `admin`. Leave it out, and nobody can. See [Let readers add a record](#let-readers-add-a-record). | | `collections` … `change`, `remove` | Optional. Who may change and who may remove rows from the page, and which: `change: {by: [member], rows: own}`, where `rows` is `own` (the rows the reader added) or `any`. Only within what the collection's own `access` allows (see [Who may change or remove rows from a page](/docs/guide/collections-and-outputs.md#who-may-change-or-remove-rows-from-a-page)): the save refuses more, naming the collection's setting. Leave both out for a page whose readers only add rows; `by: []` is the same as leaving one out. See [Let readers change and remove rows](#let-readers-change-and-remove-rows). | | `template` | The page itself: markdown, with blocks in `{{ }}`. | A document may also carry `delivery` and `loops`. `delivery` puts the page on your site (see [Put a page on your site](#put-a-page-on-your-site)), and `loops` lists the loops whose chat a `{{loop}}` block shows. A console page needs neither. ## Blocks A block is one `{{ }}` in the template, on one line. It shows records from a collection the page lists, and it sits in the page where you write it. | Block | What it shows | |---|---| | `{{collection orders}}` | The collection's records: a table, or a list or cards with `view=list` or `view=cards` (the keys are below). The publish card names the view: "A table of", "A list of" or "Cards of". | | `{{record orders A-1042}}` | One record, by its id: the value of the collection's `key` field. | | `{{record orders from=row}}` | The row a reader opens: each row of a `{{collection orders}}` block on the page links to it. See [A row's own view](#a-rows-own-view). | | `{{search orders fields=[number, note]}}` | A search box. A reader types words and finds the rows that hold every word in one of the listed fields (all the collection's fields without `fields=`). It searches only the rows that reader may read, so it never finds a row the page hides from them, and it never searches a sealed field. It reads at most 500 rows: a reader who may read more is told "Searched the first 500 rows you can read". It works with scripts off. It takes `fields=`, `limit=`, `view=`, `where=` and `sort=`, as a collection block does. | | `{{count orders}}` | How many records the collection holds. Above 500 it reads "500 or more". It shows the number alone, so write the words before it, as in `Orders so far: {{count orders}}`: after it, "orders" reads wrong when there is one. | | `{{fields orders}}` | The collection's declared fields and their types. | | `{{chart orders by=status}}` | A chart of the collection's records: one bar for each value of the field, as long as how many records hold it. `sum=total` adds a number field instead of counting rows; `view=line` draws a line over a date field or `by=@created_at` (each day a row was added; `@changed_at` for the day it last changed), every day from the first to the last, a day with no records at zero (when every record falls on one day, that day draws as one bar, since one point is no line); `where=` takes the conditions a table's does. Its title says what it counts and which rows: "Tasks by status", "Sum of total by status", "Tasks by status, where owner is ivy". A choice field draws its values in their order, each one, none held or not; other values draw the largest first; records with no value draw as "(none)". It draws at most 31 bars or days and says how many more it leaves out (on a line, the latest 31 days). Each reader's chart counts only the records they may read. It reads at most 500 records: past that, it says each number is at least what it shows, and a `sum=` over a field that holds a number below zero is not drawn, because its total could be wrong either way. It reads with scripts off. A `sum=` of a field that is not a number, or a line over a field that is not a date, is refused at the save. | | `{{loop order_help}}` | The loop's chat, on a page placed on your site. It runs as the page's reader, so they sign in once. The loop must be one your account published (a loop Reactor ships, such as `lead_qualification`, opens on your page only as your own edited version; start from a demo on Home instead), listed under the page's `loops`, and sign readers in the same way as the page: a save or a publish is refused when it signs them in another way. To let the chat change what its reader sees on the page, for their visit (write in a scratchpad, filter or refresh a table, or scroll to a block), give the loop `client_navigate` in its `capabilities`; its `entry` may name the tools, `page_write`, `page_filter`, `page_refresh`, `page_focus` and `page_prefill`. `page_filter` narrows a table by a field's value, by a number range on a field that holds numbers (`at_least`, `at_most`), or by both on different fields, and the table says what it shows ("Showing 2 of 3 records where price is at most 55"). Nothing it does changes a record, and another reader of the page sees it unchanged. After each reply, the page reads its blocks again, so a table shows a record the chat just saved without a reload. The console's preview says where the chat will show. | | `{{form waitlist fields=[email, company]}}` | A form that adds one record to the collection, with one input per listed field, checked against the field's declared type. A reader may use it only if the page's `collections` entry names them in `write`; an anonymous visitor also within the page's per-address limit and its monthly cap. A form only adds: it never changes a saved record. After a save, the page's blocks that show the collection update. Add `email=owners` or `email=
` to email someone at each save: see [Email someone when a form saves](#email-someone-when-a-form-saves). The console's preview shows the form and does not save. | | `{{user name}}`, `{{user email}}` | The reader's own name or email address, inside your words: `Hi {{user name else=there}}, welcome back.` Each reader sees only their own, filled in when they open the page. A member or admin reads the name and address on their account; an invited reader reads the address they signed in with, and has no name; a signed-in user of your site reads what your page's claims carry. A reader with none reads the `else=` words (`else=there`, or `else=[my friend]` for more than one word), or nothing. Write `{{user name}}` with a space: `{{user.name}}` is refused at the save. The value is shown to the reader only and is never sent to a loop. | | `{{scratchpad answer}}` | Nothing, until a `{{loop}}` block's chat writes into it for its reader: the loop's answer laid out on the page, at most 4,000 characters, until the reader leaves. | A `collection` block takes the keys below, and a `record` block takes `fields=`: | Key | What it does | |---|---| | `fields=[number, status]` | The columns to show, in this order. Without it, the block shows every declared field. Each column is headed by its field in words: `pickup_date` reads "Pickup date". More fields are filled in by pio on every row: `@created_at`, headed **Added**, is the day the row was added; `@created_by`, headed **Added by**, is who added it; `@changed_at`, headed **Changed**, is the day the row was last changed; `@changed_by`, headed **Changed by**, is who changed it last. See [Who added a row](#who-added-a-row). | | `limit=20` | The most rows to show, from 1 to 100. The default is 100. When more records match, the table says "Showing the first 20 rows. More match." | | `view=list` | How the rows are laid out. `view=table` is the default. `view=list` shows each record as one line: its first field, then the others in a quieter line, each with its name ("Status: open"). `view=cards` shows each record as a card that lists its fields by name, in a grid that fits as many cards across as the screen has room for. Every view takes the same `fields=`, `limit=`, `where=` and `sort=`, and works with scripts off. | | `view=board group=status` | A board: a column for each value of `status`, in the order the collection declares them; a column for each value a row holds that the field no longer lists, such as **blocked**, said as *Not one of the Status values*; and a column **(none)** for rows with no value. `group=` must name a field with declared choices, or the save refuses it and names the fields that have them. Each row is a card; a button from `actions=`, such as `actions=[Done: status=done]`, moves its card to that column. The board needs `status` to place a card, so `fields=` may leave it out: the column already says it. On a phone the columns scroll sideways inside the board, never the page. | | `view=calendar by=due` | A calendar: each row on the day its date field `due` holds. It opens on this month, with today marked, and **Previous**, **Today** and **Next** step through the months; **Week** shows one week, each day with its rows and their buttons. A day lists three rows, then says how many more, and a click shows its week. On a phone each day shows how many rows it holds, and a tap shows its week. Rows in other months are counted below it ("Not shown: 2 rows earlier"), and rows with no date in `due` are listed under **No date**. `by=` must name a field of type `date`, or the save refuses it and names the date fields. When the page has a [row's own view](#a-rows-own-view), a row's first field opens it. With scripts off, the calendar is a list of the rows by day, earliest first. | | `for=row` | Only the rows that refer to the row a reader opens, on a collection with a `row` field. See [Comments on a row](#comments-on-a-row). | | `where=status:open` | Only the records whose field equals the value. To name more than one field, write a list: `where=[status:open, priority:high]`, and a record must match each one. The value is read as the field's declared type, so `where=seats:2` matches the number 2, and `where=done:true` matches a boolean. Equality only. `where=@mine` shows each reader only the rows they added; with conditions, write `where=[@mine, status:open]`. | | `sort=due_date` | The order of the rows, by one field: lowest first, or `sort=due_date:desc` for highest first. Numbers sort by size, and text and dates sort as text. A record without the field comes last. The block orders at most 500 records. When more match, it orders the 500 whose record ids sort last as text (a record's id is its key's value), and the others are not in the order, even one that would come first. The table then says "Sorted among 500 of the matching rows. Other matching rows are not in this order." Without `sort=`, the newest key comes first. `sort=@created_at:desc` puts the rows added last first, and `sort=@changed_at:desc` the rows changed last. | | `edit=[title, due]` | An Edit button on each row the reader may change, with a form of these fields filled with the row's values, and a pencil beside each of these values to change it in place. The key and a `generated` field cannot be edited. See [Let readers change and remove rows](#let-readers-change-and-remove-rows). | | `actions=[Done: status=done]` | A button on each row the reader may change, that sets one field to one value in one press: here **Done** sets `status` to `done`. List several: `actions=[Done: status=done, Reopen: status=open]`. A row whose field already holds a button's value does not show that button, so a done task offers no **Done**. The value must be of the field's type, and one of the field's fixed values when it has them. A button can also run a loop on the row instead: `actions=[Draft a reply: run draft_reply]`. See [Buttons that run a loop](#buttons-that-run-a-loop). | | `filter=[status, title]` | Fields the reader may filter by. A field with [fixed values](/docs/guide/collections-and-outputs.md#fixed-values-for-a-field) shows each of them as a button, with **All** first, even a value no record holds yet. Another field with eight or fewer values among the block's records shows them as buttons the same way; any other field shows a search box, which keeps the records whose field contains the words, ignoring case. A filter only narrows what the block already shows: it never shows a record that `where=` or the reader's own-rows rule leaves out. | A table cell shows at most 160 characters of a value. Every value is shown as text, never as markup. The one exception is a file a reader uploaded: an image shows as a small picture and any other file as a link (see [Let readers upload a file](#let-readers-upload-a-file)). A reader can also sort a block and see more of it. A table's column header sorts by that column: lowest first, then highest first, then back to the block's own `sort=`. A list or cards show **Sort by** with each field. When a block has more records than its `limit=`, **Show more** adds the next ones below. These read the block's records again, and the order and the next rows cover at most the block's first 500 records, as `sort=` does. On the page's own address with scripts turned off, the buttons, the sort and the next rows are links (**Next rows** and **First rows** move between pages of the block), and a search box says it needs JavaScript. Each of those links can be shared: opened later, with scripts on or off, it shows the same sort, filter and rows. The second step checks each block against your account. A block that names a collection your account does not have, a `{{form}}` included, is refused with the collections you have: make the collection on the Collections screen, or save the draft of a loop that declares it, first. A field the collection does not declare, in `fields=`, `where=`, `sort=` or a form's `fields=`, is refused with the fields it has. A `where=` value that is not its field's type is refused, with an example of one that is. A `{{form}}` block that lists no fields is refused with the fields a person can fill in. A collection that only a pipeline step writes declares no fields, so its field names are not checked. A `where=` value is matched as written. `where=assignee:me` shows the records whose `assignee` is the text "me", not the person viewing the page. The save warns about a value like `me`, `self` or `@user`, names `where=@mine` as the way to show each reader their own rows, and the publish card shows each value in quotes. ### Who added a row pio remembers who added each row: the person whose page form or loop conversation saved it. A row a pipeline or a seed added has nobody, and so does a row sent through a page's form by a visitor the page does not know. - `where=@mine` keeps a block to the rows the reader added. It matches by who added the row, never by a field, so a field that names a person does not change it, and a reader's filter can only narrow it. A reader the page does not know, such as an anonymous visitor, sees no rows and the line "This shows each person only the rows they added, and this page does not know who you are." - `@created_by` shows **You** on the reader's own rows. On another member's row it shows the name that member gave, and **Someone** when they gave none, or for anyone outside your team. It never shows an email address. A row nobody added shows a dash, "—". - `@created_at` shows the day, in UTC, like "19 Oct 2026". A reader can sort by it, not by `@created_by`. - `@changed_at` shows the day the row was last changed, in the same way, and a reader can sort by it too. - `@changed_by` shows who changed the row last, in the words of `@created_by`: **You**, a member's name, or **Someone**, and never an email address. A change through the page or by a loop working for a person names that person. A row a pipeline or a seed wrote last shows a dash, "—". A reader cannot sort by it. - `edit=`, `actions=`, `filter=` and a `where=` field cannot name any of them: pio fills them in, so the save refuses them, and a form never asks for them. ### A row's own view Add `{{record tasks from=row fields=[title, status, due]}}` to a page that has a `{{collection tasks}}` block. Each row's first value in that block becomes a link, and the link shows that row in the `from=row` block, at the same address, with a **Close** link. The address carries the row, so the link can be shared, and it works with scripts off. Until a reader opens a row, the block shows nothing. - It shows only a row the reader may read: the page's `read`, the collection's `rows:` and each reader's own rows hold, as for every block. A row they may not read, or one that was removed, shows "That row is not on this page any more." - It takes `fields=`, and `edit=` and `actions=` as a table does: Edit, the buttons and Delete show on the row for a reader the page lets change or remove it. - A page shows a collection's opened row in one place, and a `from=row` block needs a `{{collection}}` block of the same collection. The save refuses a page that breaks either rule. - The **Tasks** starter opens a task this way, above its board. ### Comments on a row A collection whose `row` field refers to the rows of another (see [A field that refers to a row](/docs/guide/collections-and-outputs.md#a-field-that-refers-to-a-row)) shows under the row a reader opens. For comments on a task, make a `task_comments` collection with a field `task` of type `row`, a row of `tasks`, and a `text` field. Then add, below `{{record tasks from=row}}`: ``` {{collection task_comments for=row fields=[text, @created_by, @created_at] view=list sort=@created_at}} {{form task_comments fields=[text] for=row}} ``` - `for=row` shows only the comments on the row the reader opened. Until they open one, both blocks show nothing. With `view=list`, each comment leads its line, and **Added by** says "You", the commenter's name or "Someone". - The form saves each comment under that row. The reader never types the row: pio fills it in. - A reader sees a comment only if the page lets them read the comments and the row it is on. A row they may not read shows no comments, and its form saves nothing. - A collection with a `row` field shows on a page only so: any other block over it, without `for=row`, is refused at the save and names `for=row`. To read every comment, open the collection on **Collections**. - When a row is removed, its comments stay in the collection and show on no page, because no reader can open that row any more. ### Link to another page Write `[Orders](page:orders)`, with the other page's `page_id`. Each reader gets the address that serves them: in the console, the page's console address; on the public address, the other page's public address. Where the reader cannot open that page (it is not published, its readers do not name them, or on the public address it has no public address), the words show without a link. A page on your site through the embed shows the words without a link. The save refuses a `page_id` your account has no page of, and names the pages it has. ## Preview as a reader The preview shows the page as one reader sees it. **Read as** offers the page's own readers, for example **an anonymous visitor** on a page for visitors, and opens on the widest of them: anonymous visitors, then verified users, members and admins. A block whose collection does not grant that reader shows why in its place, and names the fix: add the reader to that collection's `read`. The rest of the page still shows. A block that cannot show for any other reason also says why in its place: a record id the collection does not hold, or a collection no loop writes any more. A form only some of the page's readers may use is a choice, not a mistake. When the collection's `write` names another reader of the page, the preview says so in its place, for example "only admin may use this form, so member readers see no form here", and names no fix. The People and Questions and answers starters are this case: their forms are for admins. When `write` names none of the page's readers, the preview names the fix: add the reader to that collection's `write`. A block that has nothing to show yet, such as a table whose collection has no records or a scratchpad nothing has written in, takes no space on the published page. The preview still draws it, so a page that is mostly empty for now does not look unrendered: an empty table shows its column headings and "Collection tasks: no records yet. Readers see nothing here until the first.", and a scratchpad says it has nothing written yet. A `{{loop}}` block shows as a frame of the chat's size with the loop's name, because the chat runs only on your site. The card that asks you to approve a page a loop proposes shows the page the same way. ## Publish Press **Publish…**. The publish card, "Publish Tasks?", says who can open the page and who can change its rows, in one or two sentences, before anything is published. Under **Show the full definition** it shows what the server read from your draft: - who may read the page, - each collection it may read, who reads it, who writes it, and who may change or remove its rows from the page (any row, or only the rows they added), - one sentence for each block: what it shows, and for whom, and what its rows let a reader do: its Edit form's fields, each button and the change it makes, and Delete, for example "Member and admin may change any row here: Edit (`title`, `due`); Done sets `status` to "done".", - what it warns about but does not refuse: an embedded loop with nothing published, whose chat shows nothing yet; one that cannot change the page because its `capabilities` omit `client_navigate`; and a loop listed under `loops` that no `{{loop}}` block embeds, which the page may open but never shows. Add the block, or remove the loop from `loops`. - a grant or an address the page's readers cannot use: a collection that lets readers the page does not have add, change or remove rows, a public address on a page whose readers include neither anonymous visitors nor invited readers, or `embed` on a page whose readers include neither anonymous visitors nor your signed-in users. Each warning names the fix: remove the grant or the address, or add the reader. The fold also shows the document itself. When the draft changes a published page, the card asks "Publish the change to Tasks?" and leads with what changes against what people see now, as [a change from LoopAssistant](#change-a-page-with-loopassistant) does; the rest is under **Show everything else**. Press **Publish Tasks**, or **Publish the change**, to publish. Publishing approves the document as it stands, and the published record is what readers see. A published version is never written again. If the draft is saved again while the card is open, the publish is refused: review it again. ## Open a published page Once a version is published, the page's screen shows **Open in console**. It opens the page in a new tab at its console address, `app.plutonium.io/p/`: the published version, live, as you, never the draft. The page fills the screen as its readers use it, under one **Edit page** link back to its screen on Pages. Its loops run and its forms save, as they do on your site, so an internal page is usable here. It opens as you when the page names your reader: a member as a member, the account's owner as an admin. A page whose readers do not include you says so and links to its preview. A chat you start there is yours: it counts toward the loop's per-person month for you, as for any person, and the loop's month and the wallet pay. **Preview as its readers** opens `app.plutonium.io/pages//preview`: the same live page, with **View as** in the bar above it. Choose yourself, or **An anonymous visitor** when the page takes them: the page as a new visitor meets it, with its loops running and its forms saving. You are a new anonymous visitor each time you choose it, and a chat counts as your preview, not as a stranger's. A page whose readers are only signed-in users of your site cannot be opened as one there; the editor's preview, with **Read as**, shows any reader, and it is also the only place a draft is previewed. Only members and admins of the page's own account can open either address. Signed out, it asks you to sign in and then shows the page. A page id your account does not hold reads "That page does not exist.", and a page not yet published says so and links back to its editor. When the page can be read at its public address (see below), the screen also shows **Open public page** and **Copy public address**. When it cannot, the screen says in one line what the published version lacks. ## Pages on Home Home lists your published pages, so the ones you use most are a click away. Each row says who may read the page, with **Open** and **Copy link**, which copies its public address when it has one. **Open** goes to the address that serves you: the console address when the page's readers include you, else its public address in a new tab. A page that neither address serves has no **Open**, and its row says what the page lacks. With no page pinned, Home lists the five newest published pages. To choose them yourself, open a published page on **Pages** and press **Pin to Home**: Home then lists only the pinned pages, in the order you pinned them, at the top of the screen. **Unpin from Home** takes one off; when the last one goes, Home lists the newest again. A pin stays when you publish a new version, and goes when you delete the page. A page that was never published cannot be pinned, because Home would have nothing to open. ## Put a page on your site A page reaches readers outside the console when its document says who they are and where the page may be framed: ```yaml access: readers: [anonymous] identity: {kind: anonymous, limits: {per_ip: 30/1m}} delivery: kinds: [embed] origins: [https://shop.example] ``` Publish it. The page's screen then shows **Put this page on your site**: an ` ``` The same snippet works on every site the loop declares. Keep all five `sandbox` flags: `allow-scripts` runs the chat, `allow-forms` lets the visitor send, and `allow-same-origin` lets the frame load its own code. `allow-popups` lets a search result or a link in an answer open in its own tab, and `allow-popups-to-escape-sandbox` lets that page work normally there. Without them, a click on a link does nothing. The snippet does not grant `allow-top-navigation`, so the frame cannot move your page to another address. The frame stays on plutonium.io, a different origin from your site, so it reaches nothing on your page: not its content, its cookies or its storage. The tab shows the snippet only for a published loop that declares `embed` and at least one site. ### A search box If the loop uses a search index, the loop's **On your site** tab asks **What the frame shows**: **The chat**; **The chat, with a search box over what this loop searches**, whose snippet address ends in `&search=1` and whose frame shows a search box above the chat; or **Search only, with no chat**, whose address ends in `&search=only` and whose frame shows the search box alone. Choose before you copy. A visitor's search never reaches a collection index; see [Letting a Loop Search](/docs/guide/search-indexes.md#let-your-visitors-search). ### Your own accent colour Under **Accent colour**, pick the colour of the frame's buttons and links, for this snippet only. Leave it empty for the platform's. The colour must read in both the light and the dark theme: at least 3:1 against the page in each, with white or dark text that reads on it at 4.5:1. A colour that fails is refused in words, and the code keeps the platform's colour. A colour that passes is added to the address as `&accent=%23…`, and the frame works out the shade it uses for links. The frame checks the colour again when it loads, so an address edited by hand to a colour that fails shows the platform's colour; your browser's console says why. ### Light or dark By default the frame follows each visitor's own light or dark setting, so a visitor whose device is set to dark sees a dark chat on any site. If your site is always light or always dark, choose **Always light** or **Always dark** under **Light or dark**. The choice is added to the address as `&theme=light` or `&theme=dark`, and the frame keeps that theme for every visitor. ## 3. Decide who the visitor is The loop's `identity` decides whether the chat knows who your visitor is. ### Anonymous visitors With `identity.kind: anonymous`, each browser gets its own identity and nobody is asked to sign in. The snippet alone is enough. ### Users your site signs in With `identity.kind: signed_assertion`, your server vouches for the user. The frame asks your page for an **assertion**, and your page answers. The tab shows the listener to paste beside the snippet: ```html ``` `mintAssertion` is yours: it asks your own server to sign a JWT for the user with the loop's secret. Its `sub` becomes the user's id in every run. An owner finds the secret on the loop's **On your site** tab, under **For a server of yours: keys and secrets**, then **Signing secret**, once the loop is published: press **Show the secret**, then **Copy the secret**. Keep it on your server: anyone who holds it can sign in as any of your visitors. [Identity and Keys](/docs/guide/identity-and-keys.md) says how to rotate it. Mint a new assertion each time the frame asks, because each one can be used only once and the frame asks again when it needs another. [Identity](/docs/api/identity.md) in the API reference describes the assertion. ## 4. Let the loop act on your page A loop can declare **client tools**: actions that your own page performs for the user, such as opening a page of your app or turning on a setting. When the loop declares any, the tab shows a second listener with one empty handler per tool. Fill in each handler: - A handler runs with the signed-in user's own authority on your site. Check what it does exactly as if the user had clicked. - What a handler returns, the loop reads as untrusted. - A tool your page has no handler for, or a handler that throws, tells the loop that this page does not handle it. Before the loop **acts** on your page, the chat shows the user a card that describes the action and its details, and the user approves or declines. Each detail is labelled with its property's `title` in the tool's input schema, so give every property one the user can read; a property with no `title` is labelled with its name. A tool that only **moves** the page to another of your pages shows no card, unless the loop's record asks for one. If the user declines, the loop reads that as the answer and the conversation goes on. The user can also write a note on the card: it travels with **Decline**, or on its own with **Reply**, which answers neither way. The page is not asked to act, and the assistant reads the note and may ask again. ## Keep the chat on topic Every message a visitor sends starts a run that your budget pays for, and a chat with no limits answers anything it is asked. Declare `on_topic` in the loop's record to say which messages it is for: ```yaml on_topic: about: questions about booking a class at our studio - classes, times, prices, what to bring and getting here reply: I can only help with booking a class at our studio. refuses: true ``` `about` is one sentence that names everything the loop answers, and `reply` is what a visitor reads when their message is not. A question about something `about` leaves out reads as off topic, so name the whole scope: "booking a class" alone would leave out parking and prices. LoopAssistant writes both for every loop that a stranger can reach, and publish refuses either one when it is blank. The cards you approve a version on show both, under **What it talks about**. Visitors never read `about`: it is for the topic check below and for you on those cards, and the empty chat says only *Say something to start.* While the loop answers a message, the topic check reads the message and the last few turns of the conversation, and decides whether the message is within `about`. The check runs beside the answer, never before it, so it adds at most a moment before the first words. Short follow-ups such as "thanks" or "and then?" count as on topic. Each check's small cost is part of what the run spent. With `refuses: true`, a visitor whose message is off topic reads `reply` and never sees the loop's answer: the loop holds its first words until the check is done, shows `reply` the moment it is (the time under it counts to that moment), and runs none of the answer's actions. The run spends the check and that one answer's model call, and the visitor can type again. Their next message is checked on its own, and the loop answers it without turning back to the refused one. A refused visitor reads nothing but `reply`, so put a way to reach you in it, such as a phone number or an email address. **Without `refuses`, the check only records what it decided, and every message is still answered.** Start there to see what the check decides for your visitors' real messages, and turn `refuses` on when its decisions look right. If the check itself fails, the message is answered. ## What your visitor sees - The conversation, with formatted answers, and a short line such as "Thinking" or "Searching the docs" with three moving dots while the loop works. From the first second the line also shows how long the turn has taken: "Searching the docs · 4 s". - If the loop declares `chat: {show_activity: true}`, each step the loop takes, in words ("Searched the docs"), as it takes it; when the answer arrives, the steps fold into one line under it that the visitor can open. A loop that does not declare it shows none of this, because a step says what the loop does inside and that is your decision. A step is only ever a tool's own words (a custom tool's `working_label`), never the model's text: what the model writes is its answer. - Links in an answer, which open in a new tab. A link to another site shows that site's address beside it, so the visitor sees where it goes. A link with no web address, such as an uploaded file's name, shows as its words: nothing on the visitor's page could open it. - When the loop searched or read a web page, a **Sources** line under the answer, linking to each page the search found and each page the loop read with `web_fetch` (the address it ended at, after any redirect). A link the model wrote is kept only when it points to one of those pages; any other, including any link in a run that found no page, shows as its words alone, because a model can write an address that does not exist. To give a fixed link, such as a booking page, put it on your page or say it in words. - Answers that never say how the loop works: no tool, collection, page it fetches, update or schedule, and never that one has not run yet. A loop whose sources have not been read yet answers from the rest of its instructions, or says it does not know. Citing a page it read is allowed. - Any card the loop asks them to answer: a form, a choice, an email check or an approval of their own. It shows in the conversation, under the message that asked for it. The action the card asks for is the filled button; the other choice is outlined. The visitor can always refuse: **Don't send** on a card that asks for details they type, **Skip** on a card of choices. One line under the buttons says what each does, and one says who reads what they type. After the visitor sends a form, the conversation shows their turn as "Sent." A form of one or two details names them instead ("Sent: Work email"). It never shows what they typed. An approval your team decides, such as a refund, never reaches the visitor; it waits for your team in the console. - One box to write in. Enter sends; Shift+Enter starts a new line. While the loop works, a **Stop** button takes the place of **Send**, so a visitor can end a run that goes wrong. Enter still sends while the loop works: when the loop then waits for the visitor, what they sent is their answer, in the order they sent it, with nothing to send again. When the loop waits for the visitor's own answer, **Send** is back. **Send** is also back when a member of your team takes the conversation over and writes to the visitor, so the visitor can answer them. - **New conversation**, at all times once the visitor has said something. While the loop is still working or waiting for the visitor, it asks first, because it stops that run; the stopped run stays in Runs. When the job is done, the loop's own closing line and **New conversation** in place of the box to write in. - If the visitor reloads the page, the chat comes back as it was, in the same tab, with each answer's folded steps when the loop shows them. A visitor never sees how long an answer took. A new tab, or **New conversation**, starts fresh. - When the frame cannot hold the chat, for example because the snippet names no loop, the frame says why in its middle instead of showing an empty chat. Opened on its own, it says the chat lives on a website and to open that website. Nothing about cost, budgets, models or tools reaches the visitor. ## The React SDK A loop can also declare the `sdk` delivery, for a React application that you build and render yourself. The package, `embed-sdk-pio`, **is not published yet**, so there is no install line to give you. The tab says the same, and will carry the line when there is one. ## Never put a key in a page An API key (`rk_…`) is for your server. A key in a page can be read by anyone who opens it, and it spends your account's money. The embed and the SDK never carry a key: they get the visitor's own credential through the loop's public id. --- # Connect an AI tool > Use plutonium.io from an AI tool such as Claude Desktop — a remote MCP server you connect by signing in, and disconnect in Settings An AI tool that speaks **MCP** (the Model Context Protocol) can work in your plutonium.io account as you: list and run your loops, read what they did, answer their approvals, search, and draft, test and publish loops. You connect it by signing in, not by pasting a key. ## Connect Add this address to the tool as a **remote MCP server**: ``` https://mcp.plutonium.io/mcp ``` In **Claude Code**, that is one command: ``` claude mcp add --transport http plutonium https://mcp.plutonium.io/mcp ``` In **Cursor**, and in any tool that reads its servers from a JSON file: ```json { "mcpServers": { "plutonium": { "url": "https://mcp.plutonium.io/mcp" } } } ``` With [the command line](/docs/guide/command-line.md) installed, `rxr mcp add claude` and `rxr mcp add cursor` do these two for you. In **Claude Desktop** and other tools with a settings page, add a custom connector, or a remote MCP server, with the address above. The tool opens plutonium.io in your browser. Sign in, and a page asks whether to connect the tool, with what it could do. Press **Allow**, and the browser goes back to the tool, which is now connected. **Deny** connects nothing. The name on that page is the name the tool gave itself. plutonium.io has not checked it, so connect only a tool you started yourself. ## What it can do To build a loop: | Tool | What it does | | --- | --- | | `list_loops` | Lists your loops, with the published version and the draft of each. | | `get_loop_format` | Explains how a loop is written. It gives a starter loop that saves as it is, and a full example. | | `get_loop` | Reads one loop's document, so the tool can show it or change it. | | `draft_loop` | Saves a draft of a loop, checked as the console checks it. A refused draft lists each problem and where it is. | | `test_loop` | Runs the test cases a draft declares. | | `get_test_results` | Reads the verdict of each test case, and why a failed one failed. | | `publish_loop` | Publishes a draft. The version records that it came from this tool. | To run a loop: | Tool | What it does | | --- | --- | | `run_loop` | Starts a run of a published loop. With `draft`, it runs the draft, so you can try a loop before you publish it. | | `get_run` | Reads a run: its state, its reply, a question it asked you, any approval it waits on, whether the conversation is still open, and what it did. | | `list_runs` | Lists recent runs. | | `send_message` | Sends your next message to a run: your answer to its question, or a follow-up. | | `answer_approval` | Allows or declines a step a run waits on. | | `stop_run` | Stops a run. | | `search` | Searches your search indexes. | A run of a draft is yours alone: no visitor reaches a draft. It costs what any run costs. Three more tools are for a program on your own machine, not for a chat: | Tool | What it does | | --- | --- | | `list_host_calls` | Lists the tool calls that runs wait on a member's own machine for. | | `claim_host_call` | Takes one of them, so that one machine answers it. | | `answer_host_call` | Sends the machine's answer, once. | A loop can declare a tool that a member's own machine answers. The `rxr` program on that machine uses these three tools to answer it, and only for the tool names that a file on the machine maps to a command or a directory. An AI tool leaves them alone. Each test case is a run that costs money, so a tool should ask you before it calls `test_loop`. A case run acts on nothing live: a tool with outside effects answers the case's stub, and the records the run writes are removed. A draft that declares test cases publishes only after they pass on it. You can also run them in the console: open the loop on **Loops** and press **Publish the change…**. It acts as you, so it can do only what your role allows. A member whose role only reads cannot publish through it. It reaches plutonium.io only through this connection: it cannot start runs through a loop's own door. ## Prompts The server also offers two **prompts**: the steps for a job, in the right order, so you do not have to explain them. Most tools show a prompt as a slash command that takes its arguments. | Prompt | Arguments | What the tool then does | | --- | --- | --- | | `new_loop` | `purpose`, and optionally `loop_id` | Reads the format, drafts a loop for that purpose, runs the draft and shows you the reply. | | `change_loop` | `loop_id`, `change` | Reads the loop, makes the change as a draft, runs the draft and shows you the reply. | In Claude Code, for example: ``` /mcp__plutonium__new_loop "answer billing questions from our help pages" ``` Both prompts tell the tool to ask you before it runs test cases and before it publishes. A prompt gives the tool no new reach: each step is one of the tools above. ## See and disconnect **Settings** lists, under **Connected AI tools**, each tool you connected to this account: when you allowed it, when it last renewed its sign-in (a tool still in use does so within the hour), and when the connection ends unless the tool renews it. You see only your own connections; each member disconnects their own. Press **Disconnect** to revoke a connection. The tool's next call is refused, and it cannot renew the connection. To use it again, connect it again. ## From a terminal [The command line](/docs/guide/command-line.md), `rxr`, uses this same server with no AI tool: it signs in the same way, and each of its commands is one of the tools above. --- # The command line > rxr, the Reactor command line — write a loop in a file, try the draft, test it, publish it and run it from a terminal, as a person or as an AI agent `rxr` is Reactor from a terminal. You write a loop in a file, save it as a draft, try it, test it, publish it and run it, with no page open. An AI agent that works in a terminal can do the same: every command has an output made for a program. `rxr` works in your account as you, and only as far as your role allows. It reaches plutonium.io through the same server an AI tool connects to ([Connect an AI tool](/docs/guide/connect-an-ai-tool.md)), so the two can do the same things. ## Install ``` curl -fsSL https://plutonium.io/install.sh | sh ``` This puts one file, `rxr`, in `~/.local/bin`. It runs on macOS and Linux, on arm64 and x86-64, and it needs nothing else installed. The installer checks the download against a SHA-256 it carries, and installs nothing when they differ. Set `RXR_INSTALL_DIR` to install somewhere else. ## Sign in ``` rxr login ``` `rxr` opens plutonium.io in your browser. Sign in, and a page asks whether to connect `rxr`, with what it could do. Press **Allow**, and the terminal says it is connected. You paste no key. When the terminal is on another machine than your browser, run `rxr login --no-browser`: open the address it prints, press **Allow**, and paste the address the browser ends on. **Settings** lists the connection under **Connected AI tools**, as "rxr on" and the machine's name. **Disconnect** there ends it at once. `rxr logout` forgets the sign-in on one machine. ## Your first loop ``` rxr new support_desk rxr push support_desk.loop.yml rxr run support_desk "Where is my order?" --draft rxr publish support_desk rxr run support_desk "Where is my order?" ``` 1. `rxr new` writes `support_desk.loop.yml`, a small loop that saves as it is. Open the file and change its name, its description and its `entry`, the instruction the loop follows. [Building a Loop](/docs/guide/building-a-loop.md) explains every key. 2. `rxr push` saves the file as the loop's **draft**. A draft serves nobody. When the document has a problem, the answer names each one and where it is. 3. `rxr run --draft` runs the draft as you, and prints what the run does and then its reply. Change the file, push, and run again until it does what you want. 4. `rxr publish` makes the draft the version that runs use. It asks you first. `rxr chat support_desk --draft` is a conversation: each line you type is your next message. With no command at all, `rxr` lists your loops to choose from. To change a loop you have, `rxr pull support_desk` writes its document to a file, and says which version number the changed copy must carry. ## Start from a sentence ``` rxr new --describe "Answer questions about our return policy, from our help pages" ``` LoopAssistant, the assistant on the console, drafts the loop. It asks what it needs to know, one question at a time, and then shows what it proposes: the loop's name, what it may do, and the most one run may cost. When you say yes, `rxr` writes the draft to a file, as `rxr new` does. Nothing is saved before you say yes, and this command publishes nothing. The conversation with LoopAssistant is a run, and costs what a run costs. ## Work on a loop ``` rxr dev support_desk.loop.yml ``` `rxr dev` is one terminal for the whole edit loop. Edit the file in your own editor and save it. Then type a message in the terminal: `rxr` first saves the changed file as the draft, and then sends your message to that draft. You never run `push` by hand, and you never talk to an old draft by mistake. - When the file has a problem, `rxr` prints each one and where it is, and holds your message until a save succeeds. - A saved change starts the conversation over, because the loop is now a different one. - **Enter** alone saves. `/test` runs the test cases, `/publish` publishes, `/quit` leaves. ## Start a run when something happens on your machine `rxr run` can stay running and start a run for each event: ``` rxr run review "Review what changed." --on-change src rxr run digest "Write the digest." --every 30m ``` [Triggers and Schedules](/docs/guide/triggers-and-schedules.md) has the details, and the lines for cron, a git hook and a pipe. ## Test cases A loop document can declare test cases: example conversations that must pass before a version publishes ([Testing a Loop](/docs/guide/testing-a-loop.md)). ``` rxr test support_desk ``` This runs each case against the draft and prints a verdict for each, with the reason when one fails. Each case is a run that costs money, so `rxr` asks before it starts them. A case run acts on nothing live. ## Runs | Command | What it does | | --- | --- | | `rxr run ""` | Starts a run and follows it to its reply. `--draft` runs the draft. | | `rxr say ""` | Sends your next message to the same run. | | `rxr watch ` | Follows a run that is working. | | `rxr show --events` | Reads a run now, with each thing it did. | | `rxr approve ` | Allows a step the run waits for. `--decline` refuses it. | | `rxr stop ` | Asks a run to stop. | | `rxr runs` | Lists recent runs. | When a run asks you a question, `rxr` shows it, with its choices under numbers, and sends what you answer. When a run waits for your approval, `rxr` shows what it asks and waits for your yes or no. A run costs what any run costs, wherever it was started. ## For an AI agent An agent that drives `rxr` reads `rxr guide`: the whole of this page for a program, with the order of the commands and what each exit status means. - **`--json`** on any command prints one JSON document on standard output, and nothing else. - **No question is asked** when there is no terminal. A step that publishes, or that spends money on test cases, then needs `--yes`: the agent asks you, and passes it when you agree. - **A run's own question** comes back as `question`, with its `prompt` and `options`. The agent asks you, and sends your answer with `rxr say`. - **The exit status says what happened**, so a program need not read sentences: | Status | Meaning | | --- | --- | | 0 | Done. | | 1 | plutonium.io refused the request. The message says why, and names the fix. | | 2 | The command line is wrong, or `--yes` is missing. | | 3 | Not signed in. | | 4 | A run waits for an approval. | | 5 | A run ended without success, or a test case failed. | | 6 | plutonium.io could not be reached. | | 7 | The wait ran out and the run is still working. | ## Let a loop use this machine A loop can read a file or run a command on your own machine, and only what a file there allows: ``` rxr host init # writes rxr.host.yml, with every key explained rxr host check # says what each tool name would do; runs nothing rxr serve # answers the calls, and starts the file's triggers, until you stop it ``` `rxr run`, `rxr chat` and `rxr dev` answer the calls of the run they follow, when the directory holds an `rxr.host.yml`. [Tools on Your Own Machine](/docs/guide/your-machine.md) has the whole of it. ## Add the server to an AI tool An AI tool that speaks MCP needs no `rxr`: it connects to the same server ([Connect an AI tool](/docs/guide/connect-an-ai-tool.md)). `rxr` can add the server for you: ``` rxr mcp add claude rxr mcp add cursor ``` `rxr mcp add claude` runs Claude Code's own `claude mcp add`. `rxr mcp add cursor` writes the server into `.cursor/mcp.json` in this directory, and keeps every server the file lists. With `--global`, each adds it for all your projects. The tool then signs in itself, through the same page `rxr login` opens. `rxr mcp` alone prints the lines, to add it by hand to any other tool. --- # Tools on your own machine > Host tools — let a loop read a file or run a command on your own machine, through rxr, and only what a file on that machine allows 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`](/docs/guide/command-line.md), 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 ```yaml 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 `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](/docs/guide/permissions-and-trust.md). ## 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: ```yaml # 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: ` | Reads a file under the directory, or lists it. | `path` | | `write: ` | 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: ```yaml 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](/docs/guide/triggers-and-schedules.md#from-your-machine)). ## 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. --- # Operating Loops > Watch runs live, stop one, take over a conversation, answer the decisions a loop waits on, and read each loop's numbers After a loop is published, the **Operate** group of the console is where you watch it: **All runs** for each run as it happens, and **Metrics** for the same runs counted per loop. ## All runs **All runs** shows every run in the account as it happens, including the conversations each member started from **My conversations**: who it is for, how it reached the loop, what it has spent, and why it ended. Choose a run to read what it did: the conversation, each tool call, and what it wrote. Each answer is headed by the loop's name, and a run outside a loop by its agent's name, such as **Researcher**. A run you started yourself opens in **My conversations**, where you can carry it on. The **Started by** chips narrow the list: **Mine**, **Visitors**, **Your server** (through the API with a key), **Automatic** (a schedule, a webhook or a new record) and **Test cases** (a run of one of the loop's test cases, which names its case, such as **test case “a user submits repair request”**). A run says where it was reached in words, such as **on your site**, **on your site or app** or **through your server**, and the meter above the list reads **Runs still going: $0.12 spent of $5.00 allowed**. Turn on several to see all of them; with none on, the list shows every run. The address keeps your choice, so a link to the page opens with the same chips on. A run with no user, started by a schedule, a webhook or a new record, has no conversation. Its title names what started it and who it is for, such as **Webhook · L-ab0508**. What it did is in its outputs. A run that the platform closed says so in words: **Ran past its time limit**, **Failed on our side**, **Halted from outside**, or **Closed: no record of its run**. **Metrics** uses the same words under **How runs ended**. A loop with several agents shows each agent's work on its own row, with its own spend and its own ending. ### Stop a run Press **Stop** on a run. The turn in flight finishes, then the run ends as stopped and the user reads the loop's `stopped` message. If the run does not stop soon, the button offers **Stop again**. ## Take over a conversation You can speak to a user yourself, in place of the model. Choose the run and press **Take over this run**. The turn in flight finishes first, then your messages go to the user and the model is silent. Press **Hand back to the model** to give the conversation back. The model reads what you and the user said, in order, as your team's answer. It is told not to answer again a question you answered, and that where your words differ from the loop's instructions, yours win in that conversation, so it answers only what the user said after your last message. One member holds a run at a time. If another member holds it, the page names them; ask them to hand it back. ## Decisions a loop waits on A step that the loop's record gates on `operator` waits for a member of your account to decide. **Home** lists each one under **Needs you**, ahead of every other notice and the one to answer soonest first, with the time to answer by. **Decide** opens that run on **All runs**, or, for a decision on a run you started yourself, its conversation in **My conversations**, where its card is. On **All runs**, the **Needs you** chip shows only the runs that wait on a decision. Open one, read what the step would do, then press **Approve** or **Decline**. Answering there answers that run. Only decisions are counted: on **Home**, beside **My conversations** in the menu, and on **All runs**. A decision on a run of your own counts too. A conversation that waits for your next message reads **Your turn** on its row and is not counted, because it may be a question or a chat that has said all it needs to. To ask before you decide, write in **Note to the agent** and press **Reply**. A reply approves nothing and declines nothing: the step does not run, and the agent reads your note. It can ask the person in the conversation, then send the step back to you, changed if your note asked for a change. A note also travels with **Decline**, so the agent knows why. **Approve** sends no note. The card then reads *"You replied with a note"*, and the run's line *"You replied with a note about the step to save a record"*, never *"declined"*. Grant cards take a note and **Reply** the same way; a card about budget or turns does not. The card names the step in words: a built-in tool reads, for example, *"Allow this run to save a record?"*. A tool you added on **Tools** reads *"Approve this step?"*, and the card's **Tool** line shows the name you gave the tool. The card says why the step waits. *"This loop asks for approval before this step"* means the loop's record declares a gate on it. *"This tool is high risk"* means the tool always needs a person, whatever the role allows. A step can wait for both reasons, and the card then says both. If nobody decides before the gate's lifetime ends, the run that waits ends with the loop's `lapsed` message, and the action never happens. A visitor never waits for your decision: their conversation has already ended with the loop's closing line. Only the approver a step names can decide it, on every surface, the API and **Connect an AI tool** included. A `user` step is the run's user's own card: a member answers it only on a run they started for themselves, and otherwise takes over the run to act for that user. An `external` step waits on the outside service the run called, and only that service's signed callback answers it. A member who tries either gets a refusal that says who answers. A question the run asks in words is its user's in the same way. A message sent to the run answers the question only from the run's own user. Another member's message is refused; to answer for the user, take over the run. A message to a run that waits on no question is kept for its next turn, from any member. Publish refuses an approval that nobody can give: every tool that needs approval must name who approves it. ## Metrics **Metrics** shows how each loop is doing: its runs, how they ended, what they cost, and how long people waited. Choose **Last 7 days** or **Last 30 days**. A loop opens on **All versions**: every version that ran in the window, summed, with a line such as "38 runs started in the last 7 days, on versions 9 to 15". Publishing a new version therefore never makes a loop look empty while earlier versions ran. Choose one version under **Version** to see it alone, for example to compare a new version with the one before it. Each version in that list shows how many runs started on it. **Checks that refused** counts each check by its name, on the versions that declare it, and across versions it names them. Only runs started through the loop's chat, page or API are counted, not your own chats or test cases. The numbers are counted as runs happen, so nothing from before counting began is included; **More** under the numbers says when counting began. Times, turns and spend per run are read from fixed ranges, so each says "up to" the top of its range: "half up to 2 s · 95 in 100 up to 8 s". **Time to the first answer** runs from a run's start to the first words its agent showed a person; time the person then takes to answer a card is not in it, and a run whose agent showed no words has none. **Tool calls that failed** names each tool as the loop's card does. **Sent (emails and webhooks)** counts what was **sent**, what failed, and each email that was **not sent** because its recipient is not verified, as **Loops** counts them. **Sent** means the receiver took it: a webhook answered `2xx`, or our mail service accepted the email. An accepted email can still bounce later, and it then moves from sent to failed. Press **Pages** above the list to see how each published page is used: - **Views**: the visits from readers outside your account. Sorting, filtering or refreshing the page adds none. - **Readers turned away**: the readers the page's door refused, and why. A reader is counted only where the page was found, so this number is *at least* what it says. - **Rows readers added, changed and removed** through the page's forms and rows. - **Runs started from row buttons**: presses of a button that runs a loop on its row. - **Page actions answered**: what the page did for a loop's chat on it, such as filtering a block, and how many of those failed. Your own looks at a page from the console, and your previews, are not counted. ## Deliveries On **Loops**, each webhook or email output of a loop says how its deliveries are doing: how many failed, how many are waiting or retrying, when the last one arrived, and the last error. An email that bounced says to correct the address. A failed delivery never changes how the run ended. --- # Money, Limits and Members > The prepaid wallet and the four budgets every run is held to, the limits on who may start runs, and the people in your account ## The wallet Your account pays for runs from a prepaid **wallet**. Nothing runs until the wallet holds money: each model call a run makes is reserved against it before the call is made. A model reply costs its tokens plus a fixed amount per model call. A tool call that runs on our servers, a loop's own tool or a read of a web page, costs the compute it used, measured on each call. A call that costs less than a millionth of a dollar is added to the run's running total, not dropped, so a run's tool calls cost what they used together. It counts toward the run's budget and the loop's caps at once, and it is taken from the wallet with the run's next model call, or when the run ends. Under **By run** on **Wallet & budgets**, each run lists what it spent on each model, and the fixed amounts per model call, the live streaming and the tool calls on lines of their own. What each model and each search, document and page costs is on [Pricing](/pricing.md). A request your server makes to read records under an API key is charged after it is served: once an hour, all of one key's requests from the hour before are taken from the wallet in one charge. If the wallet cannot cover that charge, it is taken once the wallet holds enough. Adding money by card opens soon. Until then, we add credit to your account. **Wallet & budgets** shows the wallet and, for each loop, what it has spent this month, what is held for calls not yet settled, and its monthly cap, and what each user has spent against the per-user cap. Loops are listed by what they spent, most first, and the first ten show; **Show all** lists the rest. Under each loop the three users who spent most show, then one line saying how many more there are and what they spent together, with **Show all** to list them. A member of your account is named. A signed-in visitor is named too when your site's id for them is one of your members, and reads as "a signed-in visitor" when it is not. Any other user is named by kind and id: a signed-out visitor by the end of the id the platform gave them, and an API user by the id your server sent. The wallet's balances are shown to the cent, rounded down, and what was spent to four decimals, so the lines add up to the total. A loop that is no longer in your library reads **A removed loop**, and an archived one keeps its name with **(archived)**. ## Plans Your account is on one of two plans. Both prices for everything are on [Pricing](/pricing.md). - **Pay as you go** has no monthly fee. A new account starts here. - **Pro** costs a fee each month and lowers every price. The fee is taken from the wallet when you subscribe and again at each renewal. The **Plan** card on **Wallet & budgets** shows your plan and, on Pro, when it renews. Only an owner of the account can change it. **Subscribe to Pro** first asks you to confirm, naming the fee and the day Pro renews; **Subscribe** then takes the first fee. If the wallet holds less than the fee, nothing is taken, and the card says how to add credit while card top-ups are not open. **Cancel Pro** keeps Pro until the end of the month already paid, and that fee is not refunded; until then, **Keep Pro** undoes the cancel without a new fee. If the wallet cannot cover a renewal, the account goes back to pay as you go, and the card says why. ## Four budgets Every run is held to four limits, set in the loop's record and checked before every call: | Budget | Where you set it | |---|---| | The account's **wallet** | The money you add. | | A **monthly cap** for the loop | `budgets.monthly_micros` | | A **cap per user** | `budgets.per_user_micros` | | A **budget per run** | `budgets.per_run_micros` | A search the run makes is held to the same four, so it never takes the run past its budget: when the budget has too little left, the search runs by words alone, or does not run. When a run asks you for more budget and you approve a top-up, the run's budget includes that amount from then on, and the run's page shows the new figure, so a run you funded never reads as over its budget. Amounts are in millionths of a US dollar, so `50000` is five cents. A run's budget must not be more than the per-user cap, and the per-user cap must not be more than the monthly cap: publish refuses a record that breaks the order and names it. ### Give one person more, without a publish An **override** replaces one cap for one person, or for the whole account, on one loop or on every loop. It applies every month until you remove it, a new version of the loop keeps it, and it holds no money: the wallet still pays and still binds. Only an owner sets or removes one, through `PUT` and `DELETE` on `/api/billing/budget-overrides`; any member can list them with `GET`. ```json {"loop_id": "assistant", "subject": "member:", "level": "per_user", "micros": 2000000} ``` - `level` is `per_run` (one run's budget, set when the run starts), `per_user` (one person's month on the loop) or `monthly` (the loop's month across everyone, so it takes no `subject`). Leave out `loop_id` for every loop, and `subject` for the whole account. A `per_run` override applies to runs started from the console, the run API, a webhook or a batch; a test case runs at the loop's own values, and so does a run a new record starts. A scheduled run takes its budget from the automation that wakes it, so give it more with a `per_wake` override on that automation. - `subject` is the person as a run names them: `member:` for someone in your account, `visitor:` or `signed_assertion:` for a person on your site. - The most specific override wins: this person on this loop, then this person on every loop, then the account on this loop, then the account on every loop, then the loop's own value. Every other cap still binds. - An override that would put the per-user cap above the monthly cap is refused, and the refusal names the level to raise too. An automation that wakes runs, such as a loop's schedule, declares two caps on its `wake_agent` step: `budget_micros` for each run it wakes and `daily_cap_micros` for what its wakes may be given in one UTC day. An override replaces either one on that automation, without approving it again: ```json {"claim": "loop_job_hunt", "level": "daily_cap", "micros": 5000000} ``` - `level` is `per_wake` or `daily_cap`, and `claim` names the **pipeline** whose step wakes the runs; a loop's schedule wakes them from the pipeline `loop_`. Naming the schedule is refused, and the refusal names the pipeline to use instead. It takes no `loop_id` and no `subject`: the runs it wakes are the account's. - An override that would put `per_wake` above `daily_cap` is refused, naming the level to change too. - When the daily cap stops a wake, the automation's run row names the override that set the cap. - Remove one with `DELETE` and `?level=&claim=`. In the console, **Wallet & budgets** lists every override under **Spending limits you set**: the amount, for whom, on which loop or automation, which cap it replaces, and who set it and when. A loop's schedule trigger is two automations, named by the loop: *"Job hunt's schedule"* says when it fires and is its one row on **Schedules**, and *"Job hunt's scheduled run"* wakes the runs and carries their caps, so it is the one you cap here. Any member can read the list. An owner presses **Add an override** and picks what it caps: - **A loop**: the loop (or every loop), the cap, and the person (or everyone on the account). - **An automation**: one of the automations that wake runs, and **each run it wakes** or **its day of wakes**. The form shows what the automation itself declares for both. Then the owner sets the amount; **Remove** takes one away. When the API refuses one because the caps would be out of order, the form says so in the same words and in dollars, for example *"Each run it wakes would be $5.00 on Job hunt's scheduled run, more than its day of wakes ($2.00). Raise its day of wakes too."* An automation's caps also have the platform's limit: at most $10 for each run it wakes and $100 for its day of wakes, and the form says that in dollars too. Any other refusal shows as the API wrote it. A run that its daily cap stopped says so on **Schedules**, and an owner sees **Give this automation more** beside it. It opens **Wallet & budgets** with **Spending limits you set** first and the automation and its day of wakes filled in; for a schedule, that is the scheduled run it fires. A run that stopped on a cap says on **All runs** which cap stopped it, in dollars: for example *"this person's month on the loop has $0.0007 left and the call needs $0.0021"*. It also offers the way past it there: **Give this person more** where the person's own month stopped them, or **Give this loop more** where the loop's month did. It opens **Wallet & budgets** with **Spending limits you set** first and the loop, the person and the cap filled in. The person who was stopped never sees it. **A scheduled automation and an email delivery are paid from the wallet alone.** Each firing of an automation costs a fixed amount and is held before it runs: if the wallet cannot cover it, the run stops before any step, and its row on **Schedules** says the wallet could not cover it. Each email a loop sends costs a fixed amount too, held before it is sent. An email the wallet cannot cover is not sent, and it is tried again for about three hours, so adding money in that time sends it. An email the mail service refuses is not charged. Neither counts toward a loop's monthly cap or a per-user cap. **Wallet & budgets** shows what a loop's emails cost this month on their own line under the loop, with the loop's total for the month, and never in the spend shown beside its cap. A webhook delivery costs nothing. A sign-in code a page emails to the people it invites costs what an email costs, but it is charged after it is sent and never held, so nobody is kept from signing in by an empty wallet; your daily email quota bounds it (see [Open a page to the people you invite](/docs/guide/pages.md#open-a-page-to-the-people-you-invite)). **A test case counts toward the wallet, the loop's monthly cap and its own run budget, never toward a per-user cap.** It is you checking a version before you publish it, not a user of the loop, so publishing a version with several test cases does not use up your own per-user cap. A run that meets a limit still starts, then ends with the ending `over_budget` and the message you wrote for it. Your server reads that ending; there is no payment error code. **Your users never see a budget, a price or a model**, only the conversation. When the budget for one run stops an answer partway, the user reads the part already written ending in "…", then your message. ## The last line of every run `end_messages` in the record holds the user's last line for each way a run can end: `completed`, `over_budget`, `lapsed`, `check_failed`, `stopped`, and `otherwise` for every ending you did not name. `otherwise` is required, so a person never meets an ending as silence. The platform never writes a closing line for you. When the run's last reply already said those exact words, the person reads them once, not twice. When the reply that ends the run says nothing, your `completed` line is that reply: the person reads it as the conversation's last message, in the console as in the chat on your site. **After a save that a form filled, the person reads your `completed` line.** The model never sees what the user typed on a form, so it cannot know what the record holds. The first reply after such a save shows your `completed` line in place of the model's words, whether or not that reply ends the run. The run's record keeps the model's words, marked as not shown. Write `completed` as what the user should read once their details are saved, such as "Thanks, your booking request is saved." Every other reply keeps the model's own words. A run whose same step keeps failing in the same way stops rather than keep paying. With one of your users in the chat, it ends at once with your `otherwise` line, because nobody from your account is there to decide; in your own run on the console it asks you first whether it may try again. ## Limits on who may start runs Each loop's `identity.limits` bound the people who reach it: - `per_ip` — run starts, new-visitor sign-ins and searches from one network address in a window, for example `30/1m`. They share one count, so a new visitor's first conversation spends two: `per_ip: 10/1h` lets about five new visitors start one conversation each from one address in an hour. - `per_subject_runs` — runs by one user in a window, for example `5/1d`. - `concurrent_runs` — optional: how many runs started through the run API may be running or waiting at once. When one of these refuses, your user reads when to come back in words, for example *"You have started as many conversations here as are allowed for now. You can try again in about 4 hours."* The answer is a `429`, and its `Retry-After` header carries the exact seconds for programs. Each route of the API also has its own rate limit. A refused request answers `429` with a sentence that names the limit, and a `Retry-After` header with the seconds to wait. ## Members **Members** lists the people who can sign in to the account, and the role each holds. Above the list it says what each role may do in one line, and **More** opens the full list of what only an owner may do. A member signs in with Google; your users never have an account here. An owner also sees each member's sign-in address under their name, so two people with the same name, or with none, can be told apart; a member with no name is listed by that address. A member sees names, and each owner's address, because an owner is who they ask; someone with no name reads as *"an owner"*, *"a member"* or *"a viewer"*. Where a member meets something only an owner may do, the console says so and names the owner to ask, with their address: *"Only an owner of this account can add money to the wallet. Ask its owner, Sam Lee (sam@example.com), to do it, or to make you one."* | Role | What it may do | |---|---| | **Owner** | Everything a member does, and also: adding money and subscribing to or cancelling the Pro plan; budget overrides; the API keys, a loop's keys, the search keys and the secrets that sign visitors in and sign webhooks; archiving and reopening a loop; pinning a page to Home and deleting a page; roles; the audit log; how search results are ordered, moving the search indexes to a new search model, marking a search index trusted or untrusted and its monthly cap; custom services to connect; adding a record by hand; invitations; and changing a member's role or removing a member. The **More** line on **Members** lists the same. | | **Member** | Build, test and publish loops, operate runs, and decide the steps that wait on the account. | | **Viewer** | Open the account's published pages that members may read, from Home, and use their forms and chats. Nothing else: no loops, runs, wallet, keys, members, page editor, Chat or Assistant; the console shows a viewer Home and the pages. On a page a viewer reads as a member and spends under the page's per-user caps. | A viewer is for someone in your organisation who uses your pages but builds nothing. A viewer signs in with Google like any member. An owner invites someone: enter their email address and a role, and press **Send invitation**. The email names who sent it, the account it is for, and what the role may do. They open the link in the email and sign in with Google as that address to join. A link that was already used, has expired or was withdrawn, or a sign-in as another Google address, opens the login page with a line that says so. An owner can make a member an owner, a viewer or a member again, and remove a member; a member or an owner can leave. Once they join, their Home names the account and their role, as in *"You are a member of Acme."* **Getting started** and **Your loop is live** are an owner's, so a member or a viewer does not see them. The account always keeps at least one owner. A role change applies to the person's next request, with one exception: a page they already had open keeps working for up to 12 hours, and a live view for up to 15 minutes. Owners also see the account's **Audit log**, a tab of **Members**: the changes members made, newest first, and who made each one. Opening the Assistant panel is not a change, so it is not in the log. --- # Search Indexes > Search indexes over your website, your files or a collection, searched by you, your loops, your visitors and your servers **Reactor search** makes your content searchable: a website, files you upload, or the records of one of your collections. It is a product of its own. You can use it with no loop, and a loop can use it too. Every search reads one or more **search indexes**. You create an index once, on the account, on the **Indexes** page. Then four kinds of searcher can search it: - **You**, on the console's **Indexes** page. See [Search your indexes yourself](#search-your-indexes-yourself). - **Your loops.** A loop names the indexes its runs may search. See [Letting a Loop Search](/docs/guide/search-indexes.md). - **Your visitors**, through a published loop's search box or its search API. See [Let your visitors search](/docs/guide/search-indexes.md#let-your-visitors-search). - **Your servers**, with a search key and no loop. See [Search from your server](#search-from-your-server). How to write a search is on [Writing a Search](/docs/search/writing-a-search.md): words, an exact phrase, words with a typo, a pattern, and words or meaning. ## Create an index On **Indexes**, press **New index** and choose what it is **built from**. That choice never changes. | Built from | What it holds | |---|---| | **A site crawl** | The pages of one website, fetched again daily or weekly | | **Files you upload** | Markdown, text and HTML files, and PDFs that have a text layer | | **A collection's records** | The fields you choose from one of your collections, kept up to date as runs write and delete records | Every index has a **name** for people, such as "Product documentation", and an **id** that a loop uses to name it, such as `docs`. The id is a lower-case letter, then lower-case letters, digits or underscores. The form fills in the id from the name, for example `shop_hours` from "Shop hours", until you type your own. A new index is **untrusted**: what it finds counts as outside text, which limits what a loop that searches it may also do (the [Rule of Two](/docs/guide/permissions-and-trust.md#the-rule-of-two)). An **owner** of the account can mark it trusted on its page, with **Mark trusted…**, once it exists; a member sees the mark and cannot change it. Mark an index trusted only for content you control. Trust also changes what a loop that searches the index may do; see [What an index lets a loop do](/docs/guide/search-indexes.md#what-an-index-lets-a-loop-do). One choice applies to every kind: - **Search by meaning as well as by words.** On by default. With it on, the index finds a passage that says the same thing in other words, as well as the exact words. ### A site crawl Give the crawl an **address**, such as `https://docs.example.com/guide/`. The crawl reads that host under that path, and nothing outside it. It reads the site's `robots.txt` and sitemap and follows the links it finds inside that scope. Choose how often it fetches the site again, **daily** or **weekly**, and **at most how many pages** it stores: 2,000 by default, and at most 10,000. The first crawl usually starts within an hour of creating the index; **Fetch now** starts it at once. Until then the list reads **First crawl soon**, never **Ready**. An index of files or of a collection's records reads **Empty** in the list while it holds nothing, and shows on its own page how many documents it holds and how many are still being indexed. A page that only shows its text after its scripts run, as in a single-page app, is opened in a browser so that its text is found. The crawl reaches public sites only, and sends no login. A crawled page takes its **title** from the first heading of its text, so a search result shows the page's own name and not the site's name repeated. A page with no heading keeps the title the site gives it. A crawled page keeps its **content** and leaves out the site around it: the navigation, the header and footer, the sidebar, and furniture that documentation sites put beside the text, such as an "On this page" list, a version badge, a "Was this page helpful?" box or a "Last modified" line. A footer the site writes as ordinary text in the page, with nothing marking it as one, stays in. The index shows its **last crawl** in words: whether it is crawling now or finished, how many pages it fetched, stored, rendered in a browser and failed, and what it cost. A crawl that runs out of money stops, keeps the pages it fetched, and says so. **Each account has a monthly crawl allowance**, set by the platform: about 180,000 pages a month, across all of the account's crawl indexes. When it is used up, a crawl that is running stops and keeps the pages it fetched, a new crawl does not start, and the index says **monthly crawl allowance**. It renews on the 1st (UTC). Fetch now refuses in the same words, and the press does not count. If your account needs more, contact us. **Fetch now** crawls the site again at once, when you changed pages and do not want to wait for the schedule. It starts the same crawl the schedule runs, and costs the same. An account can press it 6 times a day (the day ends at 00:00 UTC); a press that starts nothing does not count. It starts nothing while a crawl of that index runs, and says when that crawl started. The schedule keeps its own crawls either way. A crawl that finishes removes the pages it no longer reaches: a page now outside the address, a page the site skips or refuses to crawlers, and a second address that serves the same text as a page it kept, so a search never finds one page twice. A page that fails to load once keeps its place. A crawl that stops early, or that reaches its page limit, removes nothing. A crawl that reaches the end of the site but keeps **no page** also removes nothing. This happens when the site shows a placeholder or is down. The index says **crawled: no page kept**, keeps what earlier crawls stored, and Home names it until a crawl keeps a page again. ### Files you upload Open the index and press **Upload a file**. The index takes Markdown, plain text and HTML files, and PDFs with a text layer. A scanned PDF has no text layer, so the index refuses it and says why. Each document shows its state: **pending** until it can be searched, then **indexed**. To take a file out of the index, press **Remove…** beside it, then **Remove it**. The console asks first because a removed file cannot be put back: upload it again to restore it. A file added through the API can also name its **source**: the address it came from, such as the web page it copies. A search result then shows that address, so an answer can cite where the text came from. The address must start with `https://` or `http://`. ### A collection's records Name the **collection** and the **fields to index**, such as `company, notes`. The index starts with the records already stored, then follows every record a run writes or deletes. To show records that describe the same thing as one result, name the field that identifies it under **Same item when this field matches**, such as `sku`: two listings of one product then show as one search result. It is a text or number field the collection declares, and not one that holds what people typed. A record without a value in it is still its own result. You choose this field when you create the index and cannot change it later; to fold on another field, create a new index. **Records can hold personal data.** With search by meaning on, their text is sent to the embedding provider. ## Search from your server An upload or crawl index can also be searched with no loop, by a server of yours. On the index's page, an owner mints a **search key** under **For a server of yours: search keys**; the key searches that index and does nothing else. Each search is charged at the published price per search. The request, the answer and the refusals are on [Search API](/docs/api/search.md). A collection index has no search keys: its records can hold personal data. ## Search your indexes yourself On **Indexes**, press **Search every index** above the list to search all your indexes at once, without opening one. An index's own **Try a search** tab opens the same search, starting on that index. Type what you are looking for, then choose: - **Find** — the words, the exact phrase, the words allowing typos, or a pattern (one term). [Writing a Search](/docs/search/writing-a-search.md) shows each with an example. - **In** — every index, or one. - **By** — **Both**, **Words only** or **Meaning only**. Words find an exact name, such as a command-line flag. Meaning finds a passage that says the same thing in other words. **Both** ranks the two together, as a loop's own searches do. Every search is charged a small fixed amount for running it. A search by meaning also embeds your query once, at the index's embedding price. Your wallet pays both. Each result names its index and its title, and says when the index is untrusted. Its passage reads as text, and code in it keeps its lines, in a monospace box of its own that ends with "…" when the passage stops inside the code. Press a result's title to read the document from that place. A document is **one result**, at its best-matching section. When other sections of the same page also matched, the result says so, for example **+2 more sections**; its title opens the whole page. A page crawled into two of your indexes is one result too, and so are records with the same value in their index's **Same item when this field matches** field. A run's agent gets the same results, and is told that the rest of each page can be read. ## How results are ordered **Search order** on **Settings** says in one line what your searches use now, such as *"Every search uses Fuse"*. Under **More** it chooses how searches are ordered, separately for four kinds of search: **A run's agent**, **Your search** on Indexes, **Your visitors** on your site, and **Your search keys** (a server of yours, through the [Search API](/docs/api/search.md)). Each one is set to one of: - **Off** — the plain order of the word and meaning matches. - **Rerank** — the reranking model scores each match against the search and puts the best first. - **Fuse** — the reranking model's scores added to the plain order. On an index's page, **Try a search** says the order in plain words: "Best matches first: a second model reread the top results" for Rerank (and "mixed with the usual order" for Fuse), or "In the usual order" for Off. All four use **Fuse** unless you choose otherwise; **Platform default** shows it. Rerank and Fuse each cost a small amount for each search, paid from the wallet, and add a little time; through a search key, a rerank is one published unit per search. Settings shows the price and the most time they add. Past that time, a search answers in the plain order, and a search whose time ran out before the reranking model ran is not charged for it. Only an owner can change the settings. The reranking model hides a match it scores too weak, but never one that holds a code you typed: a search for `WT-30` or `flatMap()` always shows a document that contains it, exactly as typed. Its score for a match is kept for a day, so the same search gives the same results, and a repeat costs nothing for the matches it has scored. When the reranking model does not answer, the search shows the plain order, including matches it would have hidden. When it scores every match too weak, the search shows the plain order too, with the line "Showing the closest matches by words and meaning.", rather than nothing; that search is charged, because the model ran. When the platform moves an index to a new embedding model, the index keeps answering with the old one until every document is embedded again. ## See how an index is searched Open the index. **Searches, last 30 days** says how many searches it answered, how many found nothing, and how long they took. It counts every door: your loops, your own searches, your visitors and your search keys. A search across several indexes counts once in each. The time is a range, not an exact figure: **under 250 ms**, or **2 s or more**. Under it, a list gives each day that had a search; the days are UTC. When the counts cannot be read, the index says so, and that is not a report that it had no searches. ## Delete an index Open the index and press **Delete index**. Its documents and everything built from them are removed. ## What an index costs Crawling, browser renders and indexing are paid from the account's wallet, and each crawl reserves its estimate before it starts. A crawl the wallet cannot cover does not start, and the index says so. Indexing is charged **per chunk**: a chunk is one section of a document, up to about 2,000 characters, and a typical document is 2 to 4 chunks. A long document costs more than a short one, because it stores more. Indexing a document again with unchanged text costs nothing. The price per 1,000 chunks is on the [pricing page](/pricing.md). A document the wallet cannot cover waits as pending, and the index's page counts how many wait for budget. You do not send them again: within about an hour after the wallet can pay, they index on their own. While the wallet still holds less than one chunk's price, they keep waiting and nothing is charged for them. An owner of the account can give an index its own **monthly cap**, in dollars, on the index's page, and remove it there. Members see the cap but cannot change it. The cap limits the index's crawls, browser renders and indexing in one calendar month (UTC), beside the wallet: each one must fit in both. A crawl whose estimate is more than the cap has left this month does not start, and the index says so. A document the cap cannot cover waits as pending, and the index names the cap as the reason. Within about an hour after the month turns or an owner raises the cap, those documents index on their own. The cap counts only what the index spends while the cap is set, so a cap first set in the middle of a month starts at zero. Searches are not limited by it. A search by your loops, your visitors or you is charged a fixed amount for running it, whichever way it searches, plus its query's embedding when it searches by meaning, plus the reranking when it ran. A search through a search key is one published price that covers running it and its query's embedding; a rerank, when the search asks for one and it sets the order, is added at its own price. All of these prices per 1,000 are on the [pricing page](/pricing.md). An index's **Spent this month** adds up its crawls, its indexing, and its share of every search that searched it: your loops' runs, your own searches, your visitors and your search keys. A search over several indexes is shared evenly among them. Each search is still paid once, from the wallet. --- # Writing a Search > The four ways a search matches — words, an exact phrase, words with a typo, a pattern — words or meaning, the reranking model, and what each searcher may send A search has two choices: **how its text matches**, and whether it searches by **words, by meaning, or both**. This page shows each choice with a real search. Every example ran on 2026-10-12 against an index of a crawl of the Kubernetes documentation (kubernetes.io/docs, about 1,200 pages), with the default of 10 results, and shows the first three. Each searched by words only unless it says otherwise, with the reranking model's **Fuse** order, which is the default. Fewer results can change the order, because the reranking model then scores fewer matches. The text of a search is always literal. No character is an operator, so `--dry-run=server` is searched for as it is written. ## Four ways to match | Match | It finds | Example | | --- | --- | --- | | **Words** (the default) | The words, in any order and in any form | `roll back a deployment` | | **Exact** | The words together, in this order, as typed | `kubectl rollout undo` | | **Fuzzy** | Each word, or the same word with one typo | `kubernets namespase` | | **Regex** | One word that the pattern matches | `kube-(proxy\|scheduler)` | On the console, **Find** offers these as **the words**, **the exact phrase**, **the words, allowing typos** and **a pattern (one term)**. In a request, they are `"match": "words"`, `"exact"`, `"fuzzy"` and `"regex"`. ### Words The words in any order and in any form: `deployments` also finds `deployment`. A page that holds all the words as a phrase ranks higher. A page that holds a code exactly as typed, such as `kubectl` or `--dry-run`, ranks much higher. When the text holds two or more words that carry meaning, a page must hold at least two of them, or one code exactly as typed. Small words such as "a" and "the" do not count. `roll back a deployment` found: 1. **Performing a Rolling Update** — "To roll back the deployment to your last working version, use the rollout undo subcommand…" 2. **Update a Deployment Without Downtime** — "kubectl rollout undo deployment/nginx-deployment" 3. **Deployments** — "…when you roll back to an earlier revision, only the Deployment's Pod template part is rolled back." ### Exact The words together and in this order, in the text of a page. Each word must be as typed: an exact search does not find other forms of a word. Use it for a command, a product name or an error message. `kubectl rollout undo` found the page **kubectl rollout undo**, the kubectl command reference (titled **GETTING STARTED**), and **Perform a Rollback on a DaemonSet**. ### Fuzzy Each word, or a word one typo away from it. A typo is one letter added, missing or changed, or two letters swapped. Each typo is corrected to the word the index's pages use most that is one typo away, or two for a word of 7 letters or more. When every word corrects, the search is the corrected words, and it ranks exactly as they do: `kubernets namespase` finds what `kubernetes namespace` finds, in the same order, and `deploymnt` puts **Deployments** first, as `deployment` does. A word that corrects to nothing still finds a word one typo away from it or from its root. ### Regex The text is a pattern that must match **one whole word** of the page. Upper and lower case match the same. A word here can be a code such as `kube-proxy` or `snake_case`, or a part of it, such as `kube`. `kube-(proxy|scheduler)` found **Good practices for Dynamic Resource Allocation as a Cluster Admin**, **Installing Addons** and **Cluster Architecture**. `kube-.*` finds every word that starts with `kube-`. A pattern cannot hold a space, because it matches one word. Begin a pattern with a few fixed letters: a pattern that could match too many words is refused, in these words: > `query.text` is too broad a pattern to search: start it with a few fixed letters and use fewer > wildcards, as `deploy.*` rather than `.*a.{20}` A pattern the search cannot read is refused too, with the place it stopped: `kube-(proxy` gets "error: unclosed group". A visitor reads the same advice without the field name, and "This is not a pattern the search can read. Check its brackets and backslashes, or search by words." for a pattern the search cannot read. ## Words, meaning, or both Each search can read the **words** of a page, its **meaning**, or **both**. On the console this is **By**: **Words only**, **Meaning only** or **Both**. In a request it is `"mode"`: `"text"`, `"semantic"` or `"hybrid"`, the default. - **Words** finds the text as the match above says. It finds an exact name, such as a command-line flag, that meaning can miss. - **Meaning** finds a passage that says the same thing in other words. It needs words that carry meaning, so it does not run for a pattern alone. It runs only on an index with **Search by meaning as well as by words** on. - **Both** runs the two at once and ranks their results together. This is how a loop's own searches run. `how do I go back to the version that worked`, by meaning only, found the kubectl command reference (**GETTING STARTED**), **StatefulSets** and **Update a Deployment Without Downtime**. The third is at the passage "If a new version introduces issues, you can roll back to a previous revision.", which shares almost no words with the search. A search by meaning also embeds its text once, at the index's embedding price. See [What an index costs](/docs/search/overview.md#what-an-index-costs). ## The reranking model After the words and the meaning find their matches, a **reranking model** can score each match against the search, put the best first, and hide the matches it scores too weak. Your account chooses this for each kind of searcher under **Settings > Search order**; see [How results are ordered](/docs/search/overview.md#how-results-are-ordered). What the answer says about it: - When it hides matches, the answer says how many, for example "3 matches were too weak to show". - When it would hide every match, it hides none: the answer is the plain order, and says "Showing the closest matches by words and meaning." - It never hides a match that holds the text exactly as typed, such as `WT-30`. - It does not run for a pattern, because a pattern holds no words to score by. The answer then says "the query holds no natural-language text to score the results by; the results are in the plain order". By fuzzy match, the reranking model scores the corrected words, so a typo that corrects is scored as the word it corrects to, and `deploymnt` is ordered as `deployment` is. A typo that corrects to nothing is scored as typed, and the model can score good matches too weak because of it. Fix the typo, or send `"rerank": false` where the request takes it. ## What each searcher may send | Searcher | Ways to match | Words or meaning | Reranking model | Results | | --- | --- | --- | --- | --- | | You, on **Indexes** | All four | Your choice | Your account's setting for **Your search** | Up to 10 | | A loop's agent | All four, and more (below) | Its choice | Your account's setting for **A run's agent** | 1 to 50 | | A visitor, in the embed's search box | All four, as **Match** | Both | Your account's setting for **Your visitors** | Up to 10 | | A visitor or your server, through a loop's search API | All four | `mode` | `rerank`, or your setting for **Your visitors** | 1 to 20 | | Your server, with a search key | Words | `mode` | `rerank`, or your setting for **Your search keys** | 1 to 20 | A page you build with the React SDK's `useSearch` hook may send all four; its `SearchBox` shows them as **Match**, and `matches` offers fewer. The requests, the answers and the refusals of the two APIs are on [Search API](/docs/api/search.md). A loop's agent writes its own searches, and it may also: - join searches with `all` (each must match), `any` (one must match) and `not` (must not match); - search one part of a page: its `title`, `heading`, `body` or `url`; - give separate text for the meaning half, with `semantic`. You do not write these. To steer what a loop searches, say in its instructions which index holds what; see [Letting a Loop Search](/docs/guide/search-indexes.md). --- # API Overview > The run API your server or page calls, how it authenticates, and what its limits answer The run API is how your own server or interface starts and talks to runs of a **published** loop. Every path begins with `/api` on `https://plutonium.io`. A loop is named by its **public id** (`pl_…`), shown on the loop's **Keys** tab once the loop is published. ## Authentication Every call carries one header: ``` Authorization: Bearer ``` The credential is one of two things. A console session cookie is refused on the run routes. - **An API key** (`rk_…`) for your server. An owner mints it on the loop's **Keys** tab (`POST /api/loops/{loopId}/keys`) with one or more scopes: `create_runs`, `read_runs` and `read_collections`. The key text is shown once and cannot be shown again; revoke it and mint another if it is lost. A key's scopes must be ones the loop's delivery allows. A `read_collections` key names the API it serves: choose it under **Serves** on the loop's **Keys** tab, press the **Mint a key for** button in the API's detail on **Schedules**, or send `claim_name` when you mint it through the API. - **A user token** for one of your users, minted by one of the loop's [identity doors](/docs/api/identity.md). The loop's identity scheme decides which door it has. ## Limits Routes are rate limited, and a refused request answers `429 Too Many Requests` with a sentence that names which limit and a `Retry-After` header with the seconds to wait. There are several: - **Each route's own limit**, per account and across all callers. - **The loop's per-address limit**, on the identity doors and on starting a run. - **The loop's per-subject run cap and its concurrent-run cap**, on starting a run. A route that spends money refuses with `503` rather than let a request through when its limit cannot be checked. ## The reference - [Identity](/docs/api/identity.md): the doors that mint a user token, and your own OpenID issuer. - [Runs](/docs/api/runs.md): start a run, read it, talk to it, follow it. - [Search](/docs/api/search.md): search your indexes with a search key, or what a loop searches. - [Collections](/docs/api/collections.md): read a collection's records from your server. - [Webhooks](/docs/api/webhooks.md): start a run with a signed request, and receive a loop's outputs. --- # Identity > The doors that give one of your users a token for a loop, and your own OpenID issuer A user token lets one of your users reach their own runs of a loop. The loop's identity scheme decides which door mints it; the [API Overview](/docs/api/overview.md) says how a token is sent. ## Doors | Route | For | Body | |---|---|---| | `POST /api/loops/{publicId}/visitors` | An **anonymous** visitor | `previous_token` to renew, `ancestor_origin` for an embed | | `POST /api/loops/{publicId}/identities` | A user **your system vouches for** | `assertion`: a compact HS256 JWT your server signs with the loop's secret; its `sub` becomes the run's subject. On a loop whose scheme is `oidc`, `assertion` is instead an id token from your own OpenID issuer (see [Your own OpenID issuer](#your-own-openid-issuer)) | | `POST /api/loops/{publicId}/door` | Asking whether a caller would be admitted, without minting anything | The same body as the door it checks | Each door answers a user token (`token`, `expires_at`, `subject`). An assertion can be exchanged once. An owner reads the loop's secret on its **Keys** tab, under **Signing secret**, and rotates it there. Rotating refuses assertions signed with the old one at once. ## Your own OpenID issuer A loop whose identity scheme is `oidc` names an **issuer** and a **client id**. Send the id token your issuer gave the user as `assertion` on `/identities`. The token must be signed `RS256` or `ES256` with a key the issuer publishes, its `iss` must be the issuer, its `aud` must name the client id, and its `sub` becomes the run's subject. A refusal names the check that failed. --- # Runs > Start a run of a published loop, read it, talk to it and follow it A `runId` is the id `POST /api/runs` answered. | Method and path | What it does | |---|---| | `POST /api/runs` | Starts a run in the loop's published version. Body: `loop` (the public id), and optionally `message`, and `subject` for a run your key starts on a user's behalf. Answers `201` with `run` and `realtime`. | | `POST /api/runs/batch` | Starts up to 25 headless runs at once, for a loop that declares an `api` trigger. API keys only. Each item carries a `payload` and may carry a `key`; a repeated `key` answers the earlier run. | | `GET /api/runs/{runId}` | Reads the run: its `state`, its `ending` once it has one, and what it is waiting on. | | `POST /api/runs/{runId}/messages` | Sends `text` to the run. `202` means recorded; the reply arrives on the realtime channel. A finished run answers `409`. | | `GET /api/runs/{runId}/transcript` | Reads the turns a user saw, newest page first (`before` pages back). | | `POST /api/runs/{runId}/stop` | Asks the run to stop. `202` means the request is recorded, not that the run has halted. | | `POST /api/runs/{runId}/tool-results` | Answers a tool call the run asked your page to make (`client_call`). | | `POST /api/runs/{runId}/tool-confirmations` | Confirms or declines an action the run asked the user to confirm (`client_confirm`). Body: its `call_id` and `approved`, and optionally `note`, the user's words to the run (at most 500 characters). With `reply: true` and a `note`, the user neither confirms nor declines: the action does not run, and the run reads the note and may ask or change its request. | | `POST /api/runs/{runId}/inputs` | Answers the form the run asks the user to fill in (`inputs_request`). Body: its `call_id`, and `values` by input id, or `declined: true`. The values reach no model. One answer per request; a request already answered or lapsed answers `409`. | | `POST /api/runs/{runId}/verification` | The user's side of an email check (`verification_request`). Every body carries its `call_id`. Without `code`, it sends a code to `email`, or to the address the user's identity asserted. With `code`, it redeems it. A wrong or expired code answers `422` with a sentence the person can read. Neither the address nor the code reaches a model. | A run the credential cannot reach answers `404`, so an id outside it reads as no run at all. A user token reaches only its own user's runs in its loop; an API key reaches every run of its loop. A key without the scope a route needs answers `403`, naming the scope. ## What a run carries `state` is one of `running`, `waiting`, `done`, `failed`, `over_budget` or `cancelled` (and the earlier `draft`, `estimated`, `approved`). `waiting_on` says who the run waits on: `user`, `operator` or `external`. `ending` says why it ended: `completed`, `over_budget`, `lapsed`, `check_failed`, `stopped`, `otherwise` or `escalated`, with `end_message` in words. A run carries no cost, token, model or tool fields. Those are yours to read in the console, never your users'. **A run over budget still starts.** There is no `402`: a run that meets a cap ends with the `over_budget` ending. ## Following a run `POST /api/runs` answers `realtime`: a WebSocket `endpoint`, a `channel` and a `token` scoped to that one run, until `expires_at`. You can also poll `GET /api/runs/{runId}` and its transcript. --- # Search API > Search your indexes from your server with a search key, or search what a loop's published version searches There are two ways to search [Reactor search](/docs/search/overview.md) indexes from outside the console. How the text of a search matches, with examples, is on [Writing a Search](/docs/search/writing-a-search.md). - **With a search key**, from your server, with no loop: `POST /api/indexes/{indexId}/search`. - **Through a loop**, from your server or your page: `POST /api/loops/{loopId}/search`. ## With a search key A search key searches the indexes it was minted for, and does nothing else: it starts no run and reads no collection. An owner mints one on the console, on the index's page under **For a server of yours: search keys**. The key is shown once; if it is lost, revoke it there and mint another. A search key cannot search a **collection** index. A collection holds your account's records, which can be personal data, and a key's caller is not your account. Send the key as `Authorization: Bearer rk_…` to `POST /api/indexes/{indexId}/search`, where `indexId` is one of the key's indexes. Keep the key on your server: this route does not answer a browser on another site, because a key in a page's source is a key anyone can read. The body: ```json { "query": "what to find", "mode": "hybrid", "rerank": true, "limit": 10 } ``` - `query` is required: 1 to 500 characters, matched as words and by meaning. - `mode` is `hybrid` (the default: both), `text` (the words only) or `semantic` (the meaning only). - `rerank` is your account's setting when absent. `false` keeps the plain order. `true` is refused with `403` when your account turned reranking off for search keys, under **Settings > Search order**. - `limit` is 1 to 20, 10 when absent. It answers `200` with `results`, best first. Each result has the `document` id in the index, a `title`, a `heading` (where it sits in its document), a `snippet` (the matching passage as plain text: a link's words without its address, and no Markdown marks; see [A snippet's code](#a-snippets-code)), and a `url`: a crawled page's address, or the source an uploaded file named when it was added. `reranked` says whether a rerank set the order, and when it did not, `rerank_reason` says why (see [Why a search was not reranked](#why-a-search-was-not-reranked)). A result is text from your indexed documents, so show it as text. **Each call is charged one search** at the published price on [Pricing](/pricing.md), and **one rerank more** when `reranked` is true, and only then: an `all_too_weak` answer is not charged a rerank on this route. A call your wallet cannot cover answers `402` and charges nothing. A refused call is never charged. The refusals say what to fix: | Status | When | | --- | --- | | `400` | The body is not one this route takes. | | `402` | Your wallet cannot cover the search. | | `403` | No key, a key that is not a search key, a revoked key, a key that does not search this index (the message names the ones it does), or a rerank your account turned off. | | `404` | The index is gone, or is a collection index. | | `429` | Over the rate limit. `Retry-After` says when to try again. | | `503` | Search could not run just now; try again. | ## Through a loop `POST /api/loops/{loopId}/search` searches what the loop's published version searches, minus every collection index. `loopId` is the loop's public id (`pl_…`). It takes an API key with the `search` scope, for a loop that declares `api` delivery, or the visitor credential the embed and the SDK hold. A search key is not taken here. The body is `{"query": {"text": "what to find"}}`. The text is 1 to 500 characters. Add `"match"` to change how it is found: `"exact"` finds the words together and in order, `"fuzzy"` allows a typo in each word, and `"regex"` reads the text as a pattern for one whole word, such as `deploy.*`. Add `"limit"` for at most that many results (10 when absent, at most 20). Any other form of query, such as a boolean or a raw query, answers `400`. A pattern too broad to search answers `400` with what to change: start it with a few fixed letters and use fewer wildcards. - `mode` is `hybrid` (the default: both), `text` (the words only) or `semantic` (the meaning only), as on the index route. - `rerank` is your account's setting for visitors when absent. `false` keeps the plain order. `true` is refused with `403` when your account turned reranking off for visitors, under **Settings > Search order**. Each search is charged by the same prices and held to the same budgets whatever it asks for. The amount follows what ran: a search by words only embeds nothing, and a rerank is charged whenever the reranking model ran. That includes an answer whose `rerank_reason` is `all_too_weak`, which is not reranked; every other answer that is not reranked is not charged a rerank. It answers `200` with `results`: each one has a `title`, a `heading` (where it sits in its document), a `snippet` (the matching passage as plain text, with no Markdown marks; see [A snippet's code](#a-snippets-code)), and a `url`: a crawled page's address, or the source an uploaded file named when it was added. `took_ms` is how long the search took, and `reranked` says whether the reranker ordered the results; when it did not, `rerank_reason` says why. The answer never carries a cost. A result is text from the indexed documents, so show it as text. A loop with nothing a visitor may search answers `404`. A search the wallet or the loop's budgets cannot cover answers `503`, the same answer as a search that could not run. ## A snippet's code A snippet keeps its prose on one line. When the passage holds code, the code keeps its own lines and indentation, and it comes between two lines that start with three backticks. The first of the two can name the language: ````text Configure the sidebar: ```js window.$docsify = { loadSidebar: true, }; ``` Then reload the page. ```` A snippet never starts inside code. When it stops inside code, it keeps whole lines, closes the code with its own backtick line, and ends with a line that is only `…`: show that mark as the code's last line, so a reader sees that more code follows. To show a snippet, split it at those lines: show the prose as text and the code as preformatted text. Never render a snippet as Markdown or HTML, because it is text from your indexed documents. ## Why a search was not reranked Both routes answer `rerank_reason` when `reranked` is false, and leave it out when it is true. The results are then in the search's own order, which ranks the words and the meaning together. | `rerank_reason` | What happened | | --- | --- | | `off` | The rerank was not asked for, or your account turned it off for this route. | | `all_too_weak` | The reranking model ran and scored every match too weak to show, so the closest matches by words and meaning are shown. Through a loop this is charged a rerank, because the model ran; with a search key it is not. | | `budget` | The reranking model did not answer in time. | | `error` | The reranking model did not answer. | | `malformed` | The reranking model's answer could not be read. | | `not_covered` | The wallet cannot cover the rerank. | | `no_text` | The query has no words to score the results by. | | `floor` | A loop that searches the index needs a stronger model than the reranking model. | | `flag` | The ordering setting could not be read. | --- # Collections > Read the records of a collection from your own server, under an API key `GET /api/served/collections/{collection}/records` returns the records of one collection to your server. It takes an API key with the `read_collections` scope, minted for an **API** that names the collection. Create the API on **Schedules** with **New API**: pick the collections and the fields of each that a key may read. Name the fields: a key reads only those, and records that leave under a key cannot be unsent. The loop the key is minted on must declare `api` delivery and every collection the API serves. Each request is charged to your wallet at the price of an API request served on [Pricing](/pricing.md). The charge is taken after the request is served: once an hour, a key's requests from the hour before are taken from the wallet in one charge. It answers `200` with the `collection`, its `items` and a `next_cursor`. Each item has a `record_id`, its `data` (the API's fields of the record, and no others), `created_ts` and `updated_ts`. `fields` lists the fields served; it is absent when the API serves every field of the collection. Send `cursor` with the last `next_cursor` for the next page, and `limit` for the page size; no `next_cursor` means the end. A key that may not read the collection answers `403` with a sentence that says why and what to change: a revoked key, a key without `read_collections`, or an API that does not name this collection (it names the collections the key does reach). A key on a loop with no published version answers `404`. --- # Webhooks > Start a run with a signed request, and receive what a loop sends when a run ends ## Into a loop A loop that declares an `event` trigger with `source: webhook` accepts `POST /api/inbound/{publicId}`, which starts a headless run and answers `202` with its `run_id`. Sign each request: ``` Pio-Signature: t=,v1= ``` with the inbound secret you stored on the loop's page in the console. `t` must be within 300 seconds of the server's clock, and each signature is accepted once. The body is JSON of at most 256 KiB. Every refusal carries a `reason`: `signature_malformed`, `timestamp_outside_window`, `payload_not_json`, `signature_mismatch`, `loop_archived`, `loop_not_published`, `webhook_not_declared`, `replayed`, `payload_too_large`, `subject_missing`, `concurrency_full` (with `Retry-After`), or a `503` reason when the platform cannot check it. ## Out of a loop A loop that declares a `webhook` output for `run.ended` POSTs to your URL when a run ends. The body is JSON and carries identifiers only, never text a model wrote: ```json { "event": "run.ended", "loop_id": "…", "loop_version": 3, "task_id": "…", "root_task_id": "…", "end_condition": "…" } ``` For `run.ended`, `task_id` and `root_task_id` both name the run: the same id as a [run](/docs/api/runs.md)'s `runId`. Read the run itself with `GET /api/runs/{runId}`. A webhook output for `record.written` POSTs each time a run saves a record. Its body has no `end_condition`, and names the record instead: ```json { "event": "record.written", "loop_id": "…", "loop_version": 3, "task_id": "…", "root_task_id": "…", "collection": "repair_requests", "record_id": "…" } ``` Read the record through the collection's API ([Collections](/docs/api/collections.md)). **The body never carries what a person typed into a card.** When a collection's key is filled from one of those values (a `bind` on the key), `record_id` is `[sealed:]`, so the delivery cannot say which record was written. Saving the draft warns about it. To read the record back, key the collection on a generated id (`: generated`) and keep the person's value in a bound field: the delivery then names the record, and the value stays in it. ### Verifying the signature Every delivery carries the same header as an inbound webhook: ``` Pio-Signature: t=,v1= ``` The secret is under **Webhook signing secret** on the loop's **On your site** tab for a loop placed on a site, or its **Keys** tab for a loop used only through the API. A webhook output that names a stored secret of yours is signed with that one instead. Compute the HMAC over the raw bytes you received, before you parse them: ```js import { createHmac, timingSafeEqual } from 'node:crypto'; // rawBody: the request body exactly as received, as a string. export function verifyPioSignature(rawBody, header, secret, toleranceSeconds = 300) { const parts = Object.fromEntries(header.split(',').map((part) => part.split('='))); const t = Number(parts.t); if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false; const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest(); const given = Buffer.from(parts.v1 ?? '', 'hex'); return given.length === expected.length && timingSafeEqual(given, expected); } ``` `t` is when the platform signed this attempt, so a retry carries a fresh one. **Rotating the secret stops the old one at once**, deliveries already waiting for a retry included. Put the new secret in your receiver first, then rotate. Each loop's secret is its own account's: a loop with the same name in another account is signed with a different one. **A secret you read before 17 October 2026 no longer verifies**: read it again from the same tab and put the new one in your receiver. ### Retries Only a `2xx` answer counts as sent; a redirect is not followed. A refused delivery is tried up to six times in all, waiting 30 seconds, then 2, 8, 32 and 128 minutes; each wait can run up to a minute longer. A delivery that fails never changes how the run ended.