Soot DocsHow Soot is designedMarkdown ↗

07 / Company and goals

Build a screen for Nest

Add a screen to Nest without a Nest release: a Soot writes it, or a pack brings it; what the operator decides; limits and safety.

Nest is a super app: every screen in it is a piece placed in a slot. Besides the pieces Nest ships with, there are two ways to add a screen without a new Nest release: a Soot or a team writes its own screen, or a pack brings a screen along with its tools. This page walks through both, and tells the operator what they decide about those screens.

You areYou wantRead
A Soot, or a team's coordinatorA screen where the people you work with use your data and tools and ask youPath 1
A pack authorA screen that many workspaces can reuse, with its own toolsPath 2
The operator of a NestTo place, arrange, go back on and remove screensWhat the operator decides

Choosing a path

Written by a Soot or a teamPack
Who writes itThe Soot itself: it writes the files in its workspace and pushes them with storage pushThe pack author
Where it livesui/<id>/ in the Soot's or the team's filesinterface.pieces in pack.json
Reading dataNamed queries over the owner's own tasks, tables, files, needs, outcomes and memory, or a read tool the owner wroteOne read tool of the pack, returning anything
Doing workThe owner's tool or table write, at once with no model turn; or a question to the owning Soot that gets an answerOne write tool of the pack
Calling an outside serviceA written tool: one declared HTTPS request, with a key the person enters in NestA pack tool running its own program
Getting into NestThe person is asked once (the screen and its tools on one card); later versions go live by themselvesThere as soon as a Soot selects the pack
ReleaseNoneThe pack, through Forge or your own packs directory

Write it when the screen needs what the Soot can already read, plus at most a few calls to an outside service: it is the cheapest path, and a Soot finishes one in a single run. Use a pack when you need a program that runs on the host (logic that does not fit in one request), or the same screen in many workspaces.

Both paths share everything else: the same slots, the same kit, the same sandboxed frame, and the same way Nest keeps a screen light.

Slot (slot)Where it showsWrittenPack
homeA section of Hộp việc (the inbox)yesyes
railAn area of its own in the side baryesyes
project.tabA tab of the chosen project (needs tab {id, label})yesyes
data.tabA tab in Dữ liệu (Data)yesyes
settingsA Settings sectionnoyes

Path 1: a Soot or a team writes it

_[0.19.0]_ Written tools, named actions, ask and kit level 2 (soot.run, soot.ask, soot.asks) are in the runtime and Nest since 0.19.0. Nest 0.18.0 has only queries and soot.action.

