Status: BUILDING (2026-07-14). Design of record for the Apps plane — hosting small server-side apps (a mini-CRM, an internal mini-tool) inside a tenant, built by agents and humans only (no bundled seed apps — the fleet writes them). Reuses two primitives Agentric already ships: the
/terminal/reverse-proxy machinery and thelauncher.tsDynamicUser isolation daemon. Nothing here is a PaaS: an App is a supervised, uid-isolated Node process reached through the same authenticated proxy the terminal uses, and its only channel out is the same pre-auth loopback the agent MCP tools already use — so every effect an App has (the HTTP into it, the agent it triggers, the data it writes) stays inside the gateway boundary.Shipped so far:
- v0.196.0 — hosting core (§1–3):
AppStore,AppSupervisor(spawn + readiness + scale-to-zero
- resident restart + per-launch
AOS_APP_TOKEN), and the login-gated/apps/<slug>HTTP+WS proxy with trusted identity injection.- v0.197.0 — authoring (§6): the human console Apps page (create · manifest + capability editor · source editor · publish/unpublish · open · stop · delete, owner/admin,
/api/apps/*) and the agent toolsapp_create/app_list/app_update(single-fileserver.jsfor v1, lands proposed, posts anapp.proposedreview card; editing a live app unpublishes it for re-review).- v0.198.0 — the
app-builderagent (§6): a bundled library agent (config/agents/app-builder/) whose CLAUDE.md teaches the single-file Node contract + theapp_*tools + the proposed→publish flow, so "build me a mini-CRM / internal tool" has a purpose-built teammate. Install-on-demand from the agent Library (not seeded), like the department generalists.- v0.199.0 — background dispatch (§4): an app triggers an agent via
POST /api/app/dispatch(per-app-secret gated), enforcing the manifest's default-denydispatchAgentscapability; the work becomes a governedTaskStoretask (createdBy = app:<slug>, run-as = the current UI member), auto-dispatched, with an optional bounded synchronouswait.GET /api/app/dispatchespolls results. So an app can hand judgement work to the fleet without any new trust surface.- v0.201.0 — multi-file authoring + pre-publish preview (§6): an app is a normal Node project dir (the entry can
require('./lib/…'), read sibling templates) — the store gains sandboxed file ops (listFiles/readFile/writeFile/deleteFile, protecting the manifest +data.db), exposed as console file routes + agent toolsapp_files/app_write_file/app_delete_file. The console Apps page gains a file-tree editor and a sandboxed preview iframe (owner/admin can reach an unpublished app via the proxy —ensureReady({allowUnpublished})— so you see it before publishing).- v0.204.0 — secrets (§4.1): an app holds real credentials. A manifest-declared
capabilities.secretskey whose value a human set (in the Settings tab, sealed underapp:<slug>) is injected asprocess.env.KEYat launch (reuses the vault, principalapp:<slug>→*), and an app can re-read one on demand viaPOST /api/app/secret/get— both default-deny (only declared keys). Value never leaves the vault into audit/GET responses. Console Settings tab shows set/unset per key + a write-only value field.- v0.205.0 — custom domains (§9): a published app can bind custom domains (
my.tool.com). A request whoseHostmatches serves that app at the domain root, on a separate origin from the console and without a console login (public).TenantRegistry.appForHostresolves Host → app (10s-cached, published-only, invalidated on edit);serveAppDomainproxies root-mounted + strips identity. Owner/ admin bind domains in Settings; reserved hosts (base domain / tenant subdomains / localhost / IPs) and cross-app collisions are rejected. This is also the separate-origin isolation for the custom-domain path — a domain-served app is cross-origin, so its JS can't reach the console cookie/API. DNS + TLS are external (point a record at the box, terminate TLS in front).Still to build: Linux uid-isolation (§3.3),
app_history/app_revertrevisions,secret_request/admin-assignment for apps,/api/app/notify. Separate-origin isolation is now solved for custom domains; the default/apps/<slug>path is still same-origin as the console (fine for internal tools; use a custom domain — or a future per-app subdomain — for anything public or untrusted).
Agentric already hosts two kinds of running code: sessions (tmux-backed agent runs, proxied via
ttyd) and triggers (Automations firing sessions). It already renders one kind of app: a
published .html artifact in a sandboxed, null-origin iframe (ArtifactBody,
web/src/App.tsx:3904). That covers static, client-side mini-tools — but a null-origin sandbox
can't persist (localStorage throws), can't reload data, and can't reach the API. A mini-CRM needs a
backend: durable records + server logic.
Apps are the missing long-lived, addressable, server-side unit — a Node process + its own SQLite, reachable at a stable URL, that humans use through a UI and that can trigger agents in the background.
| Session | Automation | Artifact (HTML) | App | |
|---|---|---|---|---|
| What it is | an ephemeral run | a firing condition | a static render | a hosted server-side app |
| Lifetime | dies when done | standing | snapshot at publish | installed → running (scale-to-zero), long-lived |
| Code | agent + claude | — | client-side JS only | Node stdlib + SQLite |
| Reached at | ttyd proxy | — | Library preview | /apps/<slug>/… authed proxy |
| Persistence | — | — | none (null origin) | own data.db |
| Isolation | per-member uid (Phase A) | — | iframe sandbox | per-app DynamicUser + slice |
| Effects out | gateway (gate hook) | gateway | none | gateway via /api/app/* loopback |
| Built by | — | owner/admin | agent publish |
agents + humans (app_* tools / console) |
The design principle throughout: Apps invent no new trust boundary and no new run engine. Hosting = the terminal reverse-proxy pointed at a supervised process. Isolation = the launcher daemon. Background work = an enqueue into the existing Tasks/Automations machinery under a new provenance.
Routing — sharedTerminalProxy / pipeUpgradeToTtyd (src/server.ts:4671+). The main Node
server already reverse-proxies a subpath (HTTP and the WebSocket upgrade) to a locally-listening
port, cookie-gated with the same authz nginx enforces in prod. Apps get a sibling /apps/<slug>/…
branch that proxies the same way.
Isolation — launcher.ts (AOS_UID_ISOLATION, Linux). The privileged, argv-only, zero-dep daemon
that already runs sessions as a DynamicUser in a per-principal slice (mem/cpu/pids caps, 0700
home). It gains one verb, start_app, to run an app process as its own isolated uid. On macOS (no
AOS_UID_ISOLATION) apps run as plain child processes in local mode — best-effort isolation, same
honest gap the per-user isolation plan already documents.
Callback — the pre-auth loopback (src/server.ts:522+). Agent MCP tools reach the OS over
loopback with no cookie, gated by a per-session secret (x-aos-secret, verifySessionSecret),
on routes that sit before the member-auth gate. Apps get the exact same posture with a per-app
secret.
An App is an installable, governed, versioned bundle — the fourth member of the library→install→manifest→govern→version→nav family that Agents, Skills, and Automations already belong to.
<home>/apps/<slug>/
app.json # manifest (see below)
app/ # the Node source the app process runs (entry = app/server.js)
data.db # the app's own SQLite, owned by the app uid — NOT the agent-os DB
Capabilities are default-deny and enforced at the boundary, not by trust. An App can only trigger
the agents it names, only reach the network if egress:true, only read the vault keys it declares.
This is the manifest that makes hosted app code safe: the process is uid-isolated and
egress-denied, and its one privileged channel (/api/app/*) enforces capabilities per call.
Per tenant, owns the running-app table and lifecycle. Modeled on TerminalManager + launchTtyd.
slug → { pid, port, status: 'cold'|'starting'|'ready'|'crashed', lastHit, secret }
- Launch (cold → ready): allocate an ephemeral loopback port; start the app process (via
launcher.start_appon Linux, or a plainchild_process.spawnon macOS) with env:PORT,AOS_APP_TOKEN(the per-app secret),AOS_APP_SLUG,AOS_LOOPBACK(the OS base URL),AOS_APP_HOME(its dir), plus any declaredsecrets. Health-check readiness (pollGET /or a/__health) before markingreadyand releasing proxied requests. - Scale-to-zero: a tick idle-kills any app past
idleTimeoutSecwith no hits — the same teardown disciplineTerminalManager.markTurnIdleapplies to headless sessions.residentapps skip this (KeepAlive, restart-with-backoff on crash — mirrorSlackSocket). - Crash/backoff: capped restart backoff; a repeatedly-crashing app parks
crashedand the proxy serves a 502 status page instead of hot-looping.
A sibling to the /terminal/ branch, reusing the same helpers:
if (p.startsWith('/apps/')) return appProxy(rt, req, res) // HTTP
// and in server.on('upgrade'):
if (req.url?.startsWith('/apps/')) return appUpgrade(rt, req, socket, head) // WS
appProxy:
- Auth — resolve the session cookie →
me(being logged in is enough to view; per-app access lists are a §9 extension). Reject 401 if absent, mirroring the terminalauth_request. - Resolve —
slugfrom the path;AppSupervisor.ensureReady(slug)(launch-if-cold, await readiness). - Proxy — pipe HTTP (and the WS upgrade via
pipeUpgrade-style) to the app's loopback port, stripping/apps/<slug>and injecting:X-Forwarded-Prefix: /apps/<slug>— so the app builds correct absolute URLs (the exactX-Forwarded-*discipline the nginx note in CLAUDE.md already warns about),X-Aos-Member: <me.email>andX-Aos-Role: <role>— trusted because the proxy injects them after stripping any client-supplied copy. This is how the app knows who is using it without holding the session cookie.
In the multi-tenant registry the tenant resolves first (host/x-aos-tenant), then /apps/<slug>
within that runtime; in process-per-tenant it's purely the path. In prod, nginx forwards /apps/ to
the Node server (which sub-proxies) so the single authenticated path is preserved — same reason
/terminal/ goes through the app and not straight to ttyd.
On Linux (AOS_UID_ISOLATION), the app runs as its own DynamicUser in its own slice:
- home =
<home>/apps/<slug>/at 0700 → apps are mutually unreadable; the app uid ownsdata.db. - slice caps (mem/cpu/pids) reuse the per-member slice-cap machinery.
egress:false⇒PrivateNetwork/ outbound-deny, loopback-only. This matters because agents wrote this Node code — it is semi-trusted, so the OS seatbelt is the point, and the only way out is the loopback the OS controls.egress:trueis an explicit, reviewed capability.
start_app validates argv/paths exactly like start_session (the launcher stays small, argv-only, no
shell — it is the box's one privileged component). On macOS there is no equivalent: child_process
with a separate cwd/home/port, isolation best-effort. Gate identically to AOS_UID_ISOLATION and
document the gap.
The app has no ambient authority. To trigger an agent it POSTs to a new pre-auth loopback route
gated by its per-app secret — the same shape as the agent MCP tool routes (src/server.ts:522+):
POST /api/app/dispatch headers: x-aos-app-secret: $AOS_APP_TOKEN
{ agent: "support-bot", goal: "…", input: {…}, mode: "headless"|"interactive",
wait?: boolean, runAsMember?: "<email-from X-Aos-Member>" }
Handler (before the member gate):
verifyAppSecret(slug, header)→ 403 on mismatch.- Capability check —
agent ∈ manifest.capabilities.dispatchAgents, else 403. This is where default-deny is enforced per call. - Create the work through the existing engine — a
TaskStoreautoDispatch task (or a directAutomationsspawn) with:spawned_by = app:<slug>— a new provenance source alongsideautomation:<id>,chat:<agent>,task:<id>. It slots straight intocanViewRow, the pile-up guard,TASK_MAX_ATTEMPTS, and audit.run_as= the current UI member (fromX-Aos-Member, validated as a real member) if the app forwards it, elsemanifest.owner. So the accountable identity is the actual human using the app — the same run-as/provenance split chat already uses.
wait:true→ block on the task liketask_waitand return the delegate's result to the app (a synchronous "run this agent and give me the answer" call from inside the UI).
Companion read routes (all per-app-secret gated): GET /api/app/dispatches (this app's runs +
status), POST /api/app/notify (post an Inbox card / DM to the owner via resolveRecipients). Every
one is audited (app.dispatch, app.notify) — an App is a first-class principal in the audit log.
An App needs credentials (a Stripe key, an external API token, a DB URL) the same way agents and shell
tools do. Apps reuse the existing secrets vault (src/edge/secret-crypto.ts, encrypted at rest,
value kept out of audit/approval-card/policy args) — no new secret store. Three paths, mirroring the
agent model exactly, all injection/read only — none widens who can decrypt a value:
-
Declared in the manifest (launch-time env injection).
capabilities.secrets: ["STRIPE_KEY"]resolves each key via the vault and exports it into the app process env at launch — the direct parallel to an agent manifest'sshellSecrets+injectShellSecrets. Sealed under the app's own principal (app:<slug>) or tenant-wide*; auditedshell.secret.injected/unresolvedwithvia:'app-manifest'. Default-deny: a key not listed is never injected. -
Admin-assigned (central grant). Settings → Secrets can assign a stored secret to an app (the
secret_assignmentstable gainsapp:<slug>as an assignee alongside agents) — the central-grant inverse of the manifest list, so one canonical value fans out without a per-app copy. Injection only;via:'assignment'. -
Runtime read + request (
/api/app/*, per-app-secret gated). Env-at-launch isn't enough for a key rotated mid-run or fetched on demand, so an App gets loopback parallels tosecret_get/secret_request:POST /api/app/secret/get { key }→ returns the value only ifkey ∈ capabilities.secretsor an assignment grants it (read at call time, so a rotated value is picked up); 403 otherwise. Auditedapp.secret.read(never the value).POST /api/app/secret/request { key, reason }→ the ASK counterpart: carries only key + reason (never a value, so nothing lands anywhere logged), posts asecret.requestcard to owner/admins (Inbox + Settings → Secrets → App requests), auto-detecting the same provide (key absent → human types it, sealed underapp:<slug>or*) vs access (key exists but scoped away → human grants, server re-scopes the sealed value to the app, no re-type) modes the agentsecret_requestuses. Resolved viaPOST /api/secrets/requests/:id/fulfill, which can also inject into the app's env on next launch. Auditedsecret.requested/.fulfilled/.granted.
The invariant holds: an assignment or a manifest declaration is injection only, never a widening of
secret_get; and because reads go through the capability-gated loopback, a secret the app wasn't
granted is unreachable even though the app runs its own Node code.
<home>/apps/<slug>/data.db — the app's own SQLite, owned by the app uid, deliberately not the
agent-os DB (keeps app rows out of the OS tables and keeps the tenant boundary clean). The app owns
its schema and migrations; the OS never reaches into it.
Agents that need to work on app data do it through the app's own HTTP endpoints or a dispatched task, never by touching the file — that encapsulation is what makes it an App and not a shared table. An App that wants to expose data to agents publishes an endpoint the dispatched agent calls (looping back in through the authed proxy, or a dedicated app-internal API the agent is handed).
No bundled seed apps. The library is empty until someone builds an app. Two authoring paths, both
landing the same <home>/apps/<slug>/ bundle:
Agent-authored (app_* MCP tools — parallel to agent_create / skill_propose):
app_scaffold({ name, capabilities })— writes a minimal base-path-aware Node template into the agent's working folder (server.jsthat bindsPORT, honorsX-Forwarded-Prefix, readsAOS_APP_TOKEN, opensdata.db) + a stubapp.json.app_propose({ slug, dir })— likeskill_propose: lands a NOT-YET-PUBLISHED app + aapp.proposedinbox card for an owner/admin to review the code + capabilities and publish. An app that candispatchAgentsoregressshould not self-activate.app_update/app_history/app_revert— self-only, snapshotting each change to the existing revisions backbone (agent-revisions.tsstyle / aapp_revisionstable), so a bad edit rolls back. No app edits another app.
Human-authored (console → Apps page): upload/edit the bundle, edit the manifest + capabilities, Publish. Publishing (the governance gate) is what makes an app routable and lets the supervisor launch it; it appears in nav.
Governance of the code itself is the honest hard part: an owner publishing an app is vouching for its Node source. Surface a diff on publish (revisions make this free) and keep capabilities default-deny so an unreviewed app is inert (no agents, no egress, no secrets) even if published.
"A Node app" implies npm install → supply-chain + disk + the egress you denied in §3.3. Tier it in
the manifest:
stdlib(default) — Node built-ins + a small provided helper lib (adata.dbwrapper, the/api/app/*client). Zero third-party code, matches the OS's own zero-dep stance. Most mini-tools fit here.vendored— a curated, OS-shipped allowlist of vetted packages, materialized at launch.npm— arbitrary deps. An explicit reviewed capability: install happens at build/publish time under review (egress open only then), never at runtime; runtime stays egress-denied.
AppSupervisor(src/state/apps.tsorsrc/edge/app-supervisor.ts): manifest load, port table,child_processlaunch + readiness + scale-to-zero idle-kill + crash backoff. macOS-first (plain spawn) so it's testable without the launcher.- Proxy branch in
src/server.ts:appProxy+appUpgrade, cookie auth,X-Forwarded-Prefix+X-Aos-Memberinjection. Reuse the ttyd pipe helpers. /api/app/dispatchloopback route + per-app secret (verifyAppSecret) + capability check +spawned_by = app:<slug>provenance intoTaskStore. Wireapp:<slug>intocanViewRow/audit. Same slice: secrets (§4.1) — manifestcapabilities.secretslaunch injection (reuseinjectShellSecrets),app:<slug>as asecret_assignmentsassignee, and the/api/app/secret/get+/api/app/secret/requestloopback routes.launcher.tsstart_appverb (Linux isolation) behindAOS_UID_ISOLATION; DynamicUser + slice +PrivateNetworkwhenegress:false.- Authoring:
app_scaffold/app_propose/app_update/app_history/app_revertMCP tools + the/api/apps/*console routes +app_revisions. Publish gate (owner/admin) +app.proposedinbox card. - Console Apps page: install/list, manifest + capability editor, publish/diff, per-app status
(cold/ready/crashed), logs, open-in-new-tab to
/apps/<slug>. - Dependency tiers (§7):
stdlibfirst;vendored/npmas follow-ups.
- Per-app access lists — v1: any logged-in member can open any app. Later: an app's
accessnames members/roles, enforced inappProxy(likecanRunfor agents). - Custom domains / subdomain-per-app — v1 is path-based
/apps/<slug>. The registry already resolves tenants by subdomain; an app-subdomain is a later routing extension. - Separate-origin isolation (security). Apps render at
/apps/<slug>, the SAME origin as the console, so a published app's client-side JS opened top-level ("Open in new tab") runs at the app-os origin and could call the authed/api/*with the viewer's cookie. The preview iframe is already sandboxed (opaque origin, noallow-same-origin), so it can't reach the console — but the top-level case wants real isolation: serve apps from a distinct origin (subdomain-per-app / a dedicated apps domain) with their own auth, or a strict per-app CSP. Track before apps host anything sensitive. - Shared app data ↔ KB/Tasks bridges — an app reading/writing the OS's own KB or Tasks via
/api/app/*(capability-gated) rather than only its privatedata.db. npm/vendoreddependency tiers beyondstdlib.- App marketplace / export-import — apps are per-tenant bundles; a cross-tenant catalog (like the agent library) is a future, but there are still no first-party seed apps — the catalog would only ever hold community/agent-authored apps.
One-paragraph summary. An App is a supervised, uid-isolated Node+SQLite process reached at
/apps/<slug>/ through the same authenticated reverse-proxy the terminal uses, and allowed out only
through the same pre-auth loopback the agent tools use — where a default-deny capability manifest
decides which agents it can trigger, whether it has network, and which vault secrets it sees (injected
at launch or read/requested at runtime through the same capability gate). Hosting reuses
sharedTerminalProxy; isolation reuses launcher.ts; background work reuses Tasks/Automations under a
new app:<slug> provenance. Apps are built only by agents (app_* tools, proposed-then-published) and
humans (console) — nothing ships seeded. No PaaS, no second trust boundary: every effect an App has
still passes through the one gateway.
{ "id": "mini-crm", // DNS-safe slug; the /apps/<slug> segment "name": "Mini CRM", "icon": "contact", // lucide name or raw SVG, same as agents "entry": "app/server.js", // node entry; must bind process.env.PORT, honor X-Forwarded-Prefix "runtime": { "node": ">=22" }, "lifecycle": "scale-to-zero", // or "resident" "idleTimeoutSec": 900, // scale-to-zero teardown after N idle seconds "capabilities": { // the governance contract — default-deny "dispatchAgents": ["support-bot"], // which agents this app may trigger in bg ([] = none) "egress": false, // outbound network (default false → PrivateNetwork/deny) "secrets": [], // vault keys injected into the app env at launch "dependencies": "stdlib" // "stdlib" | "vendored" | "npm" (npm = reviewed capability) }, "owner": "user@…", // accountable human; default run-as for bg dispatch "createdBy": "agent:app-builder", // provenance of authorship "version": 3 // bumped per revision (see §6) }