# Documentation

- [Documentation](/): Open source infrastructure for AI-native apps. Build with Wacht — the platform, the SDKs, the API reference.
- Start
  - [Start here](/start): The mental model and your first working app.
  - [Anatomy of a Wacht app](/start/anatomy): The nouns: actors, projects, threads, board items, assignments, workspaces — and how they fit together.
  - [Mental model](/start/mental-model): How to think about a Wacht app while you're designing it.
  - [Your first build](/start/your-first-build): Zero to a working AI-native app — deployment, agent, frontend wiring, your first task, surfaced result.
  - [Common patterns](/start/patterns): The shapes most Wacht apps fall into.
- Product
  - [Platform Overview](/product): A practical map of Wacht surfaces and where each docs section fits in a real implementation.
  - [Architecture](/product/architecture): How Wacht presents one user and organization model across identity, B2B, machine auth, webhooks, notifications, and an agent runtime.
  - [Deployments](/product/deployments): The isolation and configuration boundary for one of your products — what it owns, how staging and production differ, and how SDKs target one.
  - [Authentication](/product/authentication): How Wacht authenticates end users — sign-in factors, sessions, the frontend-backend trust boundary, and server-side verification.
  - [B2B Access Model](/product/b2b): How organizations, workspaces, memberships, roles, invitations, and domain auto-join compose into Wacht's tenancy model.
  - [API Authentication](/product/api-auth): Machine and customer-facing credentials in Wacht — API auth apps, keys, scopes, rate-limit schemes, and gateway authorization.
  - [Webhooks](/product/webhooks): Outbound event delivery in Wacht — webhook apps, endpoints, signed payloads, at-least-once delivery, retries, and replay.