A written screen has two halves, both files the Soot writes in its workspace and pushes with storage push into its own level (soot:<id>; a team's is team:<id>, pushed only by its coordinator):

  • The back end is a tool: tools/<id>/tool.json declares one HTTPS request to a named host. It is a declaration, not code: nothing a Soot writes runs in the runtime. The host sends the request, puts the key in just before it goes, and removes the key from the answer.
  • The front end is a piece: ui/<id>/ with index.html, scripts, and piece.json written last. All of the screen's logic is its own JavaScript, running in Nest's sandboxed frame.

A screen has no access of its own. It reads through named queries, works through named actions and asks its owning Soot through ask: exactly what piece.json declares and the person approved. Everything runs with the owner's access.

Example: a translation screen

The person writes to the Soot writer: "Make me a translation screen". The Soot proposes a translation service and says it needs an API key, which the person will enter on the approval card in Nest, not in chat. Then the Soot writes five things in this order:

Sample text · not a command
data: create_table glossary   the glossary table the screen reads and writes
tools/translate/tool.json     the tool: one request to the translation service
ui/translate/index.html       the screen; links _kit/piece.css and _kit/piece.js
ui/translate/app.js           soot.run("translate"), soot.view("terms"), soot.ask(...)
ui/translate/piece.json       the declaration, written last: this is the save

The service in the example, at api.example.com, is made up; for a real one, change url, the headers, body and output.pick to match its documentation. TestTranslateGuideExample runs the files of the Vietnamese guide against a fake API; the files below differ only in display text.

The tool

tools/translate/tool.json:

JSON sample · not a command
{
  "id": "translate",
  "label": {"vi": "Dịch văn bản", "en": "Translate text"},
  "description": "Sends a text and a target language to the translation service at api.example.com and gets the translation back.",
  "mode": "read",
  "input": {
    "type": "object",
    "required": ["text", "target"],
    "properties": {
      "text": {"type": "string", "minLength": 1, "maxLength": 5000, "description": "The text to translate."},
      "target": {"type": "string", "enum": ["EN", "VI", "JA"], "description": "The language to translate into."}
    }
  },
  "run": {"http": {
    "method": "POST",
    "url": "https://api.example.com/v2/translate",
    "headers": {"Authorization": "Bearer {{cred:TRANSLATE_KEY}}"},
    "body": {"text": ["{{input.text}}"], "target_lang": "{{input.target}}"},
    "timeout": "20s"
  }},
  "output": {"pick": "/translations/0"},
  "needs": {
    "hosts": ["api.example.com"],
    "credentials": {
      "TRANSLATE_KEY": {
        "title": {"vi": "Khóa dịch vụ dịch", "en": "Translation service key"},
        "description": "Create a key on the translation service's account page, under API keys.",
        "url": "https://example.com/account/keys"
      }
    }
  }
}

  • description and label show on the approval card for the person, and are what the model reads when the Soot calls the tool itself: write them in the person's language and say what is sent where. Each stays on one line, with no control or text-direction character (the save is refused).
  • mode is read when the request changes nothing at the service (translating only returns a translation), write when it creates, changes, deletes or sends something. read goes with GET and POST only; PUT, PATCH and DELETE are always write (saving read with one is refused with method_needs_write). The headers X-HTTP-Method-Override, X-Method-Override and X-HTTP-Method are refused on every tool. With POST, read is the Soot's word, so the card names the method and says data is sent to the host. A write tool goes through the effect journal and the host's approval policy.
  • A {source: "tool"} query (a read when the screen opens) binds only a GET tool. A POST tool like this one is bound as a named action and called with soot.run.
  • input is a small JSON Schema: an object of strings, numbers, integers and booleans (with enum, length and value bounds) or arrays of them. The host checks every call.
  • {{input.<field>}} may stand in the path, query values, headers and body strings; a string that is exactly one placeholder takes the typed value. {{cred:<NAME>}} may stand only in a header or a query value. The scheme, the host and header names are always literal.
  • needs is what the person approves: the hosts (domain names, no IP, no port) and the keys. Each key has a title, a description and a url so the person knows where to get it; the card shows a "where to get the key" link when there are both a description and a url.

The made-up service answers {"translations": [{"text": "…", "detected_source_language": "EN"}]}; output.pick takes the first item, so the screen gets {text, detected_source_language}.

Writing tool.json saves the tool. The write's result carries one note:

JSON sample · not a command
{"tool": "soot:writer:translate", "saved": true, "revision": "…", "state": "proposed", "credentials_missing": ["TRANSLATE_KEY"],
 "message": "proposed: the person is asked once to approve it (with the screen that uses it, when a proposed screen binds it); until then it cannot be called. The person enters TRANSLATE_KEY in Nest; never ask for a key in chat"}

The glossary table

The screen reads and writes the Soot's glossary table. The table must exist before piece.json is saved (the save runs the query once). The Soot creates it with the data tool:

JSON sample · not a command
{"op": "create_table", "scope": "soot:writer", "table": "glossary", "description": "Terms the translate screen keeps.",
 "columns": [{"name": "term", "type": "text", "required": true}, {"name": "meaning", "type": "text", "required": true}]}

The screen

ui/translate/index.html. The bundle's CSP blocks scripts and styles written in the HTML, so the script is a file. Do not use a <form>: the frame has allow-scripts only, so a submit event never arrives; buttons are type="button" with click handlers.

Sample text · not a command
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Translate</title>
<link rel="stylesheet" href="_kit/piece.css">
<h1>Translate</h1>
<p id="state" class="muted"></p>
<section class="card stack">
  <textarea id="text" rows="4" maxlength="5000" aria-label="Text to translate" placeholder="Paste the text to translate"></textarea>
  <div class="row">
    <select id="target" aria-label="Translate into">
      <option value="EN">English</option>
      <option value="VI">Vietnamese</option>
      <option value="JA">Japanese</option>
    </select>
    <button id="go" type="button" class="primary">Translate</button>
  </div>
  <p id="result" class="muted">The translation shows here.</p>
</section>
<section class="card stack">
  <h2>Ask the Soot</h2>
  <div class="row">
    <input id="question" class="grow" maxlength="4000" aria-label="Question" placeholder="Does this translation read naturally?">
    <button id="ask" type="button">Ask</button>
  </div>
  <p id="answer" class="muted"></p>
</section>
<section class="card stack">
  <h2>Glossary</h2>
  <ul id="terms" class="list"></ul>
  <div class="row">
    <input id="term" aria-label="Term" placeholder="Term">
    <input id="meaning" class="grow" aria-label="Meaning" placeholder="Meaning">
    <button id="add" type="button">Save</button>
  </div>
</section>
<script src="_kit/piece.js"></script>
<script src="app.js"></script>
</html>

ui/translate/app.js:

Sample text · not a command
const $ = id => document.getElementById(id);
const say = (el, text, cls = "muted") => { el.textContent = text; el.className = cls; };
let last = null; // the last translation, sent along with a question

async function translate() {
  const text = $("text").value.trim(), target = $("target").value;
  if (!text) return say($("result"), "Type the text to translate.", "error");
  $("go").disabled = true;
  say($("result"), "Translating…");
  try {
    const { output } = await soot.run("translate", { text, target });
    last = { text, target, translation: output.text };
    say($("result"), output.text, "");
  } catch (err) {
    // Nest itself says a key is missing, with its "Open the key vault" button; do not repeat it.
    say($("result"), err.code === "credential_missing" ? "Could not translate: the key is missing." : "Could not translate: " + err.message, "error");
  } finally {
    $("go").disabled = false;
  }
}

function showAsk(s) {
  if (s.state === "done") {
    const better = s.reply.data && s.reply.data.translation;
    say($("answer"), s.reply.text + (better ? " Suggestion: " + better : ""), "");
  } else if (s.state === "waiting") say($("answer"), "The Soot needs your answer in the conversation.");
  else if (s.state === "failed") say($("answer"), "The Soot could not answer this one.", "error");
  else say($("answer"), "The Soot is answering…");
}

async function ask() {
  const text = $("question").value.trim();
  if (!text) return;
  $("ask").disabled = true;
  try {
    const s = await soot.ask(last ? { text, data: last } : { text }, { onState: showAsk });
    showAsk(s);
    if (s.state === "done") $("question").value = ""; // asked and answered: the box is empty for the next one; a failed question stays to retry
  } catch (err) {
    say($("answer"), "Could not ask: " + err.message, "error");
  } finally {
    $("ask").disabled = false;
  }
}

function drawTerms(out) {
  $("terms").replaceChildren(...out.rows.map(row => soot.el("li", { class: "row" },
    soot.el("strong", {}, row.term), soot.el("span", { class: "grow muted" }, row.meaning))));
  if (!out.total) $("terms").replaceChildren(soot.el("li", { class: "empty" }, "No terms yet."));
}

async function addTerm() {
  const term = $("term").value.trim(), meaning = $("meaning").value.trim();
  if (!term || !meaning) return;
  $("add").disabled = true;
  try {
    await soot.run("add_term", { rows: [{ term, meaning }] });
    $("term").value = $("meaning").value = "";
    drawTerms(await soot.view("terms"));
  } catch (err) {
    say($("state"), "Could not save the term: " + err.message, "error");
  } finally {
    $("add").disabled = false;
  }
}

soot.ready(async () => {
  if (soot.level < 2) {
    say($("state"), "This screen needs a newer Nest. Update Nest and open it again.", "error");
    document.querySelectorAll("button").forEach(b => { b.disabled = true; });
    return;
  }
  $("go").addEventListener("click", translate);
  $("ask").addEventListener("click", ask);
  $("add").addEventListener("click", addTerm);
  const kept = soot.cached("terms");
  if (kept) drawTerms(kept);
  soot.live(async () => {
    try { drawTerms(await soot.view("terms")); } catch (err) { say($("state"), "Could not read the glossary: " + err.message, "error"); }
    // The newest question and its answer, also when the screen is opened again.
    try { const prev = (await soot.asks()).asks[0]; if (prev) showAsk(prev); } catch (err) { /* nothing asked yet */ }
  });
});

  • soot.run(name, input) runs the named action name; the runtime does it at once, with no model turn. Every call gets a new request_id; sending an old request_id again only reads its result back, it never calls twice.
  • soot.ask(input, {onState}) sends the question into the viewer's own conversation with the owning Soot. The promise resolves with the done state and its reply {text, data?}, and rejects with ask_failed when the run fails. soot.asks() lists the questions asked, newest first, so a reopened screen shows the answer; soot.live reads again when the conversation moves.
  • Nest forwards soot.run, soot.action and soot.ask only right after the person clicks or types in the screen; calling them on load or from a timer is refused with gesture_required. soot.view and soot.asks need no gesture, and neither does following an ask already sent (the same request_id, after a reload).
  • A missing key, a wrong key or a failing service all arrive as an error with a code and a message a person can read. When a key is missing (credential_missing), Nest says so itself at the top of the screen with an "Open the key vault" button, so the screen only says briefly that it could not; for any other error the screen shows err.message.

Declaration

ui/translate/piece.json, written last:

JSON sample · not a command
{
  "id": "translate",
  "slot": "rail",
  "label": {"vi": "Dịch", "en": "Translate"},
  "icon": "globe",
  "order": 300,
  "access": "operator",
  "data": {
    "queries": {
      "terms": {"source": "table", "table": "glossary", "order": "term", "limit": 100}
    },
    "actions": {
      "translate": {"tool": "translate"},
      "add_term": {"table": "glossary", "op": "insert"}
    },
    "ask": true
  }
}

  • queries are the named reads (task, table, file, need, outcome, memory, or {source: "tool", tool} for a GET read tool of the owner). At most 8.
  • actions are the named actions: {tool} calls a tool of the owner, {table, op: "insert" | "update" | "delete"} writes a table within the owner's write access. At most 8. insert takes {rows: [{column: value}]} and answers {ids}.
  • ask: true lets the screen ask the owning Soot. Off by default.
  • The tool must be written before piece.json: an action pointing at a tool that does not exist refuses the save with tool_unknown.

The write's result carries the note {"screen": "soot:writer:translate", "saved": true, "state": "proposed", …}.

The person approves once

The first save raises one item in Cần bạn (Needs you) for the screen and the tools it uses. The card shows where the screen sits, who sees it, what it reads and which buttons it has; and for each tool: what it does (only reads, or sends and changes data), the method and the host it sends to, which keys it needs (title and name) and whether each is set ("Đã có" / "Chưa có", set / not set). A key already set that this version would send to a new host is said right above the approve button; a host the key's field named when the person typed it is not new. A key that is not set gets one secret field and a "where to get the key" link, which asks the person to confirm its host before it opens. The person enters the key, presses "Lưu khóa" (Save key; the value goes straight to the runtime and the field clears), then "Duyệt và đặt vào Nest" (Approve and place in Nest): the screen shows in the side bar and the tool can run.

The Soot never sees the key and never asks for it in chat. Approving without the key is allowed; the first translation then says the key is missing and Nest takes the person to the key vault.

Once placed, the Soot may change the look freely and new versions go live at once. But adding a host or a key, changing the method, going from read to write, adding an action with a new target, changing a memory query's search, turning ask on, or changing the slot or who sees it is refused (approval_needed); to reach further, save under a new id so the person is asked again.

Answering a question from the screen

A question reaches the Soot as a message in the viewer's own conversation: the first line is Hỏi từ màn hình “Dịch” (asked from the screen “Dịch”), then the question, then the screen's data as a JSON block. The Soot answers as it answers any message: its last message is reply.text. This run also has the piece_reply tool; the Soot calls it with data holding one JSON value (written as a string, at most 16 KiB) so the screen gets structured data, here {"translation": "…"}. The person can open that conversation from the screen's header ("Mở cuộc trò chuyện", Open the conversation) and keep typing there.

The operator's question runs in the owner's workspace, so the Soot can use its own tool (tool_translate) and the glossary. A member's question runs in the member's own place, without the owner's tools or keys.

Trying it

  1. Let the Soot select the soot-nest pack (it ships with the runtime): its nest-pieces skill teaches exactly these steps. A Soot that selects read already has the storage and data tools.
  2. Tell the Soot what you need. It writes the files and says the item waits in Cần bạn.
  3. Open the card, preview the screen, enter the key, approve. Open "Dịch" in the side bar, translate a sentence, ask the Soot a question.
  4. Without Nest, open http://<runtime>/v1/pieces/soot:writer:translate/ in a browser to see the screen; that shell is at bridge level 1, so soot.run and soot.ask work only in Nest.

The full guide for written pieces (every query source, the lifecycle, the kit) is Screens a Soot makes (written-pieces, in the repository).

Path 2: a pack brings the screen

The example below is a minimal pack, hello-board: a "Board" section in Hộp việc, read by one tool, with a second tool that pins a line. soot init-pack hello-board --with tool creates the folder; the four files below are all the rest.

Sample text · not a command
hello-board/pack.json
hello-board/tools/board.mjs
hello-board/ui/board/index.html
hello-board/ui/board/app.js

Declaration

pack.json. Pieces sit in interface.pieces; data.view_tool and data.action_tool name two tools of this same pack.

JSON sample · not a command
{
  "name": {"vi": "Bảng tin", "en": "Board"},
  "description": "A first piece: one section of the inbox, served by two tools.",
  "tools": [
    {
      "name": "board_view",
      "description": "List the board's lines, optionally filtered by q.",
      "parameters": {"type": "object", "properties": {"q": {"type": "string"}}},
      "run": {"program": "node", "args": ["tools/board.mjs", "view"], "stdin": "context", "mode": "read"}
    },
    {
      "name": "board_pin",
      "description": "Pin one line of the board.",
      "parameters": {"type": "object", "properties": {"pin": {"type": "string"}}, "required": ["pin"]},
      "run": {"program": "node", "args": ["tools/board.mjs", "pin"], "stdin": "context", "mode": "write"}
    }
  ],
  "interface": {
    "pieces": [
      {
        "id": "board",
        "slot": "home",
        "label": {"vi": "Bảng tin", "en": "Board"},
        "icon": "pin",
        "order": 200,
        "access": "operator",
        "bundle": "ui/board/",
        "data": {"view_tool": "board_view", "action_tool": "board_pin"}
      }
    ]
  }
}

  • A piece's id is English, lower case with hyphens, unique in the pack. A pack declares 1 to 8 pieces.
  • access is operator (the operator only) or member (also members who reach the Soot that serves the piece).
  • bundle is a directory in the pack that holds index.html, 5 MiB at most.
  • The read tool must have run.mode: "read"; both tools take run.stdin: "context". A tool that needs approval (approval) cannot be a piece's tool: a screen does not draw an approval step.
  • An unknown field is an error. interface.pages is the older name and no longer loads; the load error says how to move to pieces.

The read tool and the action tool

The runtime runs a tool with one JSON object on stdin and reads one JSON object from stdout. Besides the input the screen sent, the tool gets piece (the serving Soot, the piece id, and mode: view or action) and viewer (who is looking).

tools/board.mjs:

Sample text · not a command
import { readFileSync } from "node:fs";

// stdin: {piece: {soot, piece, mode}, input, viewer: {kind, id}, ...}
const ctx = JSON.parse(readFileSync(0, "utf8"));
const input = ctx.input ?? {};
const LINES = [
  { id: "release", text: "Release 1.4 ships on Friday" },
  { id: "interview", text: "Interview the support candidate at 14:00" },
];
const reply = value => console.log(JSON.stringify(value));

if (process.argv[2] === "view") {
  const q = String(input.q ?? "").toLowerCase();
  const lines = LINES.filter(line => line.text.toLowerCase().includes(q));
  reply({ lines, total: lines.length });
} else if (LINES.some(line => line.id === input.pin)) {
  reply({ pinned: input.pin });
} else {
  reply({ error: "no such line", reason: "invalid_input" });
  process.exit(1);
}

  • Treat input as untrusted: it comes from a page in a sandbox, so check it like any other input.
  • The tool runs as the Soot that serves the piece, with the same grants and credentials as when that Soot calls the tool itself. The screen adds no access.
  • An action runs exactly once per request_id. Sending the same id again returns the earlier result; the tool does not run twice.
  • Never return a secret from a read: Nest keeps the last result on the viewer's device so a screen opened again shows at once.

Bundle

A bundle is an ordinary web page. The two links _kit/piece.css and _kit/piece.js are served by the runtime in every session: the kit handles the bridge to Nest, and colours and type that follow Nest, light and dark. The bundle's CSP blocks inline script and style, so the script is its own file.

ui/board/index.html:

Sample text · not a command
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Board</title>
<link rel="stylesheet" href="_kit/piece.css">
<p id="state" class="muted">Loading…</p>
<ul id="lines" class="list"></ul>
<script src="_kit/piece.js"></script>
<script src="app.js"></script>
</html>

ui/board/app.js:

Sample text · not a command
const state = document.getElementById("state");
const list = document.getElementById("lines");

function draw(out) {
  list.replaceChildren(...out.lines.map(line => soot.el("li", { class: "row" },
    soot.el("span", { class: "grow" }, line.text),
    soot.el("button", { type: "button", onclick: event => pin(event.target, line) }, "Pin"))));
  state.textContent = out.total ? out.total + " lines" : "Nothing here yet.";
}

async function pin(button, line) {
  button.disabled = true;
  try {
    await soot.action({ pin: line.id });
    button.textContent = "Pinned";
  } catch (err) {
    button.disabled = false;
    state.textContent = "Could not pin: " + err.message;
  }
}

// Opened again: draw the last result at once, then read fresh data.
soot.ready(() => { const last = soot.cached({}); if (last) draw(last); });
// Reads again on a change, when shown again, and every minute while shown; rests while hidden.
soot.live(async () => {
  try { draw(await soot.view({})); } catch (err) { state.textContent = "Could not read: " + err.message; }
});

A pack piece calls soot.view(input) and soot.cached(input) without a name; a written piece calls them by query name. The rest of the kit is the same for both.

Trying it

  1. Put the pack folder in the workspace's packs_dir and let a Soot select it: {"packs": ["hello-board"]}.
  2. soot check --show loads the pack as the runtime will. A wrong piece declaration is reported as piece_invalid with the piece and the reason (tool_missing, view_not_read, stdin_not_context, bundle_missing, bundle_too_large, tab_required, unknown_slot…).
  3. Run the tool by hand with what the runtime will send (the command below); it must print one JSON object.
  4. Start the runtime and open Nest: the piece is in Hộp việc at once, with no question asked, because the operator already selected the pack. Without Nest, open http://<runtime>/v1/pieces/pack:hello-board:board/ in a browser: it is a shell page that builds the same frame and bridge as Nest and asks for an operator key once (the runtime's own origin must be in server.browser_origins).
  5. Edit the bundle and open the screen again. An open frame keeps the earlier copy for up to 10 minutes (the life of a session).
Terminal · review before running
echo '{"piece":{"soot":"helper","piece":"board","mode":"view"},"input":{"q":"release"},"viewer":{"kind":"operator","id":"operator"}}' | node tools/board.mjs view

Release the pack like any other; see Agents, teams, packs, Forge.

What the operator decides

Other people's screens run in your Nest, so the last word is yours.

  • A screen a Soot wrote must be placed by you. The first time, it is an item in Cần bạn: you see a preview, where it will sit, who will see it, what it reads and whether it sends actions, then place it or decline. When you decline, the Soot is told and does not ask again until it changes the content.
  • Once placed, it does not reach further by itself. The Soot is free to change the look and the filters, but it cannot change the slot, who sees it, whether it sends actions or which data it reads on a screen you approved.
  • Going back and removing. Every written screen has a version history; you go back to the earlier version or remove it from Nest on the screen itself. A new version that fails to load twice on your device, and never loaded, is rolled back by the runtime to the last good one.
  • A pack's screen follows the pack. It is there when a Soot selects the pack and gone when it does not. Selecting a pack is your decision, so Nest asks nothing more.
  • The layout is yours. Cài đặt › Màn hình (Settings › Screens) lets you order and hide each screen; the layout lives on your device. A Soot can only propose a layout, and you apply or decline it.
  • You approve tools and keys. _[0.19.0]_ When a screen uses a tool a Soot wrote, its card says what each tool does (only reads, or sends), which method and host it sends with and which keys it needs, set or not. A key that is not set can be entered right on the card, or later with "Mở Kho khóa" (Open the key vault) when the screen says it is missing. You can approve without the key; the tool runs only once the key is set.
  • See which one is heavy. Also in Cài đặt › Màn hình: how long each screen takes to open on this device, how often it failed to open in time, and which read was too large.

Limits and safety

  • A sandboxed frame. Each screen runs in a frame of its own, with no credentials, no network calls (connect-src 'none') and no form posts. It talks to Nest only over the postMessage bridge, and Nest passes a call only to that same piece.
  • What a frame can still do. A CSP cannot stop a page from navigating itself. When a frame leaves its bundle, Nest closes it and counts a failed load, but the address it went to has been requested. So treat what a screen can read as something its author can read: place screens only from Soots and packs you trust, as when you grant them access.
  • No access of its own. The owner's access is the ceiling, checked at save and again on every call. A screen cannot grant itself any permission, cannot read a key, and learns that a key is missing only from the runtime's answer to a call.
  • Opening links. soot.open and an <a> tag ask Nest to open a link. Nest accepts one only while the screen is shown, at most once a second, and never opens Nest's own browser frame for a screen.
  • The numbers. A bundle is 5 MiB at most; in home, script and style are 512 KiB at most. Call soot.ready() within 1 second (over 5 seconds is a failed load). Each read returns under 256 KiB. The same read reaches the runtime at most once a second while shown and once every ten seconds while hidden; after an action, or when the runtime says something changed, the next read always reaches the runtime. Written pieces: at most 8 per owner, 8 queries per piece, 10 actions a minute. _[0.19.0]_ Actions and questions count together: 10 a minute per viewer, 30 for the whole piece; the input of soot.run and soot.ask is 8 KiB at most, a question's text 4000 characters. Written tools: at most 16 per owner, 30 calls a minute per tool, an answer of at most 256 KiB, a wait of at most 60 seconds (20 by default).
  • Light by default. Nest opens a frame only when it is about to come on screen, at most 4 at once; a hidden frame sets no timer and asks the runtime nothing. Use soot.live instead of a timer of your own.

When Soot and Nest move to a new version

A screen you make today keeps running on later versions. Four things to know:

  • `kit`. The manifest may say "kit": 1: the version of the kit the bundle was written for. Leaving it out also means 1, and that default never moves. A runtime that does not serve the version you name refuses with kit_unsupported and says which one it serves.
  • Later additions. The bridge between a frame and Nest has a level (soot.level). Nest 0.18.0 is at level 1; level 2 adds soot.run, soot.ask and soot.asks. A feature added later carries a higher level. A screen that wants it checks soot.level first, so it still runs on an older Nest: at level 1 the kit refuses those three calls with unsupported and sends nothing.
  • Nest's messages may gain fields. Nest may add a field to one of its messages (init, result, …) without a level change. A screen that uses the kit has nothing to do: the kit reads only the fields it needs. A bundle that speaks the bridge itself must ignore a field or a message type it does not know, and never check a message against a fixed list of fields: such a screen breaks the next time Nest adds one.
  • Breaking changes. They always carry a new kit number and take two releases: the first serves both the old kit and the new one, and only the next drops the old one. In between, the runtime tells the owner Soot so it can rewrite its screen; a pack ships a new version on Forge.

The full rules are in the pieces standard, under versions and migration.

When something goes wrong

What you seeWhyWhat to do
Writing piece.json answers saved: falsereason names the problem and message says how to fix itFix it and write piece.json again
approval_neededA placed screen is reaching further than the version the person approvedKeep the reach as placed, or save under a new id
kit_unsupportedThe manifest names a kit version this runtime does not serveLeave kit out or write the version the error names; if the screen needs a newer kit, update Soot
soot check reports piece_invalidA pack's piece declaration is wrongRead reason and the pointer to the field
retired_field at /interface/pagesThe pack still uses the older nameMove to interface.pieces as the error's hint says
A blank frame, then "did not open in time"The page did not call ready within 5 seconds, usually because an inline script was blocked by the CSPMove the script to a file and link _kit/piece.js first
tool_refused with approval_requiredThe piece's tool needs approvalUse a tool that needs none for a screen
429 busyAll pack pieces share 8 tool slotsNest retries by itself; keep the read tool fast (under 500 ms)
rate_limitedMore than 10 actions a minute on one written pieceWait for retry_after
owner_unavailableThe screen's owner cannot take work nowNothing was sent: let the person try again later
ask always answers owner_unavailableThe owning Soot is only a member of a team, not a Soot a direct conversation can open withLet that Soot stand alone or be one of the team's entries (entries); or let the coordinator write the screen at the team's level
gesture_required _[0.19.0]_The screen called soot.run or soot.ask on load or from a timer, not right after a click or a key press by the personCall those two only from a click handler; read on load with soot.view and soot.asks
A button inside a <form> does nothingThe frame has allow-scripts only, no allow-forms: the submit event never arrivesDrop the <form>; use button type="button" with a click handler
A bundle that speaks the bridge itself breaks after a Nest updateThe screen checks Nest's messages against a fixed list of fieldsIgnore fields and message types it does not know; or use the kit
"Mở cuộc trò chuyện" (Open the conversation) goes to the wrong placeThe screen builds the link from run_id or another idA question's conversation is the conversation_id in its result (32 hex characters): soot.open("nest://conversation/<conversation_id>")
credential_missing _[0.19.0]_The tool's key has not been enteredThe person enters the key on the card or in the key vault ("Mở Kho khóa" shows on the screen); never send a key in chat
credential_rejected _[0.19.0]_The service answered 401 or 403: the key is wrong or expiredThe person replaces the key in the key vault
upstream_error, timeout, request_failed _[0.19.0]_The service answered an error, took longer than timeout, or could not be reachedRead status and body (the key is removed); check url and body against the service's documentation
Saving tool.json is refused _[0.19.0]_reason names the problem: run_invalid, method_needs_write, host_not_declared, credential_not_declared, input_invalid, manifest_invalid, approval_needed…Fix exactly the field message names and write tool.json again
Saving piece.json answers tool_unknown _[0.19.0]_An action or query points at a tool not written yet or retired, or a query reads a tool that does not use GET (write, or read with POST)Write tools/<id>/tool.json first, then write piece.json again
The screen does not change after an editAn open frame keeps its earlier sessionClose the screen and open it again

Content reviewed: 2026-11-12