docs(release): v0.4.0 release pass — positioning, CHANGELOG, release notes

tastyeffectco · claude · tastyeffectco · commit 41f13fc496a6 · 2026-06-25T19:52:21.000Z
- README: reposition as "Self-hosted control plane for AI-built apps"; add an above-the-fold "What you get" list (web console, runtime presets, live preview URLs, agent tasks, app config/secrets, snapshots/fork/restore, activity/events, process logs, settings/lifecycle); extend Known limitations (Docker-only; no Compose/local DB/Git import yet). - CHANGELOG: cut [0.4.0] — 2026-06-25 (was Unreleased); add Settings (GET/PATCH lifecycle), base-image contract, and test-foundation entries; honest known limitations (v1 delete purge, keepalive_until not surfaced, warming page 200, Docker-only, no Compose/local DB/Git import); note it rolls up the v0.3.0 work. - docs/release-notes-v0.4.0.md: draft GitHub release notes. - installer: default base tag sandboxd-base:0.4.0-test -> :0.4.0 (drop confusing "test" language at launch; SANDBOXD_IMAGE override unchanged). No feature/runtime changes. Gate green: gofmt/vet/build/go test + OpenAPI contract + installer syntax + console tsc/test(11)/build. Validated by the from-zero VPS RC QA pass. PR #35 to be marked ready (not merged). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,11 +5,19 @@ All notable changes to sandboxd are documented here. The format is based on
 [Semantic Versioning](https://semver.org/) (pre-1.0: a minor bump adds features,
 a patch is fixes only).
 
-## [Unreleased] — v0.4.0 (integration: `release/v0.4-apps-console`)
+## [0.4.0] — 2026-06-25
 
-One release-candidate integration of all accepted v0.3 + v0.4 work. Linearly
-stacked on `console` → `feat/v0.4-snapshots-observability` → `feat/runtime-manifest`.
-`main` stays at 0.2.0 until this is cut.
+**Self-hosted control plane for AI-built apps** — adds a web console, runtime
+presets, snapshots/fork/restore, observability, process logs, and a read-only
+(plus editable lifecycle) settings view on top of the v0.3 app/config/secrets
+foundation. Integration of all accepted v0.3 + v0.4 work, validated by a
+from-zero VPS release-candidate QA pass.
+
+### Highlights
+Web console · runtime presets (React/Vite, Next.js, Node/Express, FastAPI,
+Worker) · live preview URLs · agent tasks · app config & secrets (write-only
+secrets) · snapshots / fork / restore · activity/events timeline · per-process
+logs · settings with editable idle/keepalive lifecycle controls.
 
 ### Added
 - **Snapshots, fork & restore.** Public `POST/GET/DELETE /v1/snapshots`,
@@ -43,11 +51,25 @@ stacked on `console` → `feat/v0.4-snapshots-observability` → `feat/runtime-m
   `app_healthy`; `build_ok` stays for back-compat (true only when `passed`).
 - **`web.restart_after_task` / worker `restart_after_task`.** Per-process
   reload-by-restart for runtimes without live reload.
+- **Settings / instance overview.** `GET /v1/settings` — a read-only, safe
+  instance summary (version, networking/preview, auth mode, runtime/storage,
+  lifecycle, egress mode, agent providers, presets, capabilities; never any
+  secret). A console **Settings** page renders it.
+- **Editable lifecycle tunables.** `PATCH /v1/settings` edits ONLY the idle-reap
+  enable/threshold and keepalive-max (strict allowlist; any other key → 400),
+  persisted and **hot-applied** to the running reaper/keepalive; the console
+  Settings page edits them. Everything else stays read-only / env-managed.
+- **Base image contract.** `docs/base-image.md` documents what a custom base
+  image must provide (runtimed, `sandbox` uid/gid 1000, workspace path, no
+  privileged/Docker socket) and how to select one via `SANDBOXD_IMAGE`.
 - **Shared-host installer & preview port.** `scripts/dev/install-v04-ubuntu.sh`
   with shared-host mode (loopback API, configurable `HTTP_PORT`), and preview
   URLs that include the public port when `HTTP_PORT` ≠ 80.
+- **Test foundation.** Public-surface + JSON-shape contract tests (sandboxd is
+  the contract), a console unit-test runner (vitest) with API-mirroring fixtures,
+  and `docs/release-checklist.md` for manual VPS sign-off.
 - **Docs.** `docs/sandbox-manifest.md`, OpenAPI updates (`/v1/presets`,
-  process logs, `runtime_preset`, `processes`, task health fields).
+  `/v1/settings`, process logs, `runtime_preset`, `processes`, task health fields).
 
 ### Fixed
 - **Explicit `build.command: ""` now skips the build check** (was overwritten by
@@ -66,6 +88,14 @@ stacked on `console` → `feat/v0.4-snapshots-observability` → `feat/runtime-m
   can't tell "warming" from "ready").
 - Per-task `agent.log` transcript can be empty on task timeout — persistence
   needs investigation.