- SDKs
  - [SDK Overview](/sdks): Choose the correct Wacht SDK path for your stack, then follow a concrete implementation track.
  - React
    - [React (Router-Agnostic)](/sdks/react): Use @wacht/jsx directly for plain React or custom routing stacks, with explicit navigation and backend enforcement patterns.
  - React Router
    - [React Router SDK](/sdks/react-router): Use Wacht in React Router applications for browser auth flows and request-time protection.
    - [Quick Start](/sdks/react-router/quickstart): Install the package, set your keys, mount the provider, and protect loaders with Wacht.
    - [Integration model](/sdks/react-router/integration-model): Understand how the React Router SDK loads deployment settings, uses hosted pages, and fits into embedded auth flows.
    - [Authentication](/sdks/react-router/authentication): Understand how Wacht models sessions, sign-ins, memberships, sign-out, and session tokens in React Router apps.
    - [Client-side Auth](/sdks/react-router/client-side-auth): Use the React Router client-side helpers for hosted auth pages, signed-in UI, account management, and custom auth flows.
    - [Server Auth](/sdks/react-router/server-auth): Authenticate React Router requests, forward the returned headers, and use the privileged server client when you need backend access.
    - [Control](/sdks/react-router/components/bootstrapping): Mount the provider once and wait for the deployment to load before rendering the rest of the app.
    - [Auth UI](/sdks/react-router/components/auth-ui): Embed sign-in, sign-up, verification, and invite flows inside a React Router app.
    - [Account](/sdks/react-router/components/account-controls): Use the shared account controls for post-login UI and session management.
    - [Notifications](/sdks/react-router/components/notifications): Render unread indicators, popovers, and full notification panels in React Router.
    - [Core state](/sdks/react-router/hooks/core-state): Read deployment, client, session, user, and navigation state from the shared hook layer.
    - [Auth flows](/sdks/react-router/hooks/auth-flows): Drive sign-in, sign-up, recovery, invitation, and verification flows from code.
    - [Organizations](/sdks/react-router/hooks/organizations-workspaces): Work with active organizations, workspaces, and membership data.
    - [Notifications](/sdks/react-router/hooks/notifications): Read notification data and build custom inbox surfaces.
    - [Integrations](/sdks/react-router/hooks/integrations): Use the agent, webhook, and API auth hooks that sit on top of the shared client layer.
  - Next.js
    - [Next.js](/sdks/nextjs): Add Wacht to a Next.js app with one provider on the client and request-aware auth helpers on the server.
    - [Quick Start](/sdks/nextjs/quickstart): Install the Next.js package, set your Wacht keys, add middleware, wrap your app with the provider, and sign in with the hosted auth pages.
    - [Integration model](/sdks/nextjs/integration-model): Understand how the Next.js SDK loads deployment settings, routes users through hosted pages, and lets you override UI behavior where needed.
    - [Authentication](/sdks/nextjs/client-side): Understand how Wacht models sessions, sign-ins, memberships, sign-out, and session tokens.
    - [Client-side Auth](/sdks/nextjs/client-side-auth): Use the Next.js client-side helpers for hosted auth pages, signed-in UI, account management, and custom auth flows.
    - [Middleware](/sdks/nextjs/middleware): Protect routes, normalize request auth state, and understand how Wacht turns session cookies or bearer tokens into a request-level auth object.
    - [Server-side Auth](/sdks/nextjs/server-side): Read auth state in route handlers and server components, understand token types and permission checks, and use the privileged Wacht server client.
    - [Control](/sdks/nextjs/components/bootstrapping): Mount the provider once and wait for the deployment to load before rendering the rest of the app.
    - [Auth UI](/sdks/nextjs/components/auth-ui): Embed sign-in, sign-up, verification, and invite flows inside a Next.js app.
    - [Account](/sdks/nextjs/components/account-controls): Use the shared account controls for post-login UI and session management.
    - [Notifications](/sdks/nextjs/components/notifications): Render unread indicators, popovers, and full notification panels in Next.js.
    - [Core state](/sdks/nextjs/hooks/core-state): Read deployment, client, session, user, and navigation state from the shared hook layer.
    - [Auth flows](/sdks/nextjs/hooks/auth-flows): Drive sign-in, sign-up, recovery, invitation, and verification flows from code.
    - [Organizations](/sdks/nextjs/hooks/organizations-workspaces): Work with active organizations, workspaces, and membership data.
    - [Notifications](/sdks/nextjs/hooks/notifications): Read notification data and build custom inbox surfaces.
    - [Integrations](/sdks/nextjs/hooks/integrations): Use the agent, webhook, and API auth hooks that sit on top of the shared client layer.
  - TanStack Router
    - [TanStack Router SDK](/sdks/tanstack-router): Use Wacht in TanStack Router apps for browser auth and request-time route protection.
    - [Quick Start](/sdks/tanstack-router/quickstart): Install the package, set your keys, mount the provider, and protect requests with Wacht.
    - [Integration model](/sdks/tanstack-router/integration-model): Understand how the TanStack Router SDK loads deployment settings, uses hosted pages, and fits into embedded auth flows.
    - [Authentication](/sdks/tanstack-router/authentication): Understand how Wacht models sessions, sign-ins, memberships, sign-out, and session tokens in TanStack Router apps.
    - [Client-side Auth](/sdks/tanstack-router/client-side-auth): Use the TanStack Router client-side helpers for hosted auth pages, signed-in UI, account management, and custom auth flows.
    - [Server Auth](/sdks/tanstack-router/server-auth): Authenticate TanStack Router requests, forward the returned headers, and use the privileged server client when you need backend access.
    - [Control](/sdks/tanstack-router/components/bootstrapping): Mount the provider once and wait for the deployment to load before rendering the rest of the app.
    - [Auth UI](/sdks/tanstack-router/components/auth-ui): Embed sign-in, sign-up, verification, and invite flows inside a TanStack Router app.
    - [Account](/sdks/tanstack-router/components/account-controls): Use the shared account controls for post-login UI and session management.
    - [Notifications](/sdks/tanstack-router/components/notifications): Render unread indicators, popovers, and full notification panels in TanStack Router.
    - [Core state](/sdks/tanstack-router/hooks/core-state): Read deployment, client, session, user, and navigation state from the shared hook layer.
    - [Auth flows](/sdks/tanstack-router/hooks/auth-flows): Drive sign-in, sign-up, recovery, invitation, and verification flows from code.
    - [Organizations](/sdks/tanstack-router/hooks/organizations-workspaces): Work with active organizations, workspaces, and membership data.
    - [Notifications](/sdks/tanstack-router/hooks/notifications): Read notification data and build custom inbox surfaces.
    - [Integrations](/sdks/tanstack-router/hooks/integrations): Use the agent, webhook, and API auth hooks that sit on top of the shared client layer.
  - Backend JS
    - [Backend JS SDK](/sdks/node): Universal JavaScript and TypeScript backend access to Wacht APIs, auth helpers, and gateway checks.
    - [Runtime Environments](/sdks/node/runtime-environments): Use @wacht/backend across Node, Deno, Bun, serverless, and worker-style runtimes.
    - [Runtime Playbook](/sdks/node/framework-interop): Production implementation playbook for runtime-specific and framework-specific backend integrations.
    - Runtime Guides
      - Node.js
        - [Node.js Overview](/sdks/node/runtimes/nodejs): Use @wacht/backend in long-running Node.js services, jobs, and internal APIs.
        - [Express](/sdks/node/runtimes/nodejs/express-integration): End-to-end Express integration with @wacht/backend server auth, guards, and typed backend API access.
        - [Fastify](/sdks/node/runtimes/nodejs/fastify-integration): End-to-end Fastify integration with @wacht/backend auth guards and typed backend operations.
        - [NestJS](/sdks/node/runtimes/nodejs/nest-integration): End-to-end NestJS integration for @wacht/backend with guards, decorators, and typed backend API usage.
        - [Koa](/sdks/node/runtimes/nodejs/koa-integration): End-to-end Koa integration with @wacht/backend middleware guards and typed backend calls.
        - [Hapi](/sdks/node/runtimes/nodejs/hapi-integration): Integrate @wacht/backend in Hapi with route pre-handlers and permission guards.
        - [Restify](/sdks/node/runtimes/nodejs/restify-integration): Integrate @wacht/backend with Restify middleware pipelines and protected admin routes.
      - Bun
        - [Bun Overview](/sdks/node/runtimes/bun): Run @wacht/backend in Bun servers and background jobs.
        - [Bun HTTP Handlers](/sdks/node/runtimes/bun/http-handlers): Protect Bun Request handlers and call backend APIs safely.
        - [Bun Framework Patterns](/sdks/node/runtimes/bun/framework-patterns): End-to-end Bun patterns for Elysia and Hono with JWT and API key/OAuth protected auth.
      - Deno
        - [Deno Overview](/sdks/node/runtimes/deno): Run @wacht/backend in Deno services with typed backend API access and explicit auth flows.
        - [Deno Framework Patterns](/sdks/node/runtimes/deno/framework-patterns): End-to-end patterns for Oak, Fresh, and Hono on Deno with JWT and API key/OAuth protected auth.
      - Hono
        - [Hono Overview](/sdks/node/runtimes/hono): Build backend APIs with Hono and @wacht/backend across Node and edge runtimes.
        - [Middleware and Auth](/sdks/node/runtimes/hono/middleware-auth): Implement reusable Hono auth middleware with permission checks.
      - Cloudflare Workers
        - [Cloudflare Workers Overview](/sdks/node/runtimes/cloudflare-workers): End-to-end Cloudflare Worker integration for @wacht/backend with bindings and protected routes.
        - [JWT and API Key/OAuth Protected Auth](/sdks/node/runtimes/cloudflare-workers/auth-and-gateway): Implement session-token auth and API key/OAuth protected authorization checks in Cloudflare Workers.
        - [Cloudflare Workers Framework Patterns](/sdks/node/runtimes/cloudflare-workers/framework-patterns): Use Hono or itty-router on Workers with JWT and API key/OAuth protected auth.
      - Netlify Functions
        - [Netlify Functions Overview](/sdks/node/runtimes/netlify-functions): Build protected Netlify Function endpoints with @wacht/backend.
        - [Auth and Header Bridging](/sdks/node/runtimes/netlify-functions/auth-and-headers): Handle auth headers and guard checks in Netlify handlers and helper layers.
        - [Netlify Framework Patterns](/sdks/node/runtimes/netlify-functions/framework-patterns): Patterns for Netlify Functions, Edge Functions, and framework route handlers using @wacht/backend.
      - Serverless Workers
        - [Serverless Workers Overview](/sdks/node/runtimes/serverless-workers): Apply the backend SDK in request-isolated serverless worker environments.
        - [Production Patterns](/sdks/node/runtimes/serverless-workers/production-patterns): Reliability and security patterns for serverless worker deployments.
        - [Serverless Platform Patterns](/sdks/node/runtimes/serverless-workers/platform-patterns): Platform-ready auth and backend SDK patterns for Lambda-style and edge-worker runtimes.
    - [Server Auth](/sdks/node/server-auth): Verify Wacht session tokens and enforce permissions in backend JavaScript runtimes.
  - Rust
    - [Getting Started](/sdks/rust/getting-started): Install the wacht crate, initialize a client, and make your first backend call.
    - Frameworks
      - [Framework Guides](/sdks/rust/frameworks): Framework-specific integration guidance for the Rust SDK.
      - Axum
        - [Axum](/sdks/rust/frameworks/axum): End-to-end authentication and authorization patterns for Rust services using Axum and wacht.
        - [Auth Layer Setup](/sdks/rust/frameworks/axum/auth-layer-setup): Configure and apply AuthLayer in Axum route trees.
        - [Extractors and Permissions](/sdks/rust/frameworks/axum/extractors-and-permissions): Use typed Axum extractors for authenticated and permission-gated handlers.
        - [Gateway Authorization](/sdks/rust/frameworks/axum/gateway-authorization): Check API key and OAuth access-token authorization in Axum handlers.
    - [User Management](/sdks/rust/user-management): Admin operations on a user's sessions, passkeys, MFA, and memberships from the Rust SDK.
    - [Organizations and Workspaces](/sdks/rust/organizations-workspaces): Scoped B2B resource operations in the Rust SDK.
    - [API Auth and OAuth](/sdks/rust/api-auth-oauth): Backend-aligned API auth and OAuth management methods in Rust SDK.
    - [Webhooks](/sdks/rust/webhooks): Manage webhook apps, event catalogs, endpoints, deliveries, replay, and analytics from the Rust SDK.
    - [AI Runtime and Configuration](/sdks/rust/ai-runtime): Manage agents, tools, knowledge bases, MCP servers, projects, and threads from the Rust SDK.
    - [Contract Validation](/sdks/rust/contract-validation): Backend-driven validation status for Rust SDK route/method parity.
- Guides
  - [Guides](/guides): Task-focused guides for building on Wacht — the agent runtime, platform surfaces, end-to-end integration, and the tooling around them.
  - [Wacht Bench](/guides/wacht-bench): AI-assisted development for Wacht. Install skills, wire Docs MCP, scaffold starters, and drive the Wacht Machine API from your terminal.
  - [Docs MCP](/guides/docs-mcp): Connect AI coding tools to the Wacht documentation through the Wacht Docs MCP server.
  - [Wacht Skills](/guides/bench-skills): Understand the Wacht skills package and how each skill accelerates Wacht development.
  - Integration Playbooks
    - [React + backend auth lifecycle](/guides/integration-playbooks/fullstack-auth-lifecycle-react-rust): A React frontend signs a user in, mints a session token, and calls a backend that verifies it. Node and Rust both shown, end to end.
    - [B2B org/workspace lifecycle](/guides/integration-playbooks/b2b-org-workspace-lifecycle): The end-to-end path from a fresh sign-in to a scoped, multi-tenant request — onboarding into organizations, selecting workspaces, and enforcing scope on the backend.
    - [Unsupported stacks](/guides/integration-playbooks/unsupported-stacks): Integrate Wacht when there's no SDK for your stack — a custom React router via @wacht/jsx, or any other frontend by calling the Frontend API directly.
  - Agents
    - [Agents](/guides/agents): Build, schedule, and share Wacht agents.
    - [Multi-agent orchestration](/guides/agents/multi-agent): Route work across specialist agents with a coordinator that decides which lane runs next.
    - [Model overrides](/guides/agents/model-overrides): Override the strong or weak model on a single agent without touching deployment defaults.
    - [Execution hooks](/guides/agents/hooks): Run configured tool steps when an agent execution starts or ends.
    - [Tool approval policy](/guides/agents/approval-policy): Per-agent control over which tool calls run unattended, pause for review, or are denied outright.
    - [CodeRunner tools](/guides/agents/code-runner): Create Python tools that an agent runs inside a Wacht sandbox.
    - [Agent skill bundles](/guides/agents/skill-bundles): Upload, inspect, and manage per-agent skill bundles from the backend SDKs.
    - [Scheduling](/guides/agents/scheduling): Run an agent task once at a set time or on a recurring interval, with no human kicking it off.
    - [Composio integrations](/guides/agents/composio): Give an agent access to third-party SaaS apps through Composio.
    - [Agent sessions](/guides/agents/sessions): Share an agent chat URL with a teammate, customer, or background service.
  - Tasks
    - [Tasks](/guides/tasks): How work flows through a Wacht app — created, executed, surfaced.
    - [Workspace and artifacts](/guides/tasks/workspace-and-artifacts): Every task gets a /task/ filesystem. How agents use it, how to surface files to your UI.
    - [Deliverables and the journal](/guides/tasks/deliverables): Every task completion produces a structured handoff — in the deliverables array, on the assignment row, and in /task/JOURNAL.md.
    - [File uploads](/guides/tasks/file-uploads): Get user files into a task's workspace at three points — task creation, task update, and comments.
    - [Realtime UI](/guides/tasks/realtime-ui): Surface in-flight task state, deliverables, pending questions, and approvals in your UI as they happen.
  - API Auth
    - [API Auth](/guides/api-auth): Customer-managed API keys — lifecycle, audit, analytics, vanity or custom UX.
    - [Custom Hook Flow Implementation](/guides/api-auth/custom-hook-flow-implementation): Build a production-ready API key management UX with Wacht hooks, backend policy checks, and observability.
    - [Building API Auth Observability Screens](/guides/api-auth/audit-observability-screens): Build operator screens for API key traffic from the audit log, analytics, and timeseries hooks.
    - [Vanity Pages Implementation](/guides/api-auth/vanity-pages-implementation): Embed hosted API key management pages with secure ticket issuance, tenant isolation, and operational guardrails.
  - Webhook Apps
    - [Webhook Apps](/guides/webhook-apps): Customer-managed event delivery — endpoints, secrets, retries, replay.
    - [Vanity Pages Implementation](/guides/webhook-apps/vanity-pages-implementation): Embed hosted webhook management in your app with secure ticket issuance and route mapping.
    - [Custom Hook Flow Implementation](/guides/webhook-apps/custom-hook-flow-implementation): Build a full webhook management experience in your product using Wacht hooks.
    - [Deliveries, Replay, and Observability](/guides/webhook-apps/deliveries-replay-and-observability): Operate webhook delivery — filtered triage, bounded replay, and success-rate trends from the delivery hooks.
  - OAuth Apps
    - [OAuth Apps for SaaS](/guides/oauth-apps): End-to-end guide for creating OAuth apps, managing clients, handling consent, and validating tokens with Wacht.
    - [Create OAuth Apps and Clients](/guides/oauth-apps/create-oauth-app-and-clients): Set up OAuth apps, scopes, and clients in a way that is safe for production SaaS deployments.
    - [Implement OAuth Consent Flow](/guides/oauth-apps/implement-consent-flow): Originate OAuth flows, use hosted consent, and handle callback/token exchange correctly.
    - [Verify OAuth Access Tokens](/guides/oauth-apps/access-token-verification): Two ways to verify Wacht-issued access tokens in your resource server: gateway introspection (opaque tokens) and stateless JWT verification (zero round-trips).
    - [Verify Tokens and Operate OAuth Clients](/guides/oauth-apps/verify-access-tokens-and-operate-clients): Verify OAuth access tokens in your resource server, rotate client secrets, and revoke grants safely.
    - [Use Wacht as an OpenID Connect Provider](/guides/oauth-apps/use-as-openid-connect-provider): Authenticate users through Wacht using OpenID Connect — discovery, id_tokens, UserInfo, RP-initiated logout.
    - [Sign In from Desktop and CLI Apps](/guides/oauth-apps/native-apps): Use the OAuth 2.0 loopback flow (RFC 8252) to authenticate users from a Tauri, Electron, or CLI app against your Wacht deployment.
  - Notifications
    - [Notification System Architecture](/guides/notifications): How Wacht notifications are scoped, severity-tagged, and moved through the read/archive/expiry lifecycle, and where you create them.
    - [Backend Sending Patterns](/guides/notifications/backend-sending-patterns): Publish notifications from backend domain events with reliable delivery, stable metadata, and actionable CTAs.
    - [Frontend Inbox with Hooks](/guides/notifications/frontend-inbox-with-hooks): Build a production inbox with pagination, scoped filters, mutation actions, and resilient refresh behavior.
    - [Realtime Stream Handling](/guides/notifications/realtime-stream-handling): Use realtime notification streaming safely with reconnect handling and API reconciliation.
    - [Designing Actionable Notification UX](/guides/notifications/actionable-notification-ux): Write Wacht notifications that name the event, carry one CTA that routes to the fix, and expire when they stop mattering.
  - Deployment Events
    - [Keep your backend in sync](/guides/deployment-events): Webhook envelope contract and representative payload examples for deployment events.
- API Reference
  - [API Reference](/reference): HTTP API reference for the Wacht Frontend and Platform APIs.
  - [Backend API](/reference/backend-api): Server-to-server management API for administering users, organizations, auth configuration, and deployment settings.
  - [Frontend API](/reference/frontend-api): Runtime HTTP API used by Wacht SDKs and browser clients for session management, auth flows, and user operations.
  - [Agent runtime objects](/reference/agent-objects): Object hierarchy and API verbs for driving the Wacht agent runtime from code.