Publish

Publish (internal apps & dashboards)

Use this skill when the user wants something that outlives the turn and is reachable in a browser — a small web app, an internal API, a status page, a dashboard you generated from a query. A turn's sandbox is torn down when the turn ends; publishing ships your files to a separate, long-lived runtime that keeps running and gets a stable link.

Publish with the apps tool, action publish. Build the app in the workspace with files actions write / read; install dependencies and test with sandbox action exec (execute before sandbox-resource activation). Then publish the directory. The app must listen on the PORT env var (the runtime sets it).

Match the house style (the default)

Anything browsable you publish should look designed, not defaulted. Before you build the UI, load the design skills and apply your organization's house style unless the user asked for a different look:

• The deployment's house-style skill — if the Skills index lists a *-design skill, it carries the org's look as ready-to-paste CSS and design tokens. Start there for the look.
• taste-skill — the design process: reading the brief, layout, hierarchy, verifying the result, avoiding generic AI-design slop.
• popular-web-designs — when the user wants a specific visual reference (Stripe, Linear, Vercel…).

This is about the page a person sees — skip it for an internal-only API or a script with no UI.

Publishing

First publish, and every later update — same call, same name, a new immutable version:

apps({ action: "publish", dir: "dist", entrypoint: "node server.js", name: "status-board" })

Roll back to an earlier version (an instant pointer flip):

apps({ action: "publish", name: "status-board", rollbackTo: 3 })

Give an auto-named deployment a friendly link:

apps({ action: "publish", renameFrom: "s-1176-p-5050", name: "status-board" })

apps action publish returns { id, name, version, url, dataDir? } — give the user the full absolute url, whose path is /d/<name>/.

App bar and editing

On a configured app subdomain, signed-in people who can manage the app automatically see a slim top bar. Chat opens a resizable editing conversation beside the app. Normal app links and refreshes keep editing available for the signed-in session; viewers with read-only access see the app alone.

The bar uses a consistent neutral appearance, independent of the app's theme. Its name follows the app document title. The drawer opens directly into an empty composer; the app identity is supplied as conversation context, not pasted into the draft. The conversation survives app reloads after a publish.

Durable data — where app state must live

The app's disk is reset from source on every relaunch, with one exception: when the runtime supports durable app data it sets $DATA_DIR (and the publish result reports dataDir). Everything the app writes under $DATA_DIR survives restarts, redeploys, and platform recycles.

• Any state the app keeps — write it under $DATA_DIR. Never beside the code, never in /tmp, never in a JSON file in the app dir: all of that silently vanishes on the next relaunch.
• Database: SQLite at exactly $DATA_DIR/app.db. That specific path gets the strongest durability the runtime offers (continuous replication where enabled — ~seconds of loss window — periodic snapshots otherwise). Other files under $DATA_DIR are snapshotted periodically.
• Guard the no-persistence case: if $DATA_DIR is unset, the runtime has no durable app storage — don't build an app that quietly accumulates state on disk; say so and bake data in or fetch it live instead.
• Updating an existing stateful app? If it writes runtime state (a db, uploads, counters) anywhere else, move that state under $DATA_DIR as part of the update — do this on your own initiative; the user should never have to ask. Data deliberately baked into the repo (seed/reference files) stays where it is.

Check your work before you call it done

A published app is a new immutable version the moment the runtime accepts it — that is not the same as the app working. So for anything browsable, sanity-check it locally before you publish:

1. Run it locally. Start the server in the background on a port — e.g. PORT=8080 node server.js via sandbox action start_process with purpose: "App preview server" (background action start before sandbox-resource activation), so it keeps serving while you check.

2. Probe it with curl — confirm it answers, returns the status you expect, and the main page/endpoint is actually there (real content, not a stack trace or a blank 500):

   curl -sS -i http://localhost:8080/

3. If it's broken, fix it and check again — don't tell the user a site is ready before you've confirmed it serves. Only once it checks out do you call apps action publish and hand over the /d/<name>/ link.