+- **Docker backend only** — OCI/containerd/Kata are a future runtime provider.
+- **Out of scope for v0.4:** Git/GitHub import, managed databases/sidecars, and
+  Docker-Compose-inside-the-sandbox.
+
+---
+
+> v0.4.0 rolls up the v0.3.0 work below (app config & secrets, web console +
+> `/v1` OpenAPI) — kept here for detail.
 
 ## [Unreleased] — v0.3.0 (integration: `console`)
 
diff --git a/README.md b/README.md
@@ -2,9 +2,10 @@
 
 
 <p align="center">
-  <b>The open-source engine for AI app-builder products.</b><br/>
+  <b>Self-hosted control plane for AI-built apps.</b><br/>
   Give every user an isolated cloud dev environment, a built-in coding agent,
-  and a live preview URL — self-hosted, on one machine, in one command.
+  and a live preview URL — with a web console to drive it all. Self-hosted, on
+  one machine, in one command.
 </p>
 
 <p align="center">
@@ -18,6 +19,17 @@
 
 <img width="1100" height="816" alt="sandboxd-demo" src="https://github.com/user-attachments/assets/f794ff9b-8ffe-47e8-bd30-22541f870f09" />
 
+## What you get
+
+- **Web console** — create and open apps, watch previews, run agent tasks, manage everything from a browser (or drive the same `/v1` API directly).
+- **Runtime presets** — one-step React/Vite, Next.js, Node/Express, FastAPI, or Worker apps (`GET /v1/presets`); each boots and reloads after agent edits.
+- **Live preview URLs** — each app is reachable at its own shareable link; sleeps when idle, wakes on request.
+- **Agent tasks** — submit a prompt, stream the agent's progress, get the build/health result.
+- **App config & secrets** — per-app key/values; sensitive values are write-only (set once, encrypted at rest, never returned).
+- **Snapshots / fork / restore** — capture a workspace, fork it into a new app, or restore in place.
+- **Activity / events** — a durable per-app timeline of what happened.
+- **Process logs** — per-process status (web + workers) and tail-able logs.
+- **Settings / lifecycle controls** — a read-only instance overview, with editable idle-reap / keepalive tuning, applied live.
 
 ## What is sandboxd? (start here)
 
