Extend Bolt
Build a rich app in 5 minutes.
Copy a template, change data in one file, and get tiles, drill down with Back, a detail panel, a cache and plain error rows. You do not write code.
Copy, edit, check, pack, drop.
# one time: get the template (a public repo; needs python3 and node 18 or newer)
git clone https://github.com/SparcleHQ/bolt-apps ~/bolt-apps
cp -R ~/bolt-apps/kit/examples/portal-template ~/my-app
cd ~/my-app
# 1. edit scripts/config.json and scripts/fixtures.json (the four things below),
# rewrite check.json cases for your views and delete golden/ files no case names (golden_stale),
# set "id" in bolt-app.json, and delete the old utilities/portal-template.yaml
# (step 2 writes the new one)
# 2. build the app file from config.json (never edit the yaml by hand)
python3 scripts/engine.py --emit-yaml > utilities/<id>.yaml
# 3. check it on the sample data, review golden/ once, then check again
BA=~/bolt-apps/toolkit/bin/bolt-apps.mjs
node "$BA" check . --update-golden # once, then read the golden/ files
node "$BA" check .
# 4. pack it for your own use (run node "$BA" keygen once before the first pack)
node "$BA" lint . --personal
node "$BA" pack . --personal --version 1.0.1 --out ../my-app-1.0.1.boltpack # a higher version on every rebuild
# 5. drop my-app-1.0.1.boltpack on the Bolt launcher or Bolt Apps
-
Copy the template.
kit/examples/portal-templatein the public bolt-apps repository. It runs as is, on sample data, with no key and no network. -
Change the four things below. Also set
idinbolt-app.jsonto the new id (andtitle,summary), and renameutilities/<template>.yamltoutilities/<id>.yamlso the old one is gone. -
Emit the app file from
config.json. Keepidthe same inconfig.json,bolt-app.json, the yaml file name and the folder name (id_mismatchotherwise). -
Check.
checkruns the script on recorded data and tests every row against the row contract. It does not draw the rows: open the app in Bolt to see them. -
Pack and drop.
pack --personal --version 1.0.1 --out ../my-app-1.0.1.boltpackwrites the pack next to the folder. Keep packs outside the app folder. Raise the version (1.0.2, 1.0.3) every time you pack again: Bolt refuses a pack that is the same version or older than the one installed. Pack again with the same key you first used: a newkeygenmakes a different signer, and Bolt then refuses with "already belongs to". Drop it on the Bolt launcher or Bolt Apps (not Admin settings, which accepts only company-signed bundles). Bolt shows the permissions and asks you to confirm. -
Run it once in Bolt. Type
=<chip>, press Enter on the app's run row if Bolt asks for your OK, and see the overview rows. The tools cannot draw the launcher, so this step is the proof. If Bolt says it cannot tell which files the app runs, see the rules Bolt enforces.
Pick your starting point.
Read kit/examples/index.json:
for each template it gives the layout, the pane kinds, the techniques, the files to edit and the check command.
Pick the closest one, copy its folder, and edit only the listed files.
| Template | What it teaches | Backed by | Panes | Edit only |
|---|---|---|---|---|
portal-template | overview tiles, drill down to lists, detail with related rows, per-row detail panel | any REST API with a key | cards, entity_preview | scripts/config.json, scripts/fixtures.json |
acme-dash | compliance dashboard, 7 lists, controls drill to linked tasks | fictional API | cards, entity_preview | scripts/config.json, scripts/fixtures.json |
widget-gallery | Which right-hand panes a personal app can draw and the exact `bind` keys each needs | sample data | cards, chart, table, detail, json_tree, diff, entity_preview, markdown | scripts/config.json, scripts/fixtures.json |
form-template | A declarative input form (number, select, date, text with a length limit, toggle), checks on the values, a local log, and the log shown as a table | a local file | table | scripts/config.json |
chart-template | Every chart the launcher can draw, each fed both ways, plus a cards-only dashboard | any REST API | cards, chart | scripts/config.json, scripts/fixtures.json |
table-template | The `table` pane: columns with `label`, `align`, `format` (text, number, percent, currency, date), `unit`, per-column `total` (sum, avg, min, max, count), `sort` and `totals_label` | any REST API | cards, table | scripts/config.json, scripts/fixtures.json |
lookup-template | One typed word in, a stitched result out | Open-Meteo geocoding and forecast (keyless) | cards | scripts/config.json, scripts/fixtures.json |
file-insights-template | A local-file app: the person types the path of a CSV, the app reads it with the standard library only, finds the date, value and group columns by name, and shows totals, a titled line chart, a titled bar chart, a table and a list of things to watch | a local CSV file | cards, chart, table, markdown | scripts/config.json, scripts/fixtures.json |
cli-wrapper-template | How to wrap a command-line tool as a Bolt App, using the system `ping` as the tool | the system ping command | cards, chart, markdown | scripts/config.json |
system-glance | The command-probe archetype on the flat kit: three read-only probes (`df`, `uptime`, `lsof` or `ss`) run in parallel inside one deadline, each parsed on its own | df, uptime, lsof or ss | cards | scripts/system-glance.py |
repo-radar | Joining several remote APIs into one verdict | GitHub REST; npm registry and downloads; OSV.dev; Hacker News search | cards, diff, detail, chart, table | scripts/config.json, scripts/fixtures.json |
around | Stitching independent systems on coordinates | Nominatim; Overpass; CityBikes; Open-Meteo; Wikipedia geosearch | cards, detail, table, chart | scripts/config.json, scripts/fixtures.json |
local-service-template | `runtime: http_local`: an app with no script at all | a service on 127.0.0.1 (Ollama model list as the example) | detail | utilities/localmodels.yaml |
widget-gallery-2 | The three panes `widget-gallery` has no room for, because a personal app may have at most 8 views including the overview and that gallery already uses all 8 | sample data (generated swatches) | card, image_grid, cards | scripts/config.json, scripts/fixtures.json |
The engine templates (portal-template, acme-dash, chart-template, lookup-template, table-template, widget-gallery, widget-gallery-2)
make the app file with python3 scripts/engine.py --emit-yaml and you never edit engine.py. The others have their own script, and for those you are expected to edit it (the functions their README names), but never bolt_app_kit.py:
around uses around.py, repo-radar radar.py, cli-wrapper-template wrap.py,
file-insights-template insights.py; run that script with --emit-yaml
as its README shows. system-glance has no --emit-yaml: edit utilities/glance.yaml and scripts/system-glance.py by hand. local-service-template has no script: edit its utilities/localmodels.yaml.
Full reference: ENGINE.md.
MCP servers
A personal app has no direct way to call an MCP server. The workaround is a script that starts a command line tool or an MCP client, reads its output and prints rows. Name that script as {{scripts_dir}}/<file> like any other.
What backs your app.
| Backing | Runtime | How | Start from | Limits |
|---|---|---|---|---|
| CLI command | bridge | a script runs the command as an argument list with no shell | cli-wrapper-template (one tool with typed arguments), system-glance (parallel probes) | personal pack only; per-OS command table; stderr is not seen; 60 s at most |
| remote HTTP API | bridge | a script calls the API (urllib) inside a deadline; keys from keychain or ~/.config/ | repo-radar, around (several APIs joined); lookup-template, chart-template, table-template, portal-template (one API, config only) | declare network; a shell variable never reaches the script |
| local HTTP service | http_local | Bolt makes one GET or POST to 127.0.0.1, localhost or ::1; no script | local-service-template | loopback only, one request, no secrets, no chaining |
| file | bridge | a script reads a path the person types, with caps and a regular-file check | file-insights-template (read), form-template (write its own log) | declare files; the path travels as query words, not in a nav arg |
| MCP server | none native | a bridge script starts the MCP server over stdio and calls one tool (see ENGINE.md, MCP workaround) | the snippet in ENGINE.md | tested only against a stand-in server; the person needs the server installed; 15 s cap; one tool per app |
Typed words and nav args
A nav arg is one plain token: no slash and no spaces. A typed path or owner/repo therefore cannot travel in a row's nav.
The kit keeps the last typed query in its cache (~/.bolt-apps/cache/<app>) and the script repeats it.
A personal app has at most 8 views including the overview. widget-gallery uses all 8, so the card pane, image grid and image cards are in widget-gallery-2.
Auth modes
| Mode | What the app does |
|---|---|
| No key | Sends nothing. Four of the five sources in around. |
| Optional key | Sends Authorization: Bearer ... when you add one, and works without it. |
| Required free key | With no key the view shows an "Add your free key" row with the exact one-line setup command. The key goes in the query value the service names. |
| Bearer | Authorization: Bearer ... |
| Basic | Authorization: Basic ... built from user and password. Only a masked form is ever shown. |
Keys come from the keychain or the owner-only file, never a shell variable. Native sign-in flows are not covered by these examples.
Live terms of public APIs (checked 2026-11-15 with real requests)
| Source | What to respect |
|---|---|
GitHub api.github.com | 60 requests an hour without a token, 5,000 with one. A User-Agent is required: a request without one is refused. |
Nominatim nominatim.openstreetmap.org | A User-Agent naming the app (none got HTTP 403) and at most 1 request a second. around waits 1.1 s between calls and keeps an answer 30 days. |
Overpass overpass-api.de | Public and shared: it answers 502 or 504 when busy and a good call took 32 to 34 s. The app keeps places 1 hour and shows an old copy, so rows can say "Places down". That is real, not a bug. |
| Open-Meteo, CityBikes, Wikipedia | No key. Open-Meteo allows 600 requests a minute and asks for credit; Wikipedia expects a descriptive User-Agent. |
Pane kinds that work, and ones that do not.
| Kind | Shows | Main bind keys |
|---|---|---|
entity_preview | Selected row: tile above, label and value fields, chips, Markdown body, buttons | title, subtitle, tiles_above, fields, body, actions |
cards | All rows as a grid, or as number tiles with a meter | title, subtitle, badge, footer, and for tiles layout: tiles, value, unit, max |
table | All rows as a table, with totals | columns, sort, totals_label |
detail | Label and value pairs for the selected row | title, subtitle, fields |
chart | A line, bar or sparkline | type, values or y with x, label, color, unit |
card, markdown, json_tree, diff, image_grid | One card, a Markdown page, a JSON tree, two texts side by side, pictures | See the Agent guide table |
Do not use these
| Kind | What Bolt shows | Use instead |
|---|---|---|
image | This app asks for an image pane, which cannot show app data. Use image_grid for pictures. | image_grid (inline data images only) |
color, weather, date, calc | This app asks for a <kind> pane, which cannot show app data. Use table, detail, cards or chart. | table, detail, cards or chart |
map | Loads, but shows the launcher's own map state, not your data (no bind keys) | A row url that opens a maps page (Open in Maps) |
entity | Refused when the file loads | entity_preview |
What a chart can and cannot do
| Rule | |
|---|---|
| Types | bind.type is line (the default), bar or sparkline. There is no pie, donut or area chart. |
| Data, one row | bind.values names a row field that holds a list of numbers. |
| Data, one point per row | bind.y names a number field; bind.x names the label field. |
| Colour | bind.color is accent or muted. Nothing else. |
| Hover | Tooltips on points and bars only. No click or zoom. |
| Instead of a pie or donut | Number tiles with a meter (kpi_max) for a part of a whole, or a table with a percent column. |
Where to store API keys and passwords.
The template reads a key with the kit's get_secret. It tries an environment variable first (useful only in a terminal and in tests, because Bolt never passes it), then the keychain, then the file. When none is found the app shows a row with the exact setup line.
| Place | Rule |
|---|---|
1. The system keychain (macOS security, Linux secret-tool) | Encrypted, per user, never a file. Not available on Windows: use the file there. Needs the tool installed. |
2. ~/.config/<app id>/.env, mode 0600, one NAME=value line | Works everywhere. Plain text on disk, outside the app folder. The engine refuses it if others can read it. |
| A shell environment variable | Does not work under Bolt. Bolt starts the script with an empty environment except a short allowlist (HOME, PATH, USER, LANG, TERM, TMPDIR, TZ, LC_*, XDG_*, CA bundle variables) and never forwards secret-looking names, those containing TOKEN, KEY, SECRET, PASS, PWD, CRED, AUTH, PRIVATE, SESSION or COOKIE. It works only in a terminal and in tests. |
An inputs field of type secret | Do not use it for keys: how the value reaches the run log is not measured. |
# macOS (asks for the key)
security add-generic-password -s bolt-app-<app id> -a <NAME> -w
# Linux (asks for the key)
secret-tool store --label=<app id> service bolt-app-<app id> account <NAME>
# any system: the file, only you can read it
(umask 077; mkdir -p ~/.config/<app id> && printf '<NAME>=' >> ~/.config/<app id>/.env)
# then open that file and paste the key right after the = sign
Never put a key in
| Never in | Why |
|---|---|
The app file or config.json | Both are packed and shared. |
fixtures.json, golden/, the README | Samples are public. Use made-up data. |
| A pack | A .boltpack is a file you may hand to others. |
| The cache, a row, a comment or a log | The engine never prints, caches or shows the key. Do not add a path that does. |
| A query word | It is typed on screen and passed to the script on its command line, where other programs on the computer can read it. |
Two cases, two rules.
| Gallery app | Personal rich app | |
|---|---|---|
| Tier | 1 or 2: text, search, transform | 3: runs a script and calls the network |
| Pack | bolt-apps pack, signed with your own key | bolt-apps pack --personal, for you only. Never build a pack by hand. |
| Install | From the gallery, when it opens | Drop the .boltpack on the Bolt launcher or Bolt Apps. Bolt shows the permissions and asks you to confirm. |
| Cache | No script, so none | Inside the script: cache.ttl and cache.stale_max in config.json. Not the YAML field cache_ttl_seconds, which is the admin connector cache and is refused in a User App. |
The files, all public.
| File | Link |
|---|---|
| The template, a folder to copy | kit/examples/portal-template |
| Its config, the file you edit | scripts/config.json |
| Its engine, the file you do not edit | scripts/engine.py |
| A full example: 8 views, 3 levels | kit/examples/acme-dash |
| The row contract | kit/schema/row.schema.json |
| Rules for agents | AGENTS.md |
The four things you change.
| # | Where | What |
|---|---|---|
| 1 | config.json app, api | App id, chip, title. base_url, the key variable name, the .env path, the auth header. |
| 2 | config.json endpoints | One entry per API path, with map from your field names to the names the views use. Dotted paths work: "owner": "assignee.name". |
| 3 | config.json stats, overview, views | Counters, the tiles on the overview, and per view: row title, subtitle, tile, up to 5 detail fields, body, link, and children for a drill to a second list. |
| 4 | scripts/fixtures.json | A real response saved per endpoint. check uses it; the shipped app stays live (api.fixture_default is false). |
{
"app": { "id": "my-app", "chip": "myapp", "title": "My app", "icon": "globe", "service": "My Service" },
"api": {
"base_url": "https://api.example.com",
"key_env": "MY_API_KEY",
"env_file": "~/.config/my-app/.env",
"auth_header": "Authorization",
"auth_prefix": "Bearer ",
"fixture_default": false
},
"endpoints": {
"tickets": { "path": "/v1/tickets",
"map": { "title": "summary", "status": "state", "assignee_name": "assignee.name" } }
},
"views": [
{ "id": "tickets", "title": "Tickets", "endpoint": "tickets",
"item": { "title": "{title}", "subtitle": "{status|human} · {assignee_name}",
"fields": [{ "label": "Status", "value": "{status|human}" }] } }
]
}
Put the key in the system keychain or the owner-only .env file: see
Where to store API keys. A shell environment variable does not reach the app under Bolt.
It is never printed, cached or put in a row.
The drill flow.
The app file takes view and arg from the words you type after the key
(query.word(0), query.word(1)). Each Enter on a row with nav runs the
script again with that view and arg. A detail view reuses an existing view, so it does not use up one of the 8.
=my-app type the key, press Enter
|
v
OVERVIEW (view "overview", one summary row per list)
[ Summary no nav, its tile shows on the right ]
[ Tickets · 12 nav {view: tickets} ] Enter
[ Projects · 4 nav {view: projects} ] Enter
[ Documentation url ] Enter opens the page
[ Refresh nav {view: overview, arg: refresh} ] Enter fetches fresh data
|
v Enter on "Projects" launcher runs: engine.py projects -
LIST (view "projects")
[ Back nav {back: true} first row, always ]
[ Website refresh nav {view: projects, arg: P-1} ] Enter
[ Billing cleanup nav {view: projects, arg: P-3} ]
[ Refresh nav {view: projects, arg: refresh} ]
|
v Enter on "Website refresh" launcher runs: engine.py projects P-1
DETAIL (same view, with an arg; its rows come from views[].children)
[ Back nav {back: true} ]
[ Add SSO pane: tickets (drawn by the tickets panel) ]
[ Dark mode colors pane: tickets ]
Which config field gives which feature.
| Feature | You write (config.json) | What reaches Bolt (row and app file) |
|---|---|---|
| Overview with tiles that drill into a list | overview.rows[] with view; the tile uses stats | Row nav {view}, right panel cards with layout: tiles |
| Up to 8 views | views[], at most 7 besides the overview | presentation.views, view_arg: view |
| Which view to show | Built in: the first word you type | args from query.word(0) and query.word(1) |
| Back row, first in every list | Built in | Row nav {back: true} |
| Level 3: a detail view that lists related rows | views[].children (rows of another view whose match field equals this row's id). No new view needed. | Row nav {view, arg} with the id as arg |
| Detail panel for the selected row | item.fields (up to 5), item.body, item.tile | Row pane, right panel entity_preview with tiles_above, fields, chips, body |
| Tile with a meter and a badge | tile with label, value, max, unit, note, foot, badge rules | Row kpi_label, kpi_value, kpi_unit, kpi_max, kpi_note, kpi_foot, kpi_badge |
| Open and Copy buttons | item.url | Row open_url and copy_text, yaml actions open and copy |
| A row that opens a web page | overview.rows[].url | Row url |
| Filter by one word | Built in: =my-app tickets open | args from query.word(1). The row has no filter field. |
| Cache 45 s, old copy up to 24 h | cache.ttl, cache.stale_max | Refresh row nav {view, arg: refresh} |
| Offline, rejected key, no key, partial load | Built in, one plain row each | A row with nav back to the same view, so Enter retries |
| Key stays private | api.key_env, api.env_file (keychain first, then the file) | Never in a row, the yaml or the cache |
| Tests with no key and no network | "fixture": true in check.json (whole app, or one case; a case wins, false forces live) and scripts/fixtures.json | A shipped app is live: api.fixture_default is false. An installed pack cannot be switched to sample data. In a terminal, BOLT_APP_FIXTURE=1 runs on samples. |
Rendering rows.
The engine writes every row for you. You only need this section to understand what the launcher gets, or to
write a script by hand. Each sample is a real row from kit/examples/acme-dash/golden with the empty
fields left out. Next to it is the app file part that draws it, and the layout you see. Rows are one JSON array
on stdout, at most 200. The full contract is
row.schema.json.
1. A drillable row
A row with nav {view, arg} takes the person to another view when they press Enter. arg is optional. A nav row carries no actions of its own.
{
"title": "Tasks · 41 of 50 done",
"subtitle": "7 in progress · 2 not started",
"icon": "list",
"nav": { "view": "tasks" },
"kpi_label": "Tasks done", "kpi_value": 41, "kpi_max": 50,
"kpi_note": "of applicable tasks", "kpi_foot": "7 in progress", "kpi_badge": "IN PROGRESS"
}
{
"title": "Next up",
"subtitle": "4 things to do",
"icon": "list",
"nav": { "view": "tasks", "arg": "urgent" }
}
args:
- { name: view, from: "query.word(0)", default: overview }
- { name: arg, from: "query.word(1)", default: "-" }
bridge:
command:
macos: "python3 {{scripts_dir}}/engine.py {{view}} {{arg}} {{scripts_dir}}/config.json {{scripts_dir}}/fixtures.json {{scripts_dir}}/bolt_app_kit.py"
linux: "python3 {{scripts_dir}}/engine.py {{view}} {{arg}} {{scripts_dir}}/config.json {{scripts_dir}}/fixtures.json {{scripts_dir}}/bolt_app_kit.py"
windows: "python {{scripts_dir}}/engine.py {{view}} {{arg}} {{scripts_dir}}/config.json {{scripts_dir}}/fixtures.json {{scripts_dir}}/bolt_app_kit.py"
parse: json
timeout_seconds: 25
presentation:
widget: list
title_field: title
subtitle_field: subtitle
view_arg: view
views:
overview: {}
tasks:
right_widget: ... # see pattern 4
Overview | Right panel (tile of the selected row)
------------------------------------------+---------------------------------
> Tasks · 41 of 50 done | Tasks done IN PROGRESS
7 in progress · 2 not started | 41 / 50 [#########---]
Next up | of applicable tasks
4 things to do | 7 in progress
Refresh |
| Enter on a row with nav runs the
| script again with that view and arg
2. The Back row
The first row of every list and detail view is nav {back: true}. It needs no yaml of its own: the engine writes it. The app file only sets
view_arg: view.
{
"title": "Back",
"subtitle": "50 tasks",
"icon": "arrow-left",
"nav": { "back": true }
}
Tasks
------------------------------------------
> Back (always first)
50 tasks
Check endpoint protection status (EU)
In progress · Elena R. · due 2026-07-15
...
3. Cache and refresh
Answers are cached for cache.ttl seconds. If the API fails and an old copy exists (up to
cache.stale_max), the old rows show under a STALE row. A failure is never cached. A row whose
nav points at the same view with arg: refresh skips the cache when you press Enter.
For a detail view the arg is refresh.<id>.
"cache": { "ttl": 45, "stale_max": 86400 }
// 1. the refresh row, last in every list (golden/overview.json)
{
"title": "Refresh",
"subtitle": "Enter to fetch fresh data",
"icon": "RefreshCw",
"nav": { "view": "overview", "arg": "refresh" },
"pane": "overview"
}
// 2. the server is down but an old copy exists (golden/stale.json)
{
"title": "Acme Compliance is not answering. Showing data from 3.0 h ago.",
"subtitle": "Could not connect to Acme Compliance. Enter to retry",
"icon": "AlertCircle",
"nav": { "view": "tasks", "arg": "refresh" },
"pane": "tasks",
"kpi_label": "Data age", "kpi_value": 10800, "kpi_unit": "s",
"kpi_note": "old copy", "kpi_badge": "STALE"
}
// 3. the data came from the cache (written by engine.py notice_rows;
// shown once the copy is 2 s or more old; 12 s here as an example)
{
"title": "Loaded from cache, 12 s old",
"subtitle": "Enter to refresh (data is kept 45 s)",
"icon": "RefreshCw",
"nav": { "view": "tasks", "arg": "refresh" },
"pane": "tasks",
"kpi_label": "Data age", "kpi_value": 12, "kpi_unit": "s", "kpi_max": 45,
"kpi_note": "from cache, Enter to refresh", "kpi_badge": "CACHED"
}
Tasks
------------------------------------------
Back 50 tasks
> Loaded from cache, 12 s old
Enter to refresh (data is kept 45 s) <- Enter runs: engine.py tasks refresh
Check endpoint protection status (EU) (skips the cache, fetches again)
...
Refresh
Enter to fetch fresh data
4. A detail panel per row
A row's pane names the view whose right panel draws it. The panel binds row fields:
kpi_* into tiles_above, the fields f1 to f5 into
fields (kind chips for a tag list), body as Markdown, and
actions by id.
{
"title": "Asset inventory",
"subtitle": "1 linked tasks · Portal · owner Sam K.",
"icon": "Layers",
"body": "## Asset inventory\n\nControl asset inventory.\n\nEnter lists the tasks linked to this control.",
"nav": { "view": "controls", "arg": "C-017" },
"pane": "controls",
"kpi_label": "Linked tasks", "kpi_value": 1,
"kpi_note": "tasks behind this control", "kpi_badge": "PORTAL",
"open_url": "https://app.example.com/acme/controls/C-017",
"f1": "SOC 2, ISO 27001", "f2": "Portal", "f3": "Sam K."
}
views:
overview: {}
controls:
right_widget:
kind: entity_preview
mode: selected_row
bind:
title: "{{row.title}}"
subtitle: "{{row.subtitle}}"
tiles_above:
title: "{{row.kpi_label}}"
value: "{{row.kpi_value}}"
unit: "{{row.kpi_unit}}"
max: "{{row.kpi_max}}"
subtitle: "{{row.kpi_note}}"
badge: "{{row.kpi_badge}}"
footer: "{{row.kpi_foot}}"
fields:
- { label: "Frameworks", value: "{{row.f1}}", kind: chips }
- { label: "Portal", value: "{{row.f2}}" }
- { label: "Owner", value: "{{row.f3}}" }
body: "{{row.body}}"
actions: [open, copy]
Controls | Asset inventory
------------------------------------------+---------------------------------
Back | [tile] Linked tasks PORTAL
> Asset inventory | 1 tasks behind this control
1 linked tasks · Portal · owner Sam K. | Frameworks [SOC 2] [ISO 27001]
... | Portal Portal
| Owner Sam K.
| ## Asset inventory
| Control asset inventory. ...
| [ Open ] [ Copy ]
5. Tiles, meters and badges
A tile is kpi_label, a number kpi_value (a JSON number, never text), and optionally
kpi_unit (up to 4 characters), kpi_max (draws the meter), kpi_note,
kpi_foot (up to 80) and kpi_badge. A tile with a label and no number is refused.
In config.json the badge is a list of rules, first match wins.
The row schema also takes badges, up to 4 of {label, tone}.
"tile": {
"label": "Progress", "value": "progress", "max": 100, "unit": "%",
"note": "of the work", "foot": "created for {control_id}",
"badge": [
{ "if": "status==done", "badge": "DONE" },
{ "badge": "IN PROGRESS" }
]
}
{
"title": "Confirm encryption at rest (EU)",
"subtitle": "In progress · Jordan L. · due 2026-05-01",
"pane": "tasks",
"kpi_label": "Progress",
"kpi_value": 52,
"kpi_unit": "%",
"kpi_max": 100,
"kpi_note": "of the work",
"kpi_foot": "created for C-001",
"kpi_badge": "IN PROGRESS"
}
right_widget:
kind: cards
mode: list_data
bind:
layout: tiles
title: "{{row.kpi_label}}"
value: "{{row.kpi_value}}"
unit: "{{row.kpi_unit}}"
max: "{{row.kpi_max}}"
subtitle: "{{row.kpi_note}}"
badge: "{{row.kpi_badge}}"
footer: "{{row.kpi_foot}}"
Progress IN PROGRESS
52 % [#####-----] of 100
of the work
created for C-001
6. Row actions: open and copy
url on a row (http or https only) is opened by Enter. The buttons in the panel are declared once in the
yaml with an id, bound to row fields, and listed by id in the panel. A row may add up to 3 actions of its own
(row schema maxItems 3). The footer shows 6 buttons in all, the buttons in the app file first, and cuts each label at 14 characters
(the full label, up to 40, is the tooltip). The template declares 2 (Open, Copy).
{
"title": "Trust portal · on",
"subtitle": "trust.example.com/acme-demo",
"icon": "globe",
"url": "https://trust.example.com/acme-demo",
"copy_text": "- Trust portal on - trust.example.com/acme-demo",
"open_url": "https://trust.example.com/acme-demo"
}
actions:
- { id: open, kind: url, target: row, label: Open, url_template: "{{row.open_url}}" }
- { id: copy, kind: composer, target: row, label: Copy, insert: "{{row.copy_text}}" }
# a panel lists the ids it shows: actions: [open, copy]
> Trust portal · on Enter opens the page (row url)
trust.example.com/acme-demo
Right panel footer: [ Open ] [ Copy ]
Open -> open_url
Copy -> copy_text, a safe plain text version
The template contract.
What you or your agent may edit, and what it must leave alone.
| File | Rule | What is in it |
|---|---|---|
scripts/config.json | Edit | App id, chip, title, icon. base_url, key variable name, .env path, auth header. endpoints and their map. stats, overview, views, labels, tiles, fields, body, link, children. |
scripts/fixtures.json | Edit | One real (made-up if sensitive) response saved per endpoint. check runs on it ("fixture": true in check.json) so tests need no key and no network. The shipped app is live. |
bolt-app.json, README.md | Edit | Title, role, summary, author, permissions in plain words. Keep id equal to the one in config.json. |
check.json, golden/ | Edit, then regenerate | Add a case for each view you add. Run check --update-golden and read the diff once. |
utilities/<id>.yaml | Generate only | Written by engine.py --emit-yaml. Never hand edit: the labels in the right panel must match the row fields. |
scripts/engine.py | Do not edit | The same file in every app built from the template. It reads config.json and fixtures.json from the folder it sits in, calls the API, keeps the cache and writes the rows. It is the only script the app file names. |
scripts/bolt_app_kit.py and bolt_app_kit.lock.json | Do not edit | The vendored kit. Refresh it with bolt-apps kit vendor --flat ., never by hand. |
Checking, icons and limits.
| Topic | Rule |
|---|---|
Sample mode in check | "fixture": true at the top of check.json (every case) or on one case. A case wins; "fixture": false forces live. check then reads fixtures.json. A shipped app is live and a pack cannot be flipped. |
| Copied template, stale goldens | A copy brings its golden/ files and check.json cases. Rewrite the cases, delete goldens no case names (golden_stale), run check --update-golden once and read the files. |
| Icons | Every icon in config.json must be a name in kit/schema/icons.json. An unknown one is an engine error and a lint --personal error (icon_unknown). The app file's own icon: is only a warning. |
| Stubs by argument | A stub can answer by the words after the command (by_args), so git status and git log can differ. A case can set env (capital names, not PATH or HOME). Otherwise the check environment is empty except PATH (the stub folder) and HOME (a temporary folder). |
| Permissions | The list computed from the app files wins. permissions in bolt-app.json is listing text, and lint warns permissions_differ when they disagree. |
| Filters in labels | {field|when} (epoch seconds or milliseconds, local date and time), whenday (date only), round, round1, round2 (0, 1 or 2 decimals), plus human, day, hhmm, upper, lower. |
Limits of the engine templates
| Limit | What to do |
|---|---|
| List size | The engine hands a list at most 50 rows and says so in the view. A chart or table pane can draw up to 500 rows, but the engine does not give it more. |
| No per-id detail call | Views mode calls only the list endpoints you name. {id} and {query} paths work only in lookup mode. Put detail fields in the list response, use a lookup app, or use a script like repo-radar. |
| Row buttons | Config gives Open (url on an item) and Copy. More need the app file's actions:, at most 3 footer buttons including those two. |
| Stitching | Stats from several endpoints on the overview, and children (rows of another view whose field equals this row's id). There is no cross-join of two endpoints into one row; use a script (repo-radar, around). |
| Words before the view word | A nav arg is one plain token, no slash. If a query word comes before the view word it needs a plain-word default (lint view_arg_lead_default). A default of - is fine after it. |
| A button in a drilled-in view | A nav row carries no actions. A workaround is an ordinary row with a utility action that points at the app's own chip. That is not yet proven in the launcher. |
Rules Bolt enforces.
These are checked when Bolt loads or runs the app, not by this page. The words in the middle column are what
Bolt shows, so you can search for them. bolt-apps lint --personal, check and
verify catch most of them before you drop the pack; the last step, running it in Bolt, catches the rest.
| Rule | What Bolt says | Fix |
|---|---|---|
| The scripts folder is named in one plain form | Bolt cannot tell exactly which files this app runs, so it was not run. It names its scripts folder in a form Bolt cannot resolve to one file each, so it cannot say which files this app runs. | Every mention of scripts_dir, comments included, is {{scripts_dir}}/<file> as its own word. The file name is letters, digits, ., _ and -, no leading or trailing dot, no ... |
| A named script exists and is a plain file | <name> is missing, or is a link, not a file, or is not a plain file, or is too large to check (over 2 MB) | Put each script directly in scripts/ as a real file under 2 MB. |
| No character escapes in the app file | It uses character escapes (such as \x or \u) that can hide what it runs. | Write plain text. The generated file has none. |
| Name every helper file in the command | Nothing is said. Bolt hashes only the app file and the scripts named as {{scripts_dir}}/ | The template names its helper files (config.json, fixtures.json, bolt_app_kit.py) as extra words in the command. Keep them, and add any helper file you add. Pack again after any edit. |
| First run needs your OK | Not run. Needs your OK. Press Enter on the app's run row to review it and accept. Runs with your permissions. Not sandboxed. | Press Enter on the app's run row and accept. Do this once, then confirm the first run works. |
| The app file changed after Bolt loaded it | This app's file changed after Bolt loaded it, so it was not run. Press Reload in Settings, Desktop, User Apps. | Press Reload. |
| At most 8 views, overview included | presentation.views has N entries, at most 8 allowed | Show a detail with the same view and an id as arg, not a new view. |
| View names | presentation.views name "x" must match ^[a-z][a-z0-9_-]{0,23}$ and not be a reserved name | Lowercase, starts with a letter, up to 24 characters. Not constructor or prototype. |
view_arg and views go together | presentation.view_arg is set but presentation.views is missing, or the other way round | Set both. view_arg names an arg. |
view_arg is a query word | presentation.view_arg "x" is not a declared arg, or must name an arg bound with from: "query.word(N)" | Declare args: [{ name: view, from: "query.word(0)" }]. |
| Args come only from the typed words | args[x].from ... unsupported; only query.word(N) is supported in v1 | Use query.word(N). |
| Nav view and arg are plain tokens | Nothing is shown: Bolt silently drops a nav it cannot read. | view must be a key of presentation.views. view and arg match [A-Za-z0-9_][A-Za-z0-9_.-]{0,63} with no ... A row with a utility action gets no nav. Every query.word before the view word needs a default that is also such a token (a default of - is not), or no row in the app gets a nav, Back included. Keep view_arg on query.word(0), as the templates do. |
| A command for each OS you support | bridge.command must define at least one of macos/linux/windows. On a missing one, at run: no bridge.command variant defined for <os> | The template gives all three. Keep them. |
| One program, no shell | bridge.command.<os> contains forbidden shell metachar, or is not argv-splittable, or references a variable inside double (single) quotes, or has an unterminated {{, or a malformed variable placeholder | Remove ; && || |, backticks, $( and quotes around {{variable}}. Put steps in the script. |
| Timeout 1 to 60 seconds | bridge.timeout_seconds must be 1..=60 (got N). Without the field Bolt waits 10 seconds. | The template sets 25. |
parse is json, lines or raw | bridge.parse "x" not in [json, lines, raw] | Use json. |
| The right block for the runtime | runtime: bridge requires a `bridge` block, or runtime must be one of [bridge, http_local, transform] | Use runtime: bridge with a bridge: block. |
| No company-only fields | <field> is not allowed in a user utility (admin-only field) | Remove it. This includes cache_ttl_seconds. |
| Unknown keys are refused | unknown field | Remove or fix the key. |
| A newer pack than the installed one | Bolt did not install <name> <version>: version <old> is already installed, and a pack is only replaced by a newer version. | Pack with a higher --version. To go back to an older version, remove the installed app first: Settings, Desktop App, User Apps, the Remove button on the app's row. If a personal app shows no Remove button in your build, only Review and accept or Decline, there is no other removal path today: raise the version instead. |
| Row links and labels | The launcher refuses a link that is not http or https, or over 2048 characters, with no app file error. A button label is cut at 14 characters. | Keep links to a public https:// address. |
| Row action kinds | The launcher refuses it, with no app file error: a row's own action must be url, composer or utility. run exists only in the app file. | Declare buttons once in the app file and list them by id. |
Pitfalls.
| Pitfall | What to do |
|---|---|
| More than 8 views | The launcher refuses the app file. Overview counts as one, so 7 lists. Nest a detail inside an existing view with children instead of adding a view. |
| Looking for a filter field | There is none in the row. A filter is the second word you type, which becomes arg. |
| Scripts in a folder | A personal pack takes single files directly in scripts/. The kit is one file, bolt_app_kit.py, not a folder. |
| A folder name that is not the id | lint says id_mismatch. Name the folder after the id (~/my-app for my-app). |
| Packing again with the same version | Bolt says "version 1.0.0 is already installed, and a pack is only replaced by a newer version. To go back to an older version, remove the installed apps first." Pass a higher --version on every pack. |
| A HIGH RISK rating at install | Expected for a personal app. Any app that runs a program (tier 3) is rated high: Bolt lists "runs a program on your computer". The template's Open button uses {{row.open_url}}, which adds a second line, "opens links that are not fixed https addresses". Read the permissions, then confirm if you trust the app. |
| Writing scripts_dir anywhere else | Every mention of scripts_dir in the app file, in a comment too and in any letter case, must be {{scripts_dir}}/<file> as its own word with no quotes and no spaces inside the braces. Otherwise Bolt says it cannot tell which files the app runs and never runs it. The generated file already does this; do not add comments that name it. |
| Fancy YAML | Write plain YAML: bare keys, values on one line, no anchors, tags, | or > blocks, no tabs. The engine already writes it that way; do not hand edit it. |
| Tier 3 in the gallery | An app that runs a script and calls the network is tier 3. The public gallery does not accept it. Ship it as a personal pack. |
| Paging and writes | The engine reads the first response of each path, a list is capped at 50 rows, and it only does GET. |
| Secrets | Never put the key in config.json, fixtures.json or a row. It comes from the system keychain or a chmod 600 .env file, not from a shell variable. |
Have your agent do it.
Paste this to your coding agent and fill in the API. The steps and checks are in the Agent guide (plain Markdown).
Read https://sparcle.app/docs/extend/agent-guide.md, section 13, "Build a rich app from the portal template".
Then build me a Bolt App for <API name and docs URL>.
Follow its steps exactly and run every check it lists.
Give me the .boltpack path and one install line.