diff --git a/content/docs/build/ai-builder.mdx b/content/docs/build/ai-builder.mdx index da293da..d1770cb 100644 --- a/content/docs/build/ai-builder.mdx +++ b/content/docs/build/ai-builder.mdx @@ -137,8 +137,8 @@ If the AI can't do it, it says so — and points you at the manual path ## Live preview After each approved change, Console re-renders the affected views in -place. No reload needed. The kernel cache invalidates the touched -package; subsequent requests use the new metadata. +place. No reload needed. The runtime hot-loads the touched package's new +metadata; subsequent requests use it. ## Roll back diff --git a/content/docs/operate/observability.mdx b/content/docs/operate/observability.mdx index df5ad46..3281105 100644 --- a/content/docs/operate/observability.mdx +++ b/content/docs/operate/observability.mdx @@ -37,7 +37,7 @@ Track at least: | Request duration | Detect latency regressions | | 5xx errors | Alert on runtime failures | | Auth failures | Detect configuration or attack patterns | -| Artifact/kernel cache misses | Understand cold-start behavior | +| Readiness transitions | The process reports ready only once its kernel is built, and `/api/v1/ready` answers 503 when a data driver stops | ### Minimal Prometheus example @@ -72,14 +72,12 @@ groups: for: 10m annotations: summary: "Sustained auth failure rate — check for misconfiguration or attack" - - - alert: ObjectOSKernelColdStartHigh - expr: rate(kernel_cache_misses_total[15m]) > 1 - for: 15m - annotations: - summary: "Frequent project kernel cold starts — consider raising OS_KERNEL_CACHE_SIZE" ``` +Cold starts are not on that list. The kernel is built once, at startup, and +the process reports [ready](/docs/deploy/docker) only afterwards — there is +no steady-state cache-miss signal to alert on, so alert on readiness instead. + For OpenTelemetry, set `OS_OBS_EXPORTER=otlp` **and** `OS_OTLP_ENDPOINT` (e.g. `https:///otlp`) and ObjectOS will emit traces and metrics in OTLP format. The exporter defaults to `noop` (zero runtime cost), so OTLP diff --git a/content/docs/operate/troubleshooting.mdx b/content/docs/operate/troubleshooting.mdx index 490caee..a81c8b2 100644 --- a/content/docs/operate/troubleshooting.mdx +++ b/content/docs/operate/troubleshooting.mdx @@ -63,14 +63,13 @@ Check: - public URL and callback URL match; - OIDC discovery URL is reachable from ObjectOS; - trusted origins include the public domain; -- cookies are scoped to the correct project hostname; -- the project kernel has auth enabled. +- cookies are scoped to the deployment's public hostname. ## User cannot see records Check: -1. Correct project hostname. +1. Correct deployment hostname. 2. User belongs to the expected organization. 3. Object `read` permission. 4. Row-level security. diff --git a/content/docs/resources/faq.mdx b/content/docs/resources/faq.mdx index e2e5f97..959533d 100644 --- a/content/docs/resources/faq.mdx +++ b/content/docs/resources/faq.mdx @@ -46,15 +46,23 @@ protocol for an *external* datasource, which is a client of someone else's API rather than a surface ObjectOS serves. **Q: How is multi-tenancy handled?** -A: One ObjectOS process can serve many Environments (tenants). Hostname -→ Environment resolution caches in an LRU; each Environment has its own -database, identity, and audit log. Cookies are scoped per hostname so -sessions can't leak across tenants. +A: One deployment serves one app, against one database — see +[Architecture](/docs/architecture). Several organizations can share that +deployment: a **walled** tenancy posture (`OS_TENANCY_POSTURE`) puts up the +per-organization isolation wall, and it is a licensed capability the runtime +refuses to start without. What the wall separates is the organizations' data +and memberships, not the metadata — schema is scoped to the deployment, not +to an organization, which is why a walled deployment must also declare which +AI agents are mounted. Isolation stronger than the wall is deployment +separation: a customer that must have its own database gets its own +deployment. See [Multi-organization +deployments](/docs/reference/environment-variables#multi-organization-deployments). **Q: Can ObjectOS run in a serverless / Lambda environment?** A: The runtime is a long-lived Node process — designed for containers -or VMs, not stateless functions. The kernel cache and Better Auth -session model both depend on warm in-process state. +or VMs, not stateless functions. The kernel is built at startup and the +process reports ready only afterwards; that warm in-process state, and the +Better Auth session model, are what a per-invocation function cannot keep. **Q: Does it scale horizontally?** A: Yes. Run multiple instances behind a load balancer. Sessions live in @@ -146,13 +154,15 @@ for files + your secret manager for `OS_AUTH_SECRET`. See [Production Readiness](/docs/operate/production). **Q: Does ObjectOS have a status page?** -A: For your self-hosted deployment, status is your concern — wire -`/health` to your monitor. For hosted services, see +A: For your self-hosted deployment, status is your concern — point your +monitor at `/api/v1/health` for liveness and `/api/v1/ready` for readiness, +the pair [Docker](/docs/deploy/docker) and +[Kubernetes](/docs/deploy/kubernetes) wire up. For hosted services, see [status.objectstack.ai](https://status.objectstack.ai). **Q: What metrics should I monitor?** -A: 5xx rate, p95 latency, auth failure rate, kernel cache miss rate, -queue depth. Minimal Prometheus example in [Observability](/docs/operate/observability). +A: 5xx rate, p95 latency, auth failure rate, readiness +(`/api/v1/ready`), queue depth. Minimal Prometheus example in [Observability](/docs/operate/observability). **Q: How do I take a backup?** A: Back up the **database** and the **storage bucket** — those hold diff --git a/content/docs/resources/glossary.mdx b/content/docs/resources/glossary.mdx index 2238ecc..e1cd9c2 100644 --- a/content/docs/resources/glossary.mdx +++ b/content/docs/resources/glossary.mdx @@ -77,9 +77,12 @@ See [AI Service](/docs/configure/ai). ### Environment -A per-tenant runtime instance backed by its own database and identity. -On v4.x sometimes called *Project* (alias kept). v5.0 standardizes on -*Environment* across CLI, HTTP, env vars, and schemas. +A deployment's own identity — the id it reports as `OS_ENVIRONMENT_ID`, +persisted once a cloud binding completes. A self-hosted ObjectOS is a +**single-environment** runtime: one process, one environment, one app. +Holding many environments, and publishing an artifact for each, is what a +control plane does. See +[Environment Variables](/docs/reference/environment-variables). ### Field @@ -108,9 +111,10 @@ hooks are first-class code; flows are metadata. ### Kernel The microkernel inside ObjectOS that loads plugins, holds the DI -container, dispatches events, and serves a single Environment's -metadata. One process can hold many cached kernels (one per -Environment) in an LRU. +container, dispatches events, and serves the deployment's metadata. One +process builds one kernel, during startup, and does not report +[ready](/docs/deploy/docker) until it is built — so nothing per request +decides which metadata to serve. ### Manifest @@ -172,8 +176,9 @@ A framework package that extends the runtime with a capability — ### Project -Old name for **Environment**. Still used in v4.x CLI/env (aliased). -Removed in v5.0. +Old name for **Environment**. It survives in inherited configuration and +in framework-internal identifiers; ObjectOS documentation says +*Environment*. ### Record Share @@ -208,9 +213,12 @@ code. ### Tenant -A logical isolation boundary in multi-tenant deployments. One tenant -typically maps to one Environment. Cookies and sessions are scoped per -hostname; data is scoped per Environment. +An isolation boundary between the organizations sharing one deployment. +A walled tenancy posture puts the wall up and is a licensed capability. +Those organizations still share the deployment's app, its database and its +metadata, so the wall separates their data and memberships rather than +their schema. See [Multi-organization +deployments](/docs/reference/environment-variables#multi-organization-deployments). ### Trigger diff --git a/content/docs/why.mdx b/content/docs/why.mdx index 4a1a138..52a9c1d 100644 --- a/content/docs/why.mdx +++ b/content/docs/why.mdx @@ -42,7 +42,6 @@ Common scenarios where it's a fit: | Building a compliance / risk / vendor management tool for a regulated business | Audit log, RBAC, field security, row-level isolation are first-class — and every AI-driven change is itself an audit entry | | Standing up an internal admin for a SaaS product | One Node process, slots in next to your existing services | | Air-gapped or on-prem deployment for an enterprise customer | First-class deployment target, no internet egress required (BYO local model) | -| Multi-tenant internal portal (one runtime, many small apps) | Per-project kernel + LRU cache designed for this | | You want your users to "vibe-code" their own extensions safely | The AI Builder + HITL approval queue + audit log are the whole point | ## Don't use ObjectOS if you …