You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 61ea6c6
Browse filesBrowse the repository at this point in the historyBrowse files
site: publish per-page Markdown and fix llms.txt and llms-full.txt (#3435)
`ate.dev/llms.txt` linked to full Docsy HTML pages instead of standalone
Markdown files, omitted page status markers and schema links, and still
used the old `ateom` component name. Meanwhile, `raw-markdown.html`
wrote into an HTML template buffer and expanded `include-file` with
`replaceRE`, which HTML-escaped code blocks and blockquotes across
`ate.dev/llms-full.txt` and "Copy as Markdown" (`'`, `"`,
`>`), stripped `$VAR` shell references as regexp capture groups, left
relative links unrewritten, and kept decorative `<figure>` HTML blocks.
- Add the `MARKDOWN` output format for doc pages
(`site/layouts/docs/single.md`) so each page publishes a clean
`index.md` alongside `index.html` and exposes `<link rel="alternate"
type="text/markdown">` in `<head>`.
- Return a plain string from `raw-markdown.html`, expand `include-file`
with literal replacement, drop decorative diagram HTML, and rewrite
relative links to absolute URLs across `llms-full.txt`, per-page
`index.md`, and "Copy as Markdown".
- Update `index.llms.txt` to link to each page's `index.md` build,
include `[Status: ...]` labels from front matter, link the
`ateapi.proto`, `ate.dev/v1` CRD, and OpenTelemetry Weaver metric
schemas, and summarize the sandbox model and the split between
`ate.dev/v1` Kubernetes CRDs and the `ate-api-server` gRPC API.
- Replace leftover `ateom`, `ate-api`, and `herder` references in docs
with `ateworker`, `atenet-router`, and `ate-api-server`, and add
template tests in `hack/test-site-templates.sh`.
AI use: AI-assisted, I reviewed and tested it.
- [x] Tests pass
- [x] Docs updated
---------
Signed-off-by: Mofi Rahman <[email protected]>
Copy file name to clipboardExpand all lines: docs/concepts/architecture.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -331,9 +331,9 @@ manage actor lifecycles.
331
331
332
332
The node-level subsystem manages the physical execution of sandboxes and the movement of snapshots.
333
333
334
-
***atelet**: A lightweight supervisor running on each node as a DaemonSet. It acts as the "Herder," managing a pool of physical pods and communicating with the Control Plane.
334
+
***atelet**: A lightweight supervisor running on each node as a DaemonSet. It manages local worker pods and communicates with the Control Plane.
335
335
336
-
***ateworker**: A specialized sandbox-herder container image — one per sandbox class (`ateworker-gvisor`, `ateworker-microvm`) — that runs inside the physical worker pods. It provides a gRPC interface for `atelet` to trigger `RunWorkload`, `CheckpointWorkload`, and `RestoreWorkload` operations. This separation ensures that the physical pod lifecycle remains decoupled from the sandboxed agent process.
336
+
***ateworker**: The worker container image (`ateworker-gvisor` or `ateworker-microvm`, one per sandbox class) that runs inside each physical worker pod. It provides a gRPC interface for `atelet` to trigger `RunWorkload`, `CheckpointWorkload`, and `RestoreWorkload` operations. This separation ensures that the physical pod lifecycle remains decoupled from the sandboxed agent process.
337
337
338
338
***Lifecycle Management**: The `ateworker` process invokes the sandbox runtime to checkpoint or restore processes within the physical pod boundaries — `runsc` for gVisor, or the Kata + Cloud Hypervisor stack for microVMs. (Note: the gVisor backend currently requires a `runsc` version with the `--allow-connected-on-save` flag to work around a bug in networking resumption during checkpointing.)
339
339
@@ -343,7 +343,7 @@ The node-level subsystem manages the physical execution of sandboxes and the mov
343
343
344
344
### Sandbox Classes
345
345
346
-
A `WorkerPool` selects a **sandbox class** (`spec.sandboxClasses[].name`), and each class has a matching `ateworker`herder image. The sandbox binaries themselves are not baked into the worker image. They come at runtime from the cluster-scoped [`SandboxConfig`](../reference/api-guide.md#3-sandboxconfig-the-sandbox-itself) the `WorkerPool` resolves for its class (an explicit `configRef`, else the class default). Each snapshot records the sandbox runtime it was taken on, and a memory restore runs on a worker that still offers that runtime, so restores stay reproducible across runtime upgrades.
346
+
A `WorkerPool` selects a **sandbox class** (`spec.sandboxClasses[].name`), and each class has a matching `ateworker` image. The sandbox binaries themselves are not baked into the worker image. They come at runtime from the cluster-scoped [`SandboxConfig`](../reference/api-guide.md#3-sandboxconfig-the-sandbox-itself) the `WorkerPool` resolves for its class (an explicit `configRef`, else the class default). Each snapshot records the sandbox runtime it was taken on, and a memory restore runs on a worker that still offers that runtime, so restores stay reproducible across runtime upgrades.
347
347
348
348
***gVisor** (`ateworker-gvisor`, the default): Runs the workload under `runsc` for kernel-level sandboxing. Suspend and resume leverage gVisor's native checkpoint/restore of the sandboxed process tree. `DurableDir` volumes and each container's rootfs overlay are saved as separate filesystem checkpoint bundles (`fs/` and `rootfs/`). A `MEMORY` snapshot splits them out of the process checkpoint; `VOLUMES` and `ROOTFS` snapshots save only the bundles they need with `runsc fscheckpoint`, without memory, and restore them on a cold boot.
@@ -50,6 +50,6 @@ Substrate decouples the **Actor** (a stateful agent or workload instance) from t
50
50
</figcaption>
51
51
</figure>
52
52
53
-
***Core Platform Terms at a Glance:** Each actor lives in an `atespace` (`<atespace>/<actor>`), traffic enters via `atenet`, node supervision and snapshot streaming are handled by `atelet`, and sandbox execution inside each warm `Worker` is managed by `ateom` (internally prefixed `ate` across binaries and CRDs). See the **[Glossary](../reference/glossary.md)** for complete definitions.
53
+
***Core Platform Terms at a Glance:** Each actor lives in an `atespace` (`<atespace>/<actor>`), traffic enters via `atenet-router`, node supervision and snapshot streaming are handled by `atelet`, and sandbox execution inside each warm `Worker` is managed by `ateworker` (internally prefixed `ate` across binaries and CRDs). See the **[Glossary](../reference/glossary.md)** for complete definitions.
54
54
***Framework Agnostic:** Runs standard OCI containers inside zero-trust sandboxes—supporting ADK, LangChain, Hermes, OpenClaw, MCP servers, and stateful coding environments out of the box.
55
-
***Ready to try it?** Jump straight to **[Quickstart](quickstart.md)** to launch your first actor locally on Kind, follow the **[GKE Installation Guide](https://docs.cloud.google.com/kubernetes-engine/ai-ml/install-overview-substrate)** to deploy on Google Kubernetes Engine, or explore the **[Architecture](../concepts/architecture.md)**.
55
+
***Ready to try it?** Jump straight to **[Quickstart](quickstart.md)** to launch your first actor locally on [kind](https://kind.sigs.k8s.io/), follow the **[GKE Installation Guide](https://docs.cloud.google.com/kubernetes-engine/ai-ml/install-overview-substrate)** to deploy on Google Kubernetes Engine, or explore the **[Architecture](../concepts/architecture.md)**.
Copy file name to clipboardExpand all lines: docs/get-started/quickstart.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,25 +5,25 @@ weight: 2
5
5
aliases:
6
6
- "/docs/getting-started/"
7
7
description: >
8
-
Deploy Agent Substrate on a local Kind cluster and invoke your first stateful actor.
8
+
Deploy Agent Substrate on a local kind cluster and invoke your first stateful actor.
9
9
---
10
10
11
11
# Quickstart & Installation
12
12
13
-
Deploy the Agent Substrate control plane and the stateful **Counter** sample application on a local `kind` cluster.
13
+
Deploy the Agent Substrate control plane and the stateful **Counter** sample application on a local [kind](https://kind.sigs.k8s.io/) cluster.
14
14
15
15
> [!NOTE]
16
-
> **Prerequisites:** Ensure [Go](https://go.dev/doc/install), [`kubectl`](https://kubernetes.io/docs/tasks/tools/), and [Docker](https://www.docker.com/) are installed (`kind` is managed automatically via Go). A Linux host that will run more than about a thousand sandboxes also needs a larger kernel neighbor table (`net.ipv4.neigh.default.gc_thresh1/2/3` = 4096/16384/32768); `hack/create-kind-cluster.sh` warns when the host is at the default of 1024.
16
+
> **Prerequisites:** Ensure [Go](https://go.dev/doc/install), [`kubectl`](https://kubernetes.io/docs/tasks/tools/), and [Docker](https://www.docker.com/) are installed ([`kind`](https://kind.sigs.k8s.io/) is managed automatically via Go). A Linux host that will run more than about a thousand sandboxes also needs a larger kernel neighbor table (`net.ipv4.neigh.default.gc_thresh1/2/3` = 4096/16384/32768); `hack/create-kind-cluster.sh` warns when the host is at the default of 1024.
17
17
18
18
## 1. Deploy Agent Substrate & Create an Actor
19
19
20
20
Run the following commands from the repository root to provision a local `kind` cluster, install Agent Substrate, and create a `counter` actor:
21
21
22
22
```bash
23
-
# 1. Create a local Kind cluster and image registry (IPv4; IP_FAMILY=dual|ipv6 overrides)
23
+
# 1. Create a local kind cluster and image registry (IPv4; IP_FAMILY=dual|ipv6 overrides)
24
24
hack/create-kind-cluster.sh
25
25
26
-
# 2. Target the local Kind cluster in every shell that runs ate-setup
26
+
# 2. Target the local kind cluster in every shell that runs ate-setup
27
27
export ATE_INSTALL_KIND=true
28
28
29
29
# 3. Install Agent Substrate, PostgreSQL, and snapshot storage (rustfs)
@@ -66,7 +66,7 @@ data:
66
66
OTEL_METRIC_EXPORT_TIMEOUT: "10000"
67
67
OTEL_LOGS_EXPORTER: otlp
68
68
---
69
-
# ActorTemplate snapshotConfig rendered for Kind (local bucket)
69
+
# ActorTemplate snapshotConfig rendered for kind (local bucket)
Copy file name to clipboardExpand all lines: docs/reference/api-guide.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ card_icon: "fa-solid fa-code"
6
6
aliases:
7
7
- "/docs/guides/api-guide/"
8
8
description: >
9
-
Define WorkerPoolsand ActorTemplates, the workload blueprints of Agent Substrate.
9
+
Define WorkerPools, ActorTemplates, and SandboxConfigs, and call the Control Plane gRPC API.
10
10
---
11
11
12
12
# Substrate API Guide: WorkerPool & ActorTemplate
@@ -15,14 +15,14 @@ This guide explains how to configure Substrate resources to deploy high-density,
15
15
16
16
## 1. WorkerPool: The Physical Capacity
17
17
18
-
The `WorkerPool` defines the pool of physical "warm" compute capacity. It manages a fleet of standby pods (herders) that are ready to receive and execute actor states.
18
+
The `WorkerPool` defines the pool of physical "warm" compute capacity. It manages a fleet of standby worker pods that are ready to receive and execute actor states.
19
19
20
20
### Specification (`WorkerPoolSpec`)
21
21
22
22
| Field | Type | Description |
23
23
| :--- | :--- | :--- |
24
24
|`replicas`|`int32`|**Required.** Number of physical standby pods to maintain in the cluster. |
25
-
|`workerImage`|`string`|**Required.** The container image for the `ateworker`herder process (e.g. `ko://go.ate.dev/substrate/cmd/ateworker-gvisor`). |
25
+
|`workerImage`|`string`|**Required.** The container image for the `ateworker` process (e.g. `ko://go.ate.dev/substrate/cmd/ateworker-gvisor`). |
26
26
|`sandboxClasses`|`[]WorkerPoolSandboxClass`|**Required.** The sandbox runtime families the pool runs; exactly one entry today. Each entry has `name` (**required**, `gvisor` or `microvm`, immutable), which drives the worker pod shape (e.g. KVM device mounts, node placement), and `configRef.name` (optional), which names a cluster-scoped [`SandboxConfig`](#3-sandboxconfig-the-sandbox-itself) of the same class. Without `configRef`, the pool uses the class default (see [Class default](#class-default)). The controller records the result in `status.sandboxClasses`. The sandbox binaries an actor boots with come from the `SandboxConfig` the pool of its assigned worker resolved. |
27
27
|`template`|`WorkerPoolPodTemplate`|**Optional.** Metadata, scheduling, and resource settings for worker workloads. |
Copy file name to clipboardExpand all lines: hack/test-site-templates.sh
+14-2Lines changed: 14 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -118,11 +118,23 @@ lacks main "${F}/override/index.html" 'as-status-banner--deprecated'
118
118
lacks main "${F}/plain/index.html"'as-status-banner'
119
119
lacks main "${F}/index.html"'as-status-banner'
120
120
121
-
# Copy as Markdown and llms-full.txt carry the status line.
121
+
# Copy as Markdown, per-page index.md, and llms-full.txt carry unescaped
122
+
# Markdown, preserve shell variables, and rewrite relative links.
122
123
has main "${F}/experimental/index.html"'\*\*Status: Experimental\.\*\* This feature is experimental'
123
-
has main llms-full.txt '(>|>) \*\*Status: Deprecated\.\*\* Use the \[experimental page\]\(experimental\.md\) instead\.'
124
+
has main "${F}/deprecated/index.md"'> \*\*Status: Deprecated\.\*\* Use the \[experimental page\]\(https://example\.org/docs/fixtures/experimental/index\.md\) instead\.'
125
+
has main llms-full.txt '> \*\*Status: Deprecated\.\*\* Use the \[experimental page\]\(https://example\.org/docs/fixtures/experimental/index\.md\) instead\.'
126
+
has main "${F}/plain/index.md"'[$]SHELL_VAR'
127
+
has main llms-full.txt '[$]SHELL_VAR'
128
+
lacks main "${F}/plain/index.md"'>|<|"|''
129
+
lacks main llms-full.txt '>|<|"|''
124
130
lacks main "${F}/plain/index.html"'\*\*Status:'
125
131
132
+
# llms.txt links to per-page Markdown files and prefixes non-GA statuses.
133
+
has main llms.txt '\[Plain Page\]\(https://example\.org/docs/fixtures/plain/index\.md\):'
134
+
has main llms.txt '\[Experimental Page\]\(https://example\.org/docs/fixtures/experimental/index\.md\): \[Status: Experimental\]'
135
+
has main llms.txt '\[Deprecated Page\]\(https://example\.org/docs/fixtures/deprecated/index\.md\): \[Status: Deprecated\]'
136
+
has main llms.txt '\[Planned Page\]\(https://example\.org/docs/fixtures/planned/index\.md\): \[Status: Planned\]'
137
+
126
138
# A status outside the allowed set fails the build and names the value.
127
139
if build bogus testdata/hugo.bogus.yaml;then
128
140
fail "bogus: build succeeded with status: experimantal"
0 commit comments