Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

feat(console): docs site guide, AGENTS routing, and deployment docs (PR 5/5)

刘祺祥65104b9c2464
diff --git a/AGENTS.md b/AGENTS.md
index a9cc90a7e..ef0d20dd0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,6 +14,7 @@ Use this file as the root router for the monorepo. Prefer the nearest `AGENTS.md
- `kubernetes/`: Kubernetes operator, CRDs, task-executor, and Kind e2e tests
- `manifests/charts/`: Helm charts (base, controller, server, ingress-gateway, node-agent, fast-sandbox, opensandbox umbrella)
- `cli/`: `osb` command-line client and bundled CLI skills
+- `console/`: developer console (React SPA + FastAPI BFF), optional K8s examples; no server/spec changes
- `tests/`: cross-language end-to-end SDK tests
- `docs/`, `examples/`, `oseps/`: documentation, samples, and proposals
@@ -26,6 +27,7 @@ Use this file as the root router for the monorepo. Prefer the nearest `AGENTS.md
- For cross-cutting changes spanning spec, server, and SDKs, start with `specs/AGENTS.md` and then read affected consumer guides.
- For runtime component changes under `components/**`, read the nearest `README.md` or `DEVELOPMENT.md`; keep component APIs aligned with `specs/` and SDK consumers.
- For CLI changes under `cli/**`, read `cli/README.md` and verify command help/output behavior alongside unit tests.
+- For console changes under `console/**`, read `console/README.md` and `console/docs/`; run `console/web` build and keep BFF env docs aligned with `console/k8s/*.example.yaml`.
- For cross-language e2e tests under `tests/**`, read the language-local README and keep test assumptions aligned with current server and SDK behavior.
- For areas without a local `AGENTS.md`, use the nearest `README.md`, `DEVELOPMENT.md`, and CI workflow as the next source of truth.
diff --git a/console/docs/04-deployment-checklist.md b/console/docs/04-deployment-checklist.md
new file mode 100644
index 000000000..0bf9312e6
--- /dev/null
+++ b/console/docs/04-deployment-checklist.md
@@ -0,0 +1,45 @@
+# Deployment checklist
+
+## 1. Prepare `tenants.toml`
+
+Same as the lifecycle server. In-cluster: ConfigMap **`opensandbox-tenants`**. Locally:
+
+```bash
+chmod +x console/scripts/extract-tenants-toml.sh
+console/scripts/extract-tenants-toml.sh
+# reads console/k8s/tenants-configmap.example.yaml by default
+# writes console/bff/tenants.local.toml (gitignored; no real keys in git)
+```
+
+Custom ConfigMap path: `console/scripts/extract-tenants-toml.sh /path/to/configmap.yaml`
+
+## 2. Build images
+
+See [06-build-and-deploy.md](./06-build-and-deploy.md). BFF Dockerfile: [../bff/Dockerfile](../bff/Dockerfile).
+
+## 3. Apply Kubernetes manifests
+
+1. `kubectl apply -f console/k8s/console-bff-secret.example.yaml` (replace placeholders)
+2. Ensure ConfigMap `opensandbox-tenants` exists (shared with server)
+3. `kubectl apply -f console/k8s/console-bff-rbac.example.yaml` (platform pages / probes)
+4. `kubectl apply -f console/k8s/console-bff-deployment.example.yaml`
+5. `kubectl apply -f console/k8s/console-web-deployment.example.yaml`
+6. `kubectl apply -f console/k8s/console-ingress.example.yaml` (set `host`)
+
+See [k8s/README.md](../k8s/README.md).
+
+## 4. Verify
+
+```bash
+curl -s http://localhost:8091/health
+
+curl -s -c /tmp/cj -X POST http://localhost:8091/api/auth/admin \
+ -H 'Content-Type: application/json' \
+ -d '{"adminToken":"YOUR_ADMIN_TOKEN"}'
+
+curl -s -b /tmp/cj http://localhost:8091/api/admin/stats/runtime
+```
+
+## 5. Optional follow-ups
+
+- Helm subchart under `manifests/charts/` (not bundled yet)
diff --git a/console/docs/05-feature-matrix.md b/console/docs/05-feature-matrix.md
new file mode 100644
index 000000000..0a55f65a0
--- /dev/null
+++ b/console/docs/05-feature-matrix.md
@@ -0,0 +1,57 @@
+# Feature matrix
+
+Core lifecycle flows go through the **BFF** to the Lifecycle API. Status legend:
+
+| Symbol | Meaning |
+|--------|---------|
+| ✅ | Implemented with a tested path |
+| 🔶 | UI present; depends on cluster/RBAC or partial admin/tenant support |
+| 📋 | Planned follow-up PR (not in MVP) |
+
+## MVP — tenant developers
+
+| Feature | Status | BFF | Web |
+|---------|--------|-----|-----|
+| Tenant key login | ✅ | `/api/auth/tenant` | `/login` |
+| Admin token login | ✅ | `/api/auth/admin` | `/login` |
+| Sandbox list / filter | ✅ | `GET /api/sandboxes` | `/sandboxes` |
+| Sandbox detail | ✅ | `GET /api/sandboxes/{id}` | `/sandboxes/:id` |
+| Runtime logs | ✅ | diagnostics logs | detail |
+| Create sandbox | ✅ | `POST /api/sandboxes` | `/sandboxes/new` |
+| Renew / delete | ✅ | renew / DELETE | detail |
+| Endpoint | ✅ | `.../endpoints/{port}` | detail |
+| Runtime / TTL summary | ✅ | `runtimeSummary` | list / detail |
+| Pause / resume | 🔶 | pause / resume | detail |
+| Tenant overview KPI | ✅ | list aggregation | `/` |
+| Colored log viewer | ✅ | diagnostics | detail |
+
+## MVP — admin and platform
+
+| Feature | Status | BFF | Web |
+|---------|--------|-----|-----|
+| Global sandbox list | ✅ | `/api/admin/sandboxes` | `/admin/sandboxes` |
+| Runtime stats | ✅ | `/api/admin/stats/runtime` | `/` (admin) |
+| Snapshots | ✅ | tenant + admin | `/snapshots` |
+| Diagnostics | ✅ | logs / events | `/diagnostics` |
+| Pools | ✅ | `/api/pools*` | `/pools` |
+| Admin sandbox ops | ✅ | `?tenant=` proxy | `/sandboxes/:id` |
+| Component health | 🔶 | K8s deployments + node-agent | `/platform/health` |
+| Archive logs | 🔶 | OSS + BFF read | log tab |
+| Version | ✅ | `/api/version` | `/platform/version` |
+| K8s workloads / events | 🔶 | admin k8s APIs | `/platform/k8s/*` |
+
+## Follow-up PRs (extended scope)
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Sandbox apply history | 📋 | PostgreSQL; server-owned store — [07-sandbox-history.md](./07-sandbox-history.md) |
+| Tenant usage / image stats | 📋 | Depends on history store |
+| Grafana sandbox monitor | 📋 | BFF embed + platform settings |
+| Mirror accel / image catalog UI | 📋 | Static or registry integration TBD |
+| Server `store.lifecycle_audit` | 📋 | Not in MVP; no server changes in first PR |
+
+## Known limitations
+
+1. **Pool API** is not tenant-isolated.
+2. **K8s platform pages** require BFF ServiceAccount RBAC.
+3. **Admin diagnostics** proxy tenant keys; define product policy for your org.
diff --git a/console/docs/06-build-and-deploy.md b/console/docs/06-build-and-deploy.md
new file mode 100644
index 000000000..f692c51de
--- /dev/null
+++ b/console/docs/06-build-and-deploy.md
@@ -0,0 +1,133 @@
+# Build and deploy
+
+Source lives under [`console/`](../). Deploy **in the same cluster** as the lifecycle server; prefer in-cluster Lifecycle Service URL.
+
+Commands assume **repository root**. Kubernetes examples: [`console/k8s/`](../k8s/README.md).
+
+## Prerequisites
+
+- OpenSandbox server running (Helm `manifests/charts/opensandbox` or equivalent) with `opensandbox-server` Service.
+- ConfigMap **`opensandbox-tenants`** with the same `tenants.toml` as the server ([02-bff-config-and-secrets.md](./02-bff-config-and-secrets.md)).
+- Container registry (e.g. `YOUR_REGISTRY.example.com`).
+
+---
+
+## 1. Build images (linux/amd64)
+
+Production nodes are usually **amd64**. On Apple Silicon, use **`--platform linux/amd64`** to avoid `exec format error`.
+
+### buildx and Docker Hub
+
+If `docker pull` works but `buildx build` times out, you may be on a **`docker-container`** builder that bypasses local registry mirrors. Prefer **`docker buildx use default`**.
+
+```bash
+export REGISTRY=YOUR_REGISTRY.example.com
+export TAG=0.1.0
+export PLATFORM=linux/amd64
+
+docker buildx use default
+export DOCKER_BUILDKIT=1
+docker login "${REGISTRY}"
+```
+
+### Base image `--build-arg`
+
+Defaults: `python:3.12-slim`, `node:22-alpine`, `nginx:1.27-alpine`. Mirror to private registry if needed:
+
+```bash
+export BASE=YOUR_REGISTRY.example.com/mirror
+export PYTHON_IMAGE="${BASE}/python:3.12-slim"
+export NODE_IMAGE="${BASE}/node:22-alpine"
+export NGINX_IMAGE="${BASE}/nginx:1.27-alpine"
+```
+
+**BFF**
+
+```bash
+docker buildx build --platform "${PLATFORM}" \
+ --build-arg PYTHON_IMAGE="${PYTHON_IMAGE:-python:3.12-slim}" \
+ -t "${REGISTRY}/opensandbox-console-bff:${TAG}" \
+ -f console/bff/Dockerfile \
+ --push \
+ console/bff
+```
+
+**Web** (check [`console/web/nginx.conf`](../web/nginx.conf) BFF upstream name)
+
+```bash
+docker buildx build --platform "${PLATFORM}" \
+ --build-arg NODE_IMAGE="${NODE_IMAGE:-node:22-alpine}" \
+ --build-arg NGINX_IMAGE="${NGINX_IMAGE:-nginx:1.27-alpine}" \
+ -t "${REGISTRY}/opensandbox-console-web:${TAG}" \
+ -f console/web/Dockerfile \
+ --push \
+ console/web
+```
+
+Local web check only:
+
+```bash
+cd console/web && npm ci && npm run build
+```
+
+---
+
+## 2. Secrets and RBAC
+
+```bash
+kubectl apply -f console/k8s/console-bff-secret.example.yaml
+kubectl apply -f console/k8s/console-bff-rbac.example.yaml
+```
+
+Secret must include `BFF_SESSION_SECRET` and `BFF_ADMIN_TOKEN`.
+
+---
+
+## 3. Deploy BFF
+
+Edit [console-bff-deployment.example.yaml](../k8s/console-bff-deployment.example.yaml): image, `LIFECYCLE_API_BASE`, `BFF_CORS_ORIGINS`, `BFF_K8S_*_DEPLOYMENT`.
+
+```bash
+kubectl apply -f console/k8s/console-bff-deployment.example.yaml
+kubectl rollout status deployment/opensandbox-console-bff -n opensandbox-system
+```
+
+---
+
+## 4. Deploy Web
+
+```bash
+kubectl apply -f console/k8s/console-web-deployment.example.yaml
+kubectl apply -f console/k8s/console-ingress.example.yaml
+```
+
+Visit `https://console.example.com/login` (tenant key or admin token).
+
+---
+
+## 5. Optional features
+
+| Feature | Config |
+|---------|--------|
+| K8s workloads / probes | `BFF_K8S_PROBE_ENABLED=true` + RBAC |
+| Archive logs | node-agent OSS + `BFF_NODEAGENT_ARCHIVE_*` |
+
+---
+
+## Helm relationship
+
+Not yet part of the umbrella `opensandbox` chart; shipped as standalone Deployments.
+
+## Troubleshooting
+
+| Symptom | Check |
+|---------|--------|
+| Login 401 | Same `tenants.toml` as server; valid key |
+| Admin login fails | `BFF_ADMIN_TOKEN` in Secret |
+| `/api` 502 | nginx → BFF Service; pods Ready |
+| Health all disabled | `BFF_K8S_PROBE_ENABLED`; RBAC |
+| TLS verify to apiserver | Fix CA or temporary `BFF_K8S_INSECURE_SKIP_TLS_VERIFY` |
+| Archive empty | OSS sink required |
+| buildx Hub timeout | `docker buildx use default` or private base images |
+
+Feature status: [05-feature-matrix.md](./05-feature-matrix.md).
diff --git a/console/docs/07-sandbox-history.md b/console/docs/07-sandbox-history.md
new file mode 100644
index 000000000..8c1cc56b2
--- /dev/null
+++ b/console/docs/07-sandbox-history.md
@@ -0,0 +1,15 @@
+# Sandbox lifecycle history (deferred)
+
+Persistent sandbox **apply history**, **tenant usage**, and **image run statistics** are **not part of the initial upstream console MVP**. They depend on a future server-side persistence design (PostgreSQL audit or catalog, K8s watch vs Docker poll) and possible **major-version** Lifecycle API semantics for deleted sandboxes.
+
+Track design discussion in a follow-up OSEP/PR series. Until then:
+
+- Console reads **live Lifecycle API** data only (`GET /sandboxes`, etc.).
+- Do not enable server `[store.lifecycle_audit]` or BFF `BFF_HISTORY_*` in the MVP PR.
+
+When implemented, expect:
+
+- **Server-owned schema** under `[store]` (same pattern as snapshots), not BFF `CREATE TABLE`.
+- **Audit-first model**: PostgreSQL as a queryable copy; runtime remains source of truth for existence; `GET` after delete stays **404** unless a future major version defines tombstones.
+
+See [05-feature-matrix.md](./05-feature-matrix.md) for what ships in MVP vs follow-up PRs.
diff --git a/console/web/src/components/DismissibleAlert.tsx b/console/web/src/components/DismissibleAlert.tsx
new file mode 100644
index 000000000..9235792d3
--- /dev/null
+++ b/console/web/src/components/DismissibleAlert.tsx
@@ -0,0 +1,51 @@
+// Copyright 2026 The OpenSandbox Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { Alert, type AlertProps } from 'antd';
+import { useCallback, useState } from 'react';
+
+const STORAGE_PREFIX = 'opensandbox-console.dismiss-alert.';
+
+type Props = AlertProps & {
+ /** Stable id; dismissal is remembered in localStorage for this browser. */
+ dismissKey: string;
+};
+
+export function DismissibleAlert({ dismissKey, onClose, ...rest }: Props) {
+ const storageKey = `${STORAGE_PREFIX}${dismissKey}`;
+ const [hidden, setHidden] = useState(() => {
+ try {
+ return localStorage.getItem(storageKey) === '1';
+ } catch {
+ return false;
+ }
+ });
+
+ const handleClose: NonNullable<AlertProps['onClose']> = useCallback(
+ (e) => {
+ try {
+ localStorage.setItem(storageKey, '1');
+ } catch {
+ /* ignore quota / private mode */
+ }
+ setHidden(true);
+ onClose?.(e);
+ },
+ [onClose, storageKey],
+ );
+
+ if (hidden) return null;
+
+ return <Alert closable {...rest} onClose={handleClose} />;
+}
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index d01a7521a..226c0c236 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -211,6 +211,7 @@ export default defineConfig({
text: "Guides",
items: [
{ text: "Overview", link: "/guides/" },
+ { text: "Developer Console", link: "/guides/developer-console" },
{ text: "Credential Vault", link: "/guides/credential-vault" },
{
text: "Chained Upstream Proxy",
diff --git a/docs/guides/developer-console.md b/docs/guides/developer-console.md
new file mode 100644
index 000000000..b9a04f02c
--- /dev/null
+++ b/docs/guides/developer-console.md
@@ -0,0 +1,45 @@
+---
+title: Developer Console
+description: Optional React console and FastAPI BFF for sandbox lifecycle operations, deployed beside the lifecycle server.
+---
+
+# Developer Console
+
+OpenSandbox includes an **optional** developer console under [`console/`](https://github.com/opensandbox-group/OpenSandbox/tree/main/console) in the monorepo. It provides a web UI for common lifecycle tasks (list, create, renew, delete, endpoints, diagnostics) without putting API keys in the browser.
+
+This guide is the **published entry point**. Detailed BFF configuration, API notes, and Kubernetes examples live next to the code:
+
+| Topic | Location |
+|-------|----------|
+| Quick start | [console/README.md](https://github.com/opensandbox-group/OpenSandbox/blob/main/console/README.md) |
+| Architecture | [console/docs/01-architecture.md](https://github.com/opensandbox-group/OpenSandbox/blob/main/console/docs/01-architecture.md) |
+| BFF env / secrets | [console/docs/02-bff-config-and-secrets.md](https://github.com/opensandbox-group/OpenSandbox/blob/main/console/docs/02-bff-config-and-secrets.md) |
+| Build & deploy | [console/docs/06-build-and-deploy.md](https://github.com/opensandbox-group/OpenSandbox/blob/main/console/docs/06-build-and-deploy.md) |
+| Feature status | [console/docs/05-feature-matrix.md](https://github.com/opensandbox-group/OpenSandbox/blob/main/console/docs/05-feature-matrix.md) |
+
+## Relation to OSEP-0006
+
+[OSEP-0006](../community/oseps.md) describes a phased console and server-side auth. The in-tree implementation is a **BFF adjunct**:
+
+- Tenant **API keys** and **`BFF_ADMIN_TOKEN`** stay on the server/BFF; the SPA uses **httpOnly cookies**.
+- **Sandbox history / usage analytics** (PostgreSQL) are planned for a later release; the MVP console uses the Lifecycle API only. See [console/docs/07-sandbox-history.md](https://github.com/opensandbox-group/OpenSandbox/blob/main/console/docs/07-sandbox-history.md).
+
+## High-level layout
+
+```text
+Browser → Console Web (static) → Console BFF (/api) → Lifecycle API (/v1)
+ ↓
+ tenants.toml (same as server)
+```
+
+## Minimum deployment
+
+1. Deploy the lifecycle server (see [Kubernetes deployment](../deployment/)).
+2. Provide **`opensandbox-tenants`** ConfigMap (multi-tenant) or equivalent `tenants.toml` for the BFF.
+3. Build and apply manifests under `console/k8s/` (see [deployment checklist](https://github.com/opensandbox-group/OpenSandbox/blob/main/console/docs/04-deployment-checklist.md)).
+
+The console is **not** yet bundled in the umbrella Helm chart; run it as separate Deployments.
+
+## CI
+
+Pull requests touching `console/` run the **Console Tests** workflow (`console/web` build and BFF compile).