Bolter Connect

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Replace one slide's HTML. This is THE way to change slide content. Rewrite the whole slide fragment, do not recreate the deck. Pass the slide's current rev (from bolter_get_deck) as expectedRev. If it does not match, someone edited that slide since you read it: the call fails and returns the current rev + html so you can re-read, reconcile, and retry. On success the slide's rev increments. If the slide is protected (see bolter_get_deck's protected flag) this refuses immediately and permanently. A protection is set by a person in the deck viewer, has no expiry, and no tool can clear it, so retrying will not help and you will not be woken. SLIDE HTML: each slide is an HTML fragment rendered into a fixed 1280x720px canvas. Use normal, modern HTML + inline CSS or classes styled from themeCss. Prefer flexbox/grid flow layout over absolute pixel positioning. The canvas is fixed-size but content should lay itself out so it never overflows. You are excellent at this; write the slide the way you would write a clean web page section. - Root each slide in a single container that fills the canvas (e.g. <section style="width:100%;height:100%;display:flex;flex-direction:column;...">). - To push items to opposite ends of a row (e.g. a footer's label on the left and page number on the right), the ROW must be full-width: give it width:100% or align-self:stretch. justify-content:space-between does nothing on a shrink-wrapped row — a common bug is the page number ending up jammed against the label. - Let boxes size to their content. Don't pin a fixed height (or force equal-height grid rows) that the copy can outgrow, or the text spills out / clips. For card grids prefer grid-auto-rows:min-content + align-content:start so each row grows to its tallest card. - Shared look (fonts, colors, reusable classes) goes in themeCss ONCE; slides reference it. themeCss may @import fonts only from fonts.googleapis.com. - If the user wants a specific font that isn't on Google Fonts (e.g. a brand/corporate typeface), ask them to upload the font file, then attach it with bolter_add_deck_font before referencing the family. - Images: <img src="https://..."> or small data: URIs. Every src must be a url a tool actually returned, bolter_add_deck_media for a file someone shared, bolter_generate_image (if you have it) for a generated one. Never hand-assemble an image url and never paste a Files link (https://<org>-<bucket>.bolter.page/<path> or the older https://bolter.page/<org>/<bucket>/<path> form): Files links are access-controlled, so they load for you and 403 for the rest of the deck's audience. Both are rejected on save. No scripts, no event handlers, no iframes; those are stripped on save. - Keep each slide's HTML under ~200KB. DESIGN (a good deck looks designed, not generated): - Design tokens (set on themeCss, referenced as var(--…) in slides): colors --bg --fg --muted --accent --accent-contrast --surface; fonts --font-head --font-body; type scale --fs-display --fs-title --fs-heading --fs-body --fs-caption; spacing --pad --gap. When authoring your own themeCss, declare tokens on `:root,:host,[data-deck-v3-slide],#deck-slide` so they resolve identically in the viewer, screenshots, and export. Body text stays >=18px; never put text below ~14px. - Density: split, don't shrink. About one idea per slide, <=6 bullets or <=6 cards. If it won't fit, add another slide rather than shrinking type until it's cramped. - Titles: declarative, one consistent grammatical style across the deck, readable as a standalone sequence. Avoid "It's not X. It's Y" verdict/punchline titles. - Aesthetics: commit to 1-2 colors plus one sharp accent; a distinctive font pairing beats default Inter/Roboto/Arial; avoid the generic purple-gradient-on-white look. The themePreset library already encodes tasteful, consistent choices for you. - Structure: for an analytical slide (a comparison/scorecard, a 2x2, a waterfall, an exec summary, a roadmap, a driver tree, before/after), load its pattern with bolter_get_slide_pattern FIRST and build from it, and give it an action title that states the conclusion, not the topic. COMPONENTS. A themePreset ships a small design system; USE its classes instead of hand-styling every element inline. Bare inline-styled text dropped on an empty slide is the #1 reason decks look unfinished, compose with these instead: - Layout: .slide (the root: flex column, padded), .grid with .grid-2 / .grid-3 (column layouts), .card (a surface panel), .footer (a bottom meta line, pinned via margin-top:auto). - Type & emphasis: .display (a hero number/headline), h1 / .headline, h2, h3, .eyebrow (uppercase kicker), .dek (subhead/lede), .metric (a big accent stat), .muted, .accent. - .metric and .display are DISPLAY size (~72px). Use them ONLY for a SHORT value: a number or 1-2 short words ("12k", "+71%", "Q4", "~10 wks"). NEVER put a multi-word phrase in .metric/.display inside a grid card, a long word won't fit the narrow column and breaks mid-word (e.g. "expansi​on"). A CARD TITLE is a heading: use <h3> (or h2), never .metric. - Compose with these classes + the type-scale tokens (var(--fs-*)); reach for a raw inline style only for a genuine one-off. (If you author bespoke themeCss instead of a preset, define equivalent classes there.) - Example of a NUMERIC stat/info slide (never render key numbers as a lone floating line): <section class="slide"><div class="eyebrow">The quarter's headline</div><h1 class="headline">Active homes crossed 12,000</h1><div class="grid grid-3"><div class="card"><div class="metric">12k</div><div class="muted">End of Q3</div></div><div class="card"><div class="metric">7k</div><div class="muted">Start of quarter</div></div><div class="card"><div class="metric accent">+71%</div><div class="muted">Net growth</div></div></div></section> - Example of a TEXT-driver slide (card titles are headings, NOT .metric): <section class="slide"><div class="eyebrow">What drove the quarter</div><h1 class="headline">Three forces behind the growth</h1><div class="grid grid-3"><div class="card"><h3>Retail expansion</h3><div class="muted">New big-box presence in two regions lifted installs.</div></div><div class="card"><h3>Utility partnerships</h3><div class="muted">Rebate programs made us the subsidized default.</div></div><div class="card"><h3>App onboarding</h3><div class="muted">Shorter setup lifted 30-day activation.</div></div></div></section> COMPOSITION & minimalism. Minimalism is good when it is DELIBERATE and CORRECT, never sparse-by-accident. Match density to the slide's job: - A title / section / speaker slide can be minimal and elegant, a few well-placed words with balanced whitespace. That is a feature, not a defect. - An INFORMATION or DATA slide must present its content clearly: group related figures, give each key number a visual home (a .metric in a .card), and prefer a small chart or a designed before/after comparison over loose floating text. - Correctness ALWAYS: never strand an element (a lone arrow, rule, or number) in empty space with nothing tying it to its neighbours; keep everything on a shared grid; use ONE consistent type system across the whole deck.

bolter_edit_slide

Finds the agent's Bolter chats by name, for @-mentioning one in ChatGPT.

bolter_search_mentions

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. List conversations the agent is in, filtered by metadata. Useful for "conversations I share with these people" or "conversations active this week". Cursor-paginated by lastActivityAt descending.

find_chats

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Get the preview URL for a service running in a sandbox. The preview URL is reachable by whoever the port's access policy allows. The result's display states the port's actual audience; relay that to the user. The URL only works while a process is bound to the port, and the rail preview auto-wakes the sandbox when the user views it. Any preview you show a user MUST be served by a bolter_sandbox_service_put service with autoRestart, or it will be dead (and show a "not responding" card) when they come back after the sandbox hibernates. Do NOT back a preview with a bolter_sandbox_exec-started server; those die on cold resume. To show the preview, call bolter_create_artifact with sandboxPreview and the returned sandboxName and port (it builds the URL itself; there is no url to pass). This pins a live iframe to the context rail. If the user wants to share it, bolter_app_create on this sandbox and port, then bolter_app_publish.

bolter_sandbox_preview_url

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. List the immediate children of a directory (default first 100; page with offset/limit). The bucket root ("/") always exists implicitly. Requires read at the path. Each child includes a `url` field — the user-facing https URL for that file or sub-directory. For a specific file, use files_search instead of listing.

files_list_dir

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. List this workspace's apps. `mine` is true for apps you created (only those can you publish or share). Use to find an app's slug before publishing it (bolter_app_publish) or sharing it with a chat, person, agent, or link (bolter_app_share). Two addresses, each with who it opens for: `url` (the app's own address) opens only for people signed in to Bolter whom the app is shared with, and shows everyone else a sign-in page; `shareUrl` (the share link, present only when a share link is on) opens for anyone who has it, no account needed. To give the app to someone outside the workspace, give `shareUrl`, not `url` (unless `urlOpensFor` says the app is public); when `shareUrl` is null, follow `linkNote`. Copy a URL exactly as returned: the random suffix on a slug (the -lf6112 in market-swarm-lf6112) is part of the address.

bolter_app_list

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. List the blueprints this workspace owns, published or not, each with who can see it, the version published, how many workspaces have installed it, and whether an installed copy is running an older version. Call this before revising a blueprint: it reports the id and the revision bolter_update_blueprint needs, and it is the only way to name a blueprint that has never been published, since one has no link to reach it by. Also call it before composing a new blueprint, to check the workspace does not already have one that fits.

bolter_list_blueprints

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Find files matching a glob pattern in a sandbox (default first 200; page with offset/limit). Always narrow the glob: the sandbox enumerates every match before paging, so an unbounded pattern like "**/*" against node_modules is expensive no matter the limit. Scope the pattern to the directory/extension you need.

bolter_sandbox_list_files

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. List available sandboxes. Shows sandbox name, ID, status, and when it was last active. Sandboxes are owned by you, not by a chat. This lists all of them regardless of which chat they were created in. Sandboxes created by one of your apps through the platform show their parent and kind (scratch or durable); those belong to the app and are deleted with the parent.

bolter_sandbox_list

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Publish an app you created: give it its URL, front door and card on the sandbox port it was created on. Publishing GRANTS THIS CHAT that one served port: everyone here, including a member from outside your workspace and anyone who joins later, can reach it. Any other ports it serves (admin/debug/dev) get no grant. The grant is ADDITIVE, not a lockdown: it does not remove whatever your sandbox already admits, so people your own audience covers may be able to open it too. Never tell anyone the app is limited to this chat. The card states the real audience; read it there. Publishing needs nobody's permission, so do NOT ask the user whether to publish, and do NOT ask who should see it: the card carries a sharing control, and widening to the whole workspace or to a public link is one press there by an owner or admin. Publish ONCE per app: to share an ALREADY-published app with another chat, a person, or an agent, use bolter_app_share — re-publishing is not how audiences widen, and it will not pin the app into a different chat. Only the agent that created the app can publish it. Build and run the app in a sandbox first (bolter_sandbox_* — declare the server via bolter_sandbox_service_put so it survives hibernate/resume), confirm it is listening on the port, then call this. The app then serves directly from that sandbox at the returned url, and the chat preview is pinned to it. The result reports what the port actually answered: `live: false` means the port did not answer the probe, so the app is bound but nothing was seen serving it. Do not call an app live, or hand over its link, on a result that says otherwise. Publishing supersedes the live sandbox preview: the matching sandbox_preview card for that sandbox is removed from the rail, leaving a single card (the app) — never keep both. To move the app to another sandbox (for example after its sandbox's storage was lost), pass sandboxName and port. Do not set X-Frame-Options or a frame-ancestors CSP that excludes the Bolter origin: the chat embeds the live preview in an iframe.

bolter_app_publish

Add an emoji reaction to a message, by its id (short 8-character form preferred). Use it to acknowledge a message without posting a reply.

bolter_react_to_message

The agent's settings in Bolter: its name, and whether ChatGPT is getting its messages.

bolter_settings_read

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Read a blueprint file, by exactly one of two keys. Give it a slug to read the PUBLISHED blueprint that slug names, which is what arriving from a blueprint link looks like; that blueprint belongs to whoever published it and is not stored here, so do not go looking for the file in this workspace. Give it a blueprint_id, from bolter_list_blueprints, to read one of this workspace's OWN blueprints in full: the markdown working copy, its presentation record (the page a visitor reads, which bolter_set_blueprint_presentation writes) and the revision number bolter_update_blueprint and bolter_set_blueprint_presentation need. Use the id form before revising a blueprint, and again if an update was refused because the revision moved. Pass one key or the other, never both and never neither. An unknown, withdrawn or not-visible slug all return not_found.

bolter_read_blueprint

Read messages in one chat, oldest to newest. Pass the chat as groupId (short 8-character id preferred). lastN reads the most recent messages; around with nBefore and nAfter reads the context of one message; since and until read a time range. Pass the cursor a result returns to read further.

read_chat

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Read a v3 deck. Returns the manifest (title, viewport, and each slide's { id, rev, bytes }) plus the full HTML of the slides you name in slideIds. Omit slideIds to get the manifest only, a cheap way to see structure before pulling a specific slide's HTML to edit it. Always read a slide (to get its current rev + html) right before bolter_edit_slide. Reads are budgeted: if you request more slide HTML than fits one read, this returns full HTML for a contiguous prefix of your slideIds and lists the rest in omittedForSize (with their rev + bytes). Request those in a follow-up bolter_get_deck call, fewer at a time. HTML is always returned whole, never cut off mid-fragment. Pass version to read a specific historical version instead of the current head (find version numbers with bolter_list_deck_versions). A historical read is inspection only; it does not change what's live. To make an old version live, use bolter_restore_deck_version. A slide marked protected:true was protected by a person in the deck viewer: you cannot change its HTML, delete it, or move it, and there is no tool that removes a protection. protectedBy names who set it. Plan around protected slides rather than attempting a write you know will be refused, and if the user's request needs one changed, say who protected it and ask them to remove it.

bolter_get_deck

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Load a deck THEME (design system) before authoring. A theme is the STARTING POINT for a new deck or a redesign: read its guide first, then compose every slide FROM it. Call with a preset id to get that theme's design guide (palette, components, treatments, do/don'ts), its themeCss, and one example slide. Call with no preset to list the available themes. Valid ids: grove, daisy-days, neo-grid-bold, mat, signal, soft-editorial, cobalt-grid, slate, meridian.

bolter_get_deck_theme

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Read a file. Without version, returns head; with a version, returns history (or RetentionPrunedError if pruned). Requires read at the path. The response includes a `url` field — the user-facing https URL for this file. Returns the most useful form for each MIME: text-tier files come back as a raw-text window (encoding=utf8, default first 160 lines / ~6K chars; page with offset/limit). complete=false means you have only part of the file: the notice and more fields say which lines and the next offset. Every read carries the stored file's sizeBytes and sha256. When pagesReassembleFile is true, concatenating every page's content in order, adding nothing between them, reproduces the file byte for byte. To find the right file or the right part of a file, use files_search first rather than paging through it. office docs (docx, pptx, xlsx) come back as extracted text, windowed the same as text files (encoding=utf8, default first 160 lines / ~6K chars; page with offset/limit); text-shaped blobs (svg, etc.) come back decoded as utf8, also windowed (encoding=utf8); one that is not valid UTF-8 carries a decodeNotice saying the text is not the stored bytes; image/* (jpeg, png, webp, gif) and application/pdf come back as base64 in the JSON body PLUS a vision content block attached to the tool result so the model can actually look at them; other binary mimes (zip and the like, and audio or video you are not given as a content block) come back as base64 (encoding=base64), up to 16MB; a larger one returns FileTooLargeToReadInline, so use files_download_to_sandbox for it. A files URL is NOT public: it opens only for people who already have access, and shows everyone else a sign-in page. The `audience` field in the response says which. Treat anything other than "anyone_with_link" as sign-in-gated, and never describe such a link as public or as one anyone with the link can open. To get a link that works for someone outside the workspace, call bolter_request_files_grant with principal "public", which posts a card a human approves in one click, or tell the user they can create a private link for the file themselves from its access panel in Files. You cannot make a path public yourself, and files_grant has no principal for a person without an account.

files_read_file

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Read a single memory block by label, from your own private memory. Default returns the content (capped at 16384 chars; truncated=true when the block is larger). For long blocks, narrow with section=head|tail|around_match (with `match` for the latter) and n_chars to bound the slice. Returns content + kind + freshness metadata. For the workspace memory, use read_workspace_memory instead.

read_memory

Read one message in full, by its id (short 8-character form preferred). Use it when a message you were given or read was cut short.

read_message

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Read a windowed slice of a text file from a sandbox (default first 160 lines; use offset/limit to page). If you are looking for something specific in a file or across files, use bolter_sandbox_search_files FIRST and read only the region around the hits — do not page through whole files. Line numbers in the output are display-only: never include them in bolter_sandbox_edit old_string. Lines over 500 chars are shown wrapped across several numbered lines, and offsets count the wrapped lines (so after a long line they run ahead of bolter_sandbox_search_files line numbers); the wrap breaks are not in the file. Image files (png, jpg, webp, gif) are returned as visual content blocks you can inspect directly.

bolter_sandbox_read

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Read a single workspace memory page by label, or page through one already open with `cursor` (from this tool's own nextCursor, or from a search_workspace_memory hit's cursor, which always opens the page from the top). Default section='full' returns the page in n_chars windows: check hasMore and pass nextCursor back to keep reading. For a one-shot slice instead of paging, use section=head|tail|around_match (with `match` for the latter). Every call reports the page's full outbound [[links]], backlinks, and resolved @mentions, not just what falls inside the current window.

read_workspace_memory

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Read cursor-paginated output from an async exec session. Pass the session_id from the running response (or from an inline response when wait_ms was set). stdout and stderr have INDEPENDENT cursors because they grow at different rates. Pass each next_cursor back on the subsequent call. Returns stdout_chunk + stdout_next_cursor + stderr_chunk + stderr_next_cursor + eof.

bolter_sandbox_session_output

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Fetch the most recent supervisor-captured stdout/stderr for a service. Returns the last 100 lines.

bolter_sandbox_service_logs

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Rename yourself: change your own display name in Bolter, the name on your profile and beside your messages, in mentions and in member lists, in every chat you are in. Use it whenever you are asked to go by a different name, to be called something else, or to change your name. If you run outside Bolter, also use it to name yourself after the app you run in, spelled the way that app spells it ("Grok Bot", "Dot", "Claude Code"), not after the model underneath it. Your personality is separate: never rewrite it to change your name. The name must not be one another agent or a person in your workspace already has, must be at most 30 characters, and not a reserved name. Everyone in your chats sees the new name straight away, on your earlier messages too.

bolter_set_name

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Run a shell command in a sandbox. The command runs under bash, from /workspace unless you pass `cwd`. READ THE RESULT BEFORE ACTING ON IT: `termination` says how the process ended. "exited" means it finished and `exitCode` is its real status. "timed_out" or "signalled" mean it was KILLED — it did not finish, `exitCode` is null, and any stdout is partial output, not a result. Never report or build on the output of a killed command; re-run it with a bigger budget or as a service instead. A sandbox with a code run in flight belongs exclusively to that run: calls against it are refused until the receipt arrives, so wait rather than hand-editing its files. Two modes. SYNC: omit wait_ms; the tool blocks up to `timeout` ms (default 30000, max 610000). ASYNC: set wait_ms (0-60000); the tool returns inline if the command finishes within wait_ms, otherwise returns kind="running" with a session_id and the agent is woken with a [sandbox callback] system message when the session ends. ASYNC also accepts max_runtime_ms (max 1800000 = 30 minutes, default 30 minutes). An in-flight session — SYNC or ASYNC — keeps the sandbox alive: idle hibernation does not fire while a session is running. Use ASYNC for long installs, multi-minute builds, or anything that might exceed 60s; prefer it over shell backgrounding (`nohup … &`), which does NOT register as a live session and so does NOT prevent hibernation. Do NOT launch long-running servers/daemons here. Register them via bolter_sandbox_service_put instead. The async cap is hard: max_runtime_ms tops out at 1800000 (30 minutes). Any job expected to run longer than 30 minutes — not just servers, but multi-hour batch jobs too — must run as a bolter_sandbox_service_put service, which survives hibernation and is supervised; async exec would be killed at the cap mid-run. Secrets: write the placeholder `{{bolter.token:NAME}}` (a granted secret name) anywhere in the command or env and Bolter expands it to that grant's proxy token host-side, before the command runs — never paste a token in yourself. Use `{{bolter.value:NAME}}` for the raw secret (raw-readable grants only).

bolter_sandbox_exec

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Declare or update a long-running service inside a sandbox. Use this for any server, daemon, or worker process, and for any batch job expected to run longer than the bolter_sandbox_exec async cap of 30 minutes (e.g. multi-hour data passes) — async exec is hard-killed at max_runtime_ms <= 1800000, so anything longer must run here. Services declared here are restarted automatically when the sandbox resumes from hibernation, and supervised so they restart on crash. Prefer this over bolter_sandbox_exec for anything that needs to keep running or that runs longer than 30 minutes. Every call is the WHOLE declaration and replaces the previous one: to change one env var, resend the command, the full args and every env var with it, because whatever you leave out is cleared, not kept. The result's `declared` block shows the command, args and env names now in force; check it. Re-declaring a running auto_restart service always stops the old process and starts a fresh one, so this is also how you make a running server pick up code you just changed. There is no port parameter: the process binds its own port (pass PORT in env if your server reads it). A service is NOT a keep-alive: never declare a sleep, busy loop or idle heartbeat whose only effect is to stop the sandbox sleeping through a wait (a live browser session, a person fetching a 2FA code). That is what bolter_sandbox_keep_awake is for. A keepawake wrapper around a real job that finishes (below) is different: the hold is the job's own lifetime, nothing is kept alive for its own sake. Supervised does not mean uninterrupted: a service generates no inbound activity, so a sandbox running only a service still hibernates a few minutes after your turn ends, and the process is restarted from the beginning on the next wake, not resumed. For a job that must run to completion with nothing calling into the sandbox meanwhile (a multi-hour batch pass, a one-off worker that drains a queue and exits), declare it as command "keepawake" with the real command and its arguments in args, AND set auto_restart: false and on_exit_notify: true, e.g. command "keepawake", args ["python3", "tag_cards.py"], env {}, auto_restart false, on_exit_notify true. keepawake is on every sandbox's PATH; it holds the sandbox awake for exactly as long as the wrapped process runs and releases the moment it exits, and on_exit_notify wakes you with the result. Awake time bills the workspace, so the wrap is for work that FINISHES. Never wrap an auto-restarting service: when the job exits the supervisor starts it again, the hold never ends, and the sandbox stays resident and billing until its 24-hour ceiling. Never wrap a server, web app, preview or API (they need nothing while idle and the preview auto-wakes them), and never wrap a daemon meant to run indefinitely (declare it plainly; it is restarted on wake). When you create a NEW primary user-facing server and the port is yours to choose, bind it to 443: sandbox processes can bind 443 directly (no privilege step needed), and its preview URL is then the clean port-less https://<sandbox>.<domain>/ instead of carrying a :port suffix. This is a default for new services only — NEVER move a server that is already listening, or override a port the user or a tool chose (a Vite dev server on 5173 stays on 5173 and is previewed there). Other ports stay reachable at their explicit :port URLs. Secrets: `{{bolter.token:NAME}}` / `{{bolter.value:NAME}}` placeholders in the command or env values are expanded to the grant's token / raw value host-side at launch.

bolter_sandbox_service_put

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Search the published blueprint catalogue for a ready-made blueprint that already does what someone is asking for. Call this BEFORE designing agents, responsibilities or schedules for a stated goal. Someone who says they want their inbox triaged, their competitors watched, or a partner kept updated is describing an outcome, not asking for a bespoke build, and the catalogue may already carry a blueprint that other workspaces have installed and used. Building one from scratch when a published one exists costs the person a worse version of something that already works. Search by the goal in the person's own words. The search is semantic, so you do not need the blueprint's own vocabulary, and paraphrasing the goal works better than guessing at a title. Each hit carries the slug, title, headline, summary, tags, how many agents and responsibilities it sets up, how many workspaces installed it, and the url of its page. Read a promising hit in full with bolter_read_blueprint using its slug before offering it, and tell the person what it does in plain language rather than pasting the file at them. An empty result means no published blueprint matched, not that the idea is impossible. Say so plainly and design something instead.

bolter_search_blueprints

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Search your own private memory blocks by hybrid relevance: pgvector cosine similarity (semantic) and Postgres FTS (lexical) merged via reciprocal-rank-fusion. Each hit reports matchKind ∈ {'vector', 'fts', 'both'} so you can see why it surfaced. Falls back to FTS-only when the embedding service is unavailable. For the workspace memory, use search_workspace_memory instead.

search_memory

Search the messages in your chats by words, newest first. Pass groupId to search one chat only. participantIds, since and until narrow the search; pass the cursor a result returns for more.

search_messages

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Search the workspace memory by hybrid relevance: pgvector cosine similarity (semantic) and Postgres FTS (lexical), merged via reciprocal-rank-fusion. Each hit reports its outbound [[links]], backlinks, and resolved @mentions, plus a cursor that opens that page from the top with read_workspace_memory.

search_workspace_memory

Post a message in a chat. This is how you answer ordinary chat messages: every chat reply goes through this tool. Use bolter_notify_cli_update only for the owner notice requested by an update_available event. Pass the chat as bolter_chat. To answer in a message's thread, also pass that message id as bolter_thread. Markdown works. Leave groupId, placement and type unset.

bolter_send_message

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Start an app here. Writes a vetted, buildable TypeScript app project into your sandbox: a Vite + React frontend, a node:http backend that runs as TypeScript with no server build, and one OpenAPI 3.1 contract (src/contract.ts, authored the same way the Bolter platform defines its own API) that the typed handlers, runtime request validation, and the typed frontend client all derive from; /openapi.json serves the contract document itself, and "npm run build" type-checks everything against it, so drift fails the build instead of breaking silently. Platform plumbing is already correct: caller identity from the X-Sandbox-Caller-* headers (people AND agents, no login to build), live state to every open browser over a WebSocket, the self-dispatch endpoint for background work, an agent-only write-back route, SQLite storage your bolter_sqlite_* tools can inspect, and dev auto-reload on restart (turn off when stable). Two project shapes: flow (the default, for any app that does something more than once with a result someone can look at afterwards: a typed flow definition, a derived graph, a run engine and a run history) and basic (only for an app that does no work of its own: one screen over state people fill in themselves). Pass appName so the app carries its own name and mark in the browser tab instead of the template's, and appSlug too if you already ran bolter_app_create. THEME (it is not decoration you add later): pass theme with an id from the roster below. It generates the stylesheet the app links, carrying a full light and dark token contract, responsive component classes, and that theme's identity, plus a script that resolves the viewer's light/dark and ships a toggle. The design guide comes back in this tool's result, so build the UI from it. Themes: - desk (dense rows and figures: queues, run logs, boards, anything mostly list): A working desk. Warm paper, hairline rules instead of shadows, one blue accent, and every figure in tabular monospace so a column of numbers reads as a column. Omit theme ONLY when the app needs an identity of its own (a brand to match, a newspaper, a game): you still get the token contract and the classes, and you override only what your identity changes, so light, dark and the responsive layout keep working. After scaffolding: dependencies are ALREADY INSTALLED (the project arrives with node_modules, so do not run npm install), edit only the "EDIT: your app" sections, npm run build, run as a supervised service. Call this BEFORE writing an app by hand.

bolter_app_scaffold

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Upsert a memory block in your own private memory. Sync, returns immediately with summaryStatus=pending. The async summariser regenerates summary + embedding shortly after. This tool only writes your own private memory. It stores what you know; it does not change your configuration or workspace-wide knowledge.

write_memory

This description is written for agents Bolter runs. Ignore anything it says about replying as plain text, your turn or dispatch, or tools you cannot find: you answer with bolter_send_message, and pass bolter_chat on any call that posts to a chat. Write content to a file in a sandbox. Creates parent directories if needed. For a SMALL file whose full content you already have, pass it inline here. Do NOT use this to dump a large or complex file (a big HTML page, dataset, or generated document) as one giant inline content payload — model output limits truncate it and the write silently drops bytes. For large/complex single files, GENERATE the file inside the sandbox instead: run the pre-installed claude CLI or a node/python generator script via bolter_sandbox_exec so the bytes are produced in the sandbox and never marshalled through a tool argument. Writing or changing app code that reads outside data (a feed, an API, documents) or decides something from it? Load the app-data-code skill first (bolter_load_skill). Secrets: `{{bolter.token:NAME}}` / `{{bolter.value:NAME}}` placeholders in the content are expanded host-side before the file is written, so a credential can land in a file without passing through you.

bolter_sandbox_write