@@ -374,6 +386,10 @@ Tracked, non-blocking — details in [`docs/sandbox-manifest.md`](docs/sandbox-m
 - The wake/warming interstitial returns HTTP `200` (callers can't distinguish
   "warming" from "ready" by status code alone).
 - Per-task `agent.log` can be empty on task timeout (transcript persistence WIP).
+- **Docker backend only** (OCI/containerd/Kata are a future provider; see
+  [`docs/sandbox-manifest.md`](docs/sandbox-manifest.md)).
+- **Not yet:** Git/GitHub import, a managed-database/sidecar story, and
+  Docker-Compose-inside-the-sandbox are deliberately out of scope for v0.4.
 
 ## License
 
diff --git a/docs/release-notes-v0.4.0.md b/docs/release-notes-v0.4.0.md
@@ -0,0 +1,67 @@
+# sandboxd v0.4.0 — Self-hosted control plane for AI-built apps
+
+v0.4 turns sandboxd into a complete, operable platform for AI-built apps: a **web
+console**, one-step **runtime presets**, **live preview URLs**, **agent tasks**,
+**app config & secrets**, **snapshots / fork / restore**, an **activity/events**
+timeline, **per-process logs**, and a **settings** view with editable lifecycle
+controls — all self-hosted on one machine that just needs Docker.
+
+## Highlights
+
+- **Web console** — create and open apps, watch live previews, run agent tasks,
+  and manage config/secrets, snapshots, activity, and settings from a browser
+  (or use the same public `/v1` API directly).
+- **Runtime presets** — `GET /v1/presets` + `runtime_preset` on create for
+  **React/Vite, Next.js, Node/Express, FastAPI, Worker**. Each seeds a starter,
+  writes a `sandbox.yaml`, boots, and reloads after agent edits (Vite HMR,
+  `uvicorn --reload`, or a post-task process restart — including healing a
+  Next.js `next build` that would otherwise poison the dev server).
+- **Live preview URLs** — every app gets its own shareable link; idle sandboxes
+  sleep and wake on request.
+- **Agent tasks** — submit a prompt, stream progress, get an honest result
+  (`build_status` passed/failed/skipped, `preview_ok`, `app_healthy`).
+- **App config & secrets** — per-app key/values; sensitive values are write-only,
+  encrypted at rest, and never returned.
+- **Snapshots / fork / restore** — capture a workspace (generated/dependency dirs
+  excluded), fork it into a new app, or restore in place — with workspace
+  ownership normalized so forks boot cleanly.
+- **Activity / events** — a durable per-app timeline.
+- **Process logs** — per-process status (web + workers) and tail-able logs.
+- **Settings / lifecycle** — a read-only instance overview, plus editable
+  idle-reap / keepalive tuning that hot-applies (a strict allowlist; nothing else
+  is editable, and no secret is ever shown).
+
+## Install
+
+On a fresh Ubuntu host:
+
+```bash
+git clone https://github.com/tastyeffectco/sandboxd && cd sandboxd
+git checkout v0.4.0
+scripts/dev/install-v04-ubuntu.sh
+```
+
+It builds the base image + control plane + console and brings the stack up with
+Docker Compose (Traefik for preview/console URLs, the API on loopback). See
+[`docs/release-checklist.md`](release-checklist.md) for the full smoke test.
+
+## Known limitations (non-blocking)
+
+- `DELETE /v1/sandboxes/{id}` **purges** the workspace; the legacy internal
+  `DELETE /sandbox/{id}` stops and keeps it.
+- `keepalive_until` is honored but not surfaced in `GET /v1/sandboxes/{id}`.
+- The wake/warming interstitial returns HTTP `200`.
+- Per-task `agent.log` can be empty on task timeout.
+- **Docker backend only** (OCI/containerd/Kata are a future provider).
+- **Not yet:** Git/GitHub import, managed databases/sidecars, and
+  Docker-Compose-inside-the-sandbox.
+
+## Validation
+
+Validated by a from-zero VPS release-candidate QA pass against this branch
+(install → console → presets → previews → agent tasks → snapshots/fork →
+process logs → events → config/secrets redaction → settings/lifecycle →
+idle/wake/keepalive), plus the full automated gate (Go test + OpenAPI contract +
+console typecheck/test/build).
+
+**Full changelog:** see [`CHANGELOG.md`](../CHANGELOG.md).
diff --git a/scripts/dev/install-v04-ubuntu.sh b/scripts/dev/install-v04-ubuntu.sh
@@ -37,7 +37,7 @@ die()  { printf '  \033[31m✗ %s\033[0m\n' "$*" >&2; exit 1; }
 # ── config (override via env) ────────────────────────────────────────
 DATA_DIR="${SANDBOXD_DATA_DIR:-/var/lib/sandboxd-v04-test}"
 LOG_DIR="${SANDBOXD_LOG_DIR:-$DATA_DIR/log}"
-BASE_IMAGE="${SANDBOXD_IMAGE:-sandboxd-base:0.4.0-test}"
+BASE_IMAGE="${SANDBOXD_IMAGE:-sandboxd-base:0.4.0}"
 CONSOLE_USER="${CONSOLE_USER:-demo}"
 CONSOLE_PASS="${CONSOLE_PASS:-}"   # generated if empty
 
