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.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.tsxnew file mode 100644index 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.mtsindex 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.mdnew file mode 100644index 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).