diff --git a/.github/workflows/preview.yaml b/.github/workflows/preview.yaml
index a5a5575..b77b356 100644
--- a/.github/workflows/preview.yaml
+++ b/.github/workflows/preview.yaml
@@ -19,19 +19,20 @@ jobs:
node-version: 20.x
- name: Install dependencies
- run: rm -fr node_modules && rm package-lock.json && npm install
+ run: npm ci
- name: Build the site
run: npm run build:worker
- name: Create website preview
+ id: deploy
uses: cloudflare/wrangler-action@v3.14.1
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
- command: versions upload
+ command: deploy --minify
- name: Print website URL
env:
DEPLOYMENT_URL: ${{ steps.deploy.outputs.deployment-url }}
- run: echo $DEPLOYMENT_URL
\ No newline at end of file
+ run: echo $DEPLOYMENT_URL
diff --git a/public/sitemap.xml b/public/sitemap.xml
index d75e389..b444ff2 100644
--- a/public/sitemap.xml
+++ b/public/sitemap.xml
@@ -2,826 +2,840 @@
https://kagent.dev/agents
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/blog
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/community
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/concepts/agent-harness
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/concepts/agent-memory
- 2026-06-11
+ 2026-06-12
+ weekly
+ 0.8
+
+
+
+ https://kagent.dev/docs/kagent/concepts/agent-substrate
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/concepts/agents
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/concepts/architecture
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/concepts
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/concepts/tools
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples/a2a-agents
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples/a2a-byo
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples/agent-harness
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples/agent-sandbox
- 2026-06-11
+ 2026-06-12
+ weekly
+ 0.8
+
+
+
+ https://kagent.dev/docs/kagent/examples/agent-substrate
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples/agents-mcp
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples/crewai-byo
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples/discord-a2a
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples/documentation
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples/human-in-the-loop
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples/langchain-byo
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples/skills
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples/slack-a2a
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/examples/telegram-bot
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/getting-started/first-agent
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/getting-started/first-mcp-tool
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/getting-started/local-development
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/getting-started
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/getting-started/quickstart
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/getting-started/system-prompts
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/introduction/features
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/introduction/installation
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/introduction
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/introduction/what-is-kagent
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/observability/audit-prompts
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/observability/launch-ui
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/observability
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/observability/tracing
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/operations/debug
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/operations/operational-considerations
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/operations
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/operations/uninstall
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/operations/upgrade
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/api-ref
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-add-mcp
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-bug-report
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-build
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-completion
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-dashboard
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-deploy
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-get
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-help
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-init
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-install
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-invoke
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-mcp
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-run
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-uninstall
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli/kagent-version
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/cli
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/faq
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/helm
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/release-notes
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/resources/tools-ecosystem
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/supported-providers/amazon-bedrock
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/supported-providers/anthropic
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/supported-providers/azure-openai
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/supported-providers/byo-openai
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/supported-providers/gemini
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/supported-providers/google-vertexai
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/supported-providers/ollama
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/supported-providers/openai
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/supported-providers
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/supported-providers/sap-ai-core
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kagent/supported-providers/xai
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/deploy/install-controller
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/deploy
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/deploy/server
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/develop/fastmcp-python
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/develop/mcp-go
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/develop
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/introduction
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/quickstart
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/reference/api-ref
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/reference/kmcp-add-tool
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/reference/kmcp-build
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/reference/kmcp-completion
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/reference/kmcp-deploy
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/reference/kmcp-help
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/reference/kmcp-init
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/reference/kmcp-install
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/reference/kmcp-run
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/reference/kmcp-secrets
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/reference
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs/kmcp/secrets
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/docs
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/enterprise
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/page.tsx
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/tools
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/agents/argo-rollouts-conversion-agent
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/agents/cilium-crd-agent
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/agents/helm-agent
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/agents/istio-agent
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/agents/k8s-agent
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/agents/kgateway-agent
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/agents/observability-agent
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/agents/promql-agent
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/tools/istio
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/tools/kubernetes
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/tools/prometheus
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/tools/documentation
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/tools/helm
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/tools/argo
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/tools/grafana
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/tools/other
- 2026-06-11
+ 2026-06-12
weekly
0.8
https://kagent.dev/tools/cilium
- 2026-06-11
+ 2026-06-12
weekly
0.8
diff --git a/src/app/docs/_constants.ts b/src/app/docs/_constants.ts
index 469df6f..f523d45 100644
--- a/src/app/docs/_constants.ts
+++ b/src/app/docs/_constants.ts
@@ -10,6 +10,7 @@ export const VERSIONS = {
// External dependencies
agentSandbox: "0.3.10",
+ agentSubstrate: "0.0.6",
loki: "6.24.0",
tempo: "1.16.0",
jaeger: "4.4.7",
diff --git a/src/app/docs/kagent/concepts/agent-substrate/page.mdx b/src/app/docs/kagent/concepts/agent-substrate/page.mdx
index 03f8283..e9531ef 100644
--- a/src/app/docs/kagent/concepts/agent-substrate/page.mdx
+++ b/src/app/docs/kagent/concepts/agent-substrate/page.mdx
@@ -78,4 +78,5 @@ See the [API reference](/docs/kagent/resources/api-ref) for the full `AgentHarne
## Learn more
-For a deeper dive into the runtime internals, see the [Agent Substrate documentation](https://learn.agentsubstrate.dev/).
+- [Run a declarative agent on Agent Substrate](/docs/kagent/examples/agent-substrate) — end-to-end walkthrough on a kind cluster.
+- For a deeper dive into the runtime internals, see the [Agent Substrate documentation](https://learn.agentsubstrate.dev/).
diff --git a/src/app/docs/kagent/examples/agent-substrate/page.mdx b/src/app/docs/kagent/examples/agent-substrate/page.mdx
new file mode 100644
index 0000000..4cdd7bc
--- /dev/null
+++ b/src/app/docs/kagent/examples/agent-substrate/page.mdx
@@ -0,0 +1,226 @@
+---
+title: "Agent Substrate"
+pageOrder: 9
+description: "Run a declarative agent on Agent Substrate — a Kubernetes-native runtime that snapshots idle agents and rehydrates them inside gVisor sandboxes."
+---
+
+import { VERSIONS } from "../../../_constants";
+
+export const metadata = {
+ title: "Agent Substrate",
+ description: "Run a declarative agent on Agent Substrate — a Kubernetes-native runtime that snapshots idle agents and rehydrates them inside gVisor sandboxes.",
+ author: "kagent.dev"
+};
+
+# Agent Substrate
+
+This example walks from an empty machine to a declarative agent running inside a gVisor actor on [Agent Substrate](/docs/kagent/concepts/agent-substrate). Everything pulls from published OCI charts — no source builds, no repo clones.
+
+By the end you'll have:
+
+- A kind cluster running Agent Substrate {VERSIONS.agentSubstrate} in `ate-system`.
+- kagent 0.9.7 or later installed with the substrate integration enabled. **kagent 0.9.7 is the minimum version** — earlier releases do not include the controller wiring that lets a `SandboxAgent` target substrate.
+- A `SandboxAgent` running on substrate, reachable from the kagent UI.
+
+For background on what substrate is and how it differs from a per-pod agent runtime, see the [Agent Substrate concept page](/docs/kagent/concepts/agent-substrate). This guide does not cover the `AgentHarness` path on substrate.
+
+## Before you begin
+
+You will need:
+
+- `kind`, `kubectl`, and `helm` on your `PATH`.
+- A running Docker daemon (Docker Desktop or equivalent).
+- An OpenAI API key exported in your shell.
+
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+## Step 1: Create a kind cluster
+
+```bash
+kind create cluster --name kagent-substrate
+```
+
+The substrate {VERSIONS.agentSubstrate} chart defaults to JWT auth backed by Kubernetes ServiceAccount tokens, so a vanilla kind cluster works — no feature gates or custom kind config are required.
+
+## Step 2: Install Agent Substrate
+
+Install the CRDs first, then the substrate control plane and data plane.
+
+```bash
+helm upgrade --install substrate-crds \
+ oci://ghcr.io/kagent-dev/substrate/helm/substrate-crds \
+ --version {VERSIONS.agentSubstrate} \
+ --namespace ate-system --create-namespace --wait
+
+helm upgrade --install substrate \
+ oci://ghcr.io/kagent-dev/substrate/helm/substrate \
+ --version {VERSIONS.agentSubstrate} \
+ --namespace ate-system --wait --timeout 10m
+```
+
+Verify the substrate pods are running.
+
+```bash
+kubectl get pods -n ate-system
+```
+
+You should see `ate-api-server`, `ate-controller`, `atelet-*`, `atenet-router`, `valkey-cluster-{0..5}`, and `rustfs` all `Running`, plus a few `Completed` init jobs.
+
+## Step 3: Install kagent with substrate enabled
+
+> Pin the chart to `0.9.7` or later. The `controller.substrate.*` and `substrateWorkerPool.*` values used below were introduced in 0.9.7; against an older chart they will be silently ignored and the controller will start without the substrate integration.
+
+Confirm the OpenAI key is set in this shell before running helm. If it's empty, the install will run silently with no `kagent-openai` Secret and the default agent pods will land in `CreateContainerConfigError`.
+
+```bash
+[[ -n "${OPENAI_API_KEY:-}" ]] && echo "key is set (len=${#OPENAI_API_KEY})" || echo "OPENAI_API_KEY is empty — export it first"
+```
+
+> Don't combine the export and the helm command on one line — `OPENAI_API_KEY="$(cat ...)" helm ... --set providers.openAI.apiKey="${OPENAI_API_KEY}"` evaluates `${OPENAI_API_KEY}` before the inline assignment runs and passes an empty string. Either `export` on its own line first, or splice the value directly with `--set providers.openAI.apiKey="$(cat ~/path/to/key)"`.
+
+Install the CRDs, then kagent with the substrate flags.
+
+```bash
+helm upgrade --install kagent-crds \
+ oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
+ --version 0.9.7 \
+ --namespace kagent --create-namespace --wait
+
+helm upgrade --install kagent \
+ oci://ghcr.io/kagent-dev/kagent/helm/kagent \
+ --version 0.9.7 \
+ --namespace kagent --timeout 10m --wait \
+ --set providers.openAI.apiKey="${OPENAI_API_KEY}" \
+ --set providers.default=openAI \
+ --set controller.substrate.enabled=true \
+ --set controller.substrate.ateApiEndpoint=dns:///api.ate-system.svc:443 \
+ --set controller.substrate.ateApiInsecure=true \
+ --set substrateWorkerPool.create=true \
+ --set substrateWorkerPool.replicas=1 \
+ --set substrateWorkerPool.ateomImage=ghcr.io/kagent-dev/substrate/ateom-gvisor:v{VERSIONS.agentSubstrate}
+```
+
+The `controller.substrate.*` and `substrateWorkerPool.*` flags are what turn on the substrate integration. The rest is a standard kagent install.
+
+If helm hits its `--timeout 10m` while waiting on the cold-start pod startup race (the controller restarts a couple of times waiting on postgres), wait for the controller manually and continue.
+
+```bash
+kubectl wait deploy/kagent-controller -n kagent --for=condition=Available --timeout=10m
+```
+
+Sanity-check that the key landed and the default agents are healthy.
+
+```bash
+kubectl get secret kagent-openai -n kagent # should exist with 1 data entry
+kubectl get pods -n kagent | grep -v Running # only header + Completed jobs expected
+```
+
+If you see `CreateContainerConfigError` on the default agent pods, the secret didn't get created — re-run the kagent helm command with `--reuse-values --set providers.openAI.apiKey="$(cat ~/path/to/key)"` to patch it in. The deployments will roll to new pods automatically.
+
+### Tuning the WorkerPool size
+
+`substrateWorkerPool.replicas=1` is the chart default. One worker is enough for a declarative-only walkthrough: session actors release their slot the moment they snapshot back to object storage, so a single worker can serve many sequential sessions. Bump it when:
+
+- You add a long-lived `AgentHarness`. The `ahr-<...>` actor pins a slot for the lifetime of the CR, so you need at least `1 + (number of harnesses)`.
+- You want simultaneous, overlapping declarative sessions.
+
+You can change the size three ways, depending on how permanent you want it.
+
+```bash
+# 1) Quick, ephemeral — scale the live CR. Reverts on the next helm upgrade.
+kubectl scale workerpool kagent-default -n kagent --replicas=3
+
+# 2) Stick it into the helm release — survives upgrades.
+helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
+ --version 0.9.7 --namespace kagent --reuse-values \
+ --set substrateWorkerPool.replicas=3
+
+# 3) Fresh install — change the value on the Step 3 install command above.
+```
+
+## Step 4: Open the kagent UI
+
+```bash
+kubectl port-forward -n kagent svc/kagent-ui 8001:8080
+```
+
+Open [http://localhost:8001](http://localhost:8001). Skip the first-run wizard if it appears.
+
+## Step 5: Create a declarative agent on substrate
+
+A `SandboxAgent` with `platform: substrate` and a `substrate.workerPoolRef` runs as a substrate actor instead of a plain Deployment. Pick one of the two paths below.
+
+### Option A: Via the UI
+
+1. **Create** → **Agent** → choose **Declarative** as the type.
+2. Set the basics:
+ - **Name**: `hello-substrate`
+ - **Namespace**: `kagent`
+ - **Model config**: `default-model-config`
+ - **Runtime**: `Go` (required — the Python ADK isn't supported on substrate today)
+ - **System message**:
+ ```
+ You are a friendly assistant living inside an Agent Substrate sandbox.
+ When asked who you are, say "I am hello-substrate, a Go ADK declarative
+ agent running inside a gVisor actor."
+ ```
+3. In the **Sandbox** / **Platform** section (the label depends on UI version), set **Platform** to **`substrate`** and select the worker pool `kagent-default`.
+4. Save.
+
+### Option B: Via kubectl
+
+```yaml
+kubectl apply -f - < *What are you, and where are you running? Answer in one sentence.*
+
+Expected reply:
+
+> *I am hello-substrate, a Go ADK declarative agent running inside a gVisor actor.*
+
+Behind the scenes, a per-session gVisor actor was restored from the golden snapshot, ran the LLM call, and snapshotted itself back to object storage. Open **View → Substrate** to see the actor in the inventory — between requests it will sit `Suspended`.
+
+## Cleanup
+
+```bash
+kind delete cluster --name kagent-substrate
+```
+
+## Next steps
+
+- [Agent Substrate concept page](/docs/kagent/concepts/agent-substrate) — runtime architecture and how snapshots, actors, and worker pools fit together.
+- [AgentHarness](/docs/kagent/examples/agent-harness) — provision long-running OpenClaw, NemoClaw, or Hermes sandboxes. Set `runtime: substrate` to run a harness on Agent Substrate too.
+- [Agent Sandbox](/docs/kagent/examples/agent-sandbox) — the upstream `kubernetes-sigs/agent-sandbox` backend for `SandboxAgent`, a separate path from substrate.
diff --git a/src/app/docs/kagent/examples/page.mdx b/src/app/docs/kagent/examples/page.mdx
index 3d7b93b..8d1760e 100644
--- a/src/app/docs/kagent/examples/page.mdx
+++ b/src/app/docs/kagent/examples/page.mdx
@@ -32,5 +32,6 @@ import QuickLink from '@/components/quick-link';
+
diff --git a/src/config/navigation.json b/src/config/navigation.json
index 179059b..43d2810 100644
--- a/src/config/navigation.json
+++ b/src/config/navigation.json
@@ -232,6 +232,11 @@
"title": "Agent Harness",
"href": "/docs/kagent/examples/agent-harness",
"description": "Provision OpenClaw, NemoClaw, and Hermes sandboxes with the AgentHarness API."
+ },
+ {
+ "title": "Agent Substrate",
+ "href": "/docs/kagent/examples/agent-substrate",
+ "description": "Run a declarative agent on Agent Substrate — a Kubernetes-native runtime that snapshots idle agents and rehydrates them inside gVisor sandboxes."
}
]
},