Skip to content

Commit aea6295

Browse files
volatilemolotovvolatilemolotov
committed
add documentation
1 parent 2332dd1 commit aea6295

File tree

7 files changed

+269
-0
lines changed

7 files changed

+269
-0
lines changed

‎site/content/docs/_index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: "Documentation"
3+
linkTitle: "Documentation"
4+
weight: 20
5+
menu:
6+
main:
7+
weight: 20
8+
---

‎site/content/docs/concepts/_index.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: "Concepts"
3+
linkTitle: "Concepts"
4+
weight: 2
5+
description: >
6+
This section of the documentation helps you learn about the components, APIs and abstractions that Agent Sandbox uses to represent your cluster and workloads Core Agent Sandbox Concepts
7+
---
8+
9+
## Sandbox
10+
11+
The `Sandbox` CRD is designed to solve the problem of managing **isolated, stateful, singleton workloads** in Kubernetes.
12+
13+
While Kubernetes is exceptionally good at running stateless, replicated applications (like web servers managed by a `Deployment`), it lacks a simple, dedicated abstraction for applications that need to be:
14+
15+
* **Singleton:** only one instance of the application should ever be running.
16+
* **Stateful:** the application needs to retain its state (e.g., files on a disk, configuration, user data) across restarts or updates.
17+
* **Isolated:** it requires a secure, self-contained environment, often for running user-provided code or interactive sessions.
18+
19+
Common examples include AI agent runtimes, remote development environments (like a VS Code server), or data science tools (like a Jupyter Notebook). Today, users often resort to using a `StatefulSet` with `replicas: 1` as a workaround, but this is a cumbersome approach that doesn't offer specialized features for this use case.
20+
21+
The `Sandbox` resource provides a **first-class API** for these workloads, making their management declarative, simple, and Kubernetes-native.
22+
23+
## Benefits
24+
25+
Using the `Sandbox` CRD provides several key benefits:
26+
27+
1. **Declarative Simplicity:** instead of manually creating and managing a `StatefulSet`, `PersistentVolumeClaim`, and `Service`, we can define a single `Sandbox` resource. The controller handles the complexity of creating and wiring together the underlying components.
28+
29+
2. **Stateful by Design:** persistence is a core feature. The `Sandbox` automatically manages a persistent volume, ensuring that any data saved within the environment survives pod restarts, crashes, or node failures.
30+
31+
3. **Strong Isolation:** by design, it encourages running workloads in an isolated manner, which is critical for security, especially in multi-tenant environments where you might be running untrusted code.
32+
33+
## Simple Example
34+
35+
Here is a basic example of a `Sandbox` manifest that runs a simple container with a persistent home directory.
36+
{{% snippet file="additional/examples/sandbox-ksa/sandbox.yaml" type="yaml" %}}
37+
38+
39+
## Glossary
40+
41+
* **Controller**
42+
The cluster-level component that reconciles the state of `Sandbox` resources, managing their underlying `StatefulSets` and `PersistentVolumeClaims`.
43+
44+
* **Custom Resource Definition (CRD)**
45+
An extension of the Kubernetes API that introduces the `Sandbox` resource, making it a native object in the cluster.
46+
47+
* **PersistentVolumeClaim (PVC)**
48+
A request for storage used by a `Sandbox` to provide a persistent, stateful filesystem for the workload.
49+
50+
* **Sandbox**
51+
The unit of deployment in `agent-sandbox`. It represents an isolated, stateful, and singleton workload, often used for development environments or AI agent runtimes.
52+
53+
* **Singleton Workload**
54+
An application designed to have only one running instance, which is the core management pattern for the `Sandbox` resource.
55+
56+
* **Stateful Workload**
57+
An application that requires its data to be preserved across restarts and hibernations.
58+
59+
* **StatefulSet**
60+
The underlying Kubernetes API object used by the controller to manage a `Sandbox`'s pod and ensure it has a stable identity and persistent storage.

‎site/content/docs/contribution_guidelines/_index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: "Contribution Guidelines"
3+
linkTitle: "Contribution Guidelines"
4+
weight: 25
5+
description: >
6+
How to contribute to Agent Sandbox
7+
---
8+
{{% include-file file="additional/CONTRIBUTING.md" %}}

‎site/content/docs/contribution_guidelines/testing.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: "Running and debugging tests"
3+
linkTitle: "Running tests"
4+
weight: 25
5+
description: >
6+
Running and debugging tests
7+
---
8+
9+
## To create a kind cluster
10+
```shell
11+
make deploy-kind
12+
```
13+
14+
## Running unit tests
15+
To run all unit tests:
16+
```shell
17+
make test-unit
18+
```
19+
## Running the e2e tests
20+
To run all e2e tests:
21+
```shell
22+
make test-e2e
23+
```
24+
## Remove the kind cluster
25+
```shell
26+
make delete-kind
27+
```
28+
29+
### See also
30+
- [Kubernetes testing guide](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-testing/testing.md)
31+
- [Integration Testing in Kubernetes](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-testing/integration-tests.md)
32+
- [End-to-End Testing in Kubernetes](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-testing/e2e-tests.md)
33+
- [Flaky Tests in Kubernetes](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-testing/flaky-tests.md)

‎site/content/docs/installation/_index.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: "Installation"
3+
linkTitle: "Installation"
4+
weight: 3
5+
description: >
6+
Installing Agent Sandbox to a Kubernetes Cluster
7+
---
8+
This guide provides step-by-step instructions for installing and running the agent-sandbox controller on kind (Kubernetes in Docker) for local development and testing.
9+
10+
## Before You Begin
11+
12+
Ensure you have the following prerequisites installed:
13+
14+
**Required Tools:**
15+
- [Docker](https://docs.docker.com/get-docker/)
16+
- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)
17+
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
18+
19+
**Verify installations:**
20+
```bash
21+
docker --version
22+
kind --version
23+
kubectl version --client
24+
```
25+
## Create a Kind cluster
26+
27+
Create a kind cluster with:
28+
29+
```bash
30+
kind create cluster --name agent-sandbox
31+
```
32+
33+
## Deploy Agent-Sandbox to kind
34+
35+
### Clone the Repository
36+
37+
```bash
38+
git clone https://github.com/kubernetes-sigs/agent-sandbox.git
39+
cd agent-sandbox
40+
```
41+
### Deploy to kind
42+
43+
With kubectl install the controller:
44+
45+
```bash
46+
export VERSION=v0.1.0
47+
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/manifest.yaml
48+
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/extensions.yaml
49+
```
50+
51+
This command will:
52+
1. Create a kind cluster named `agent-sandbox` (if it doesn't exist)
53+
2. Build the controller container image
54+
3. Load the image into the kind cluster
55+
4. Deploy the controller to the cluster in the `agent-sandbox-system` namespace
56+
57+
### Verify Installation
58+
59+
Check that the controller is running:
60+
61+
```bash
62+
# Check controller pod status
63+
kubectl get pods -n agent-sandbox-system
64+
65+
# Verify CRDs are installed
66+
kubectl get crds | grep agents.x-k8s.io
67+
68+
# Check controller logs
69+
kubectl logs -n agent-sandbox-system -l control-plane=controller-manager -f
70+
```
71+
72+
You should see the controller pod in `Running` state.
73+
74+
## Uninstall
75+
76+
Remove agent-sandbox from your cluster:
77+
78+
```bash
79+
# Delete all sandbox resources
80+
kubectl delete sandboxes --all
81+
82+
# Remove the controller and namespace
83+
kubectl delete namespace agent-sandbox-system
84+
85+
# Delete CRDs
86+
kubectl delete crd sandboxes.agents.x-k8s.io
87+
```
88+
89+
Delete the kind cluster:
90+
91+
```bash
92+
kind delete cluster --name agent-sandbox
93+
```
94+
95+
## Troubleshooting
96+
97+
**Controller pod not starting:**
98+
- Check logs: `kubectl logs -l app=agent-sandbox-controller`
99+
- Verify RBAC permissions: `kubectl get clusterroles,clusterrolebindings | grep agent-sandbox`
100+
- Check if CRDs are properly installed: `kubectl get crds | grep agents`
101+
- Verify the image is correct: `kubectl get statefulset agent-sandbox-controller -o yaml | grep image:`
102+
103+
**Storage issues:**
104+
- kind uses local Docker storage - ensure Docker has enough disk space
105+
- Check Docker disk usage: `docker system df`
106+
- Clean up unused images: `docker system prune`
107+
- Verify PVC is bound: `kubectl get pvc`
108+
109+
**Out of memory errors:**
110+
- kind uses Docker resources - check Docker resource limits in Docker Desktop settings
111+
- Increase Docker memory allocation (recommend 8GB+ for development)
112+
- Reduce sandbox resource requests if needed
113+
114+
**Building the Controller Binary:**
115+
116+
To build just the controller binary:
117+
118+
```bash
119+
make build
120+
```
121+
122+
Binary will be at `bin/manager`.
123+
124+
**Regenerating CRDs and RBAC:**
125+
126+
After modifying `api/` or `controllers/` directories:
127+
128+
```bash
129+
make all
130+
```
131+
132+
## Additional Resources
133+
134+
- [Agent-Sandbox GitHub Repository](https://github.com/kubernetes-sigs/agent-sandbox)
135+
- [Agent-Sandbox Development Guide](https://github.com/kubernetes-sigs/agent-sandbox/blob/main/docs/development.md)
136+
- [kind Documentation](https://kind.sigs.k8s.io/)
137+
- [Kubernetes SIG-Apps](https://github.com/kubernetes/community/tree/master/sig-apps)

‎site/content/docs/overview/_index.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: "Overview"
3+
linkTitle: "Overview"
4+
weight: 1
5+
description: >
6+
Why Agent Sandbox?
7+
---
8+
9+
Agent Sandbox represents a critical new layer of AI infrastructure that provides a controlled, isolated execution environment for code execution and computer use used in AI Agents and Reinforcement Learning (RL).
10+
11+
## Why use Agent Sandbox?
12+
Agent Sandbox is cloud agnostic, and can be used on top of any implementation of Kubernetes. By acting as a secure, contained "isolated environment", Agent Sandbox ensures that untrusted or dynamically generated code or commands are isolated, preventing potential risks such as compromising production systems, accidentally corrupting data, or accessing unauthorized hosts. This environment is engineered for high-scale, secure deployment, offering strong isolation capabilities, alongside advanced lifecycle features such as suspending, and warm pools to achieve low-latency performance necessary for scalable agent platforms.
13+
14+
15+
## Features Overview
16+
Agent Sandbox - This core resource provides a declarative KRM API for managing isolated, single-instance execution environments, ensuring each Sandbox is unique and disposable.
17+
Suspend/Resume - Allows users to pause sandboxes—which deletes the Pod while preserving state via the PVC and Service—and resume them by recreating the Pod.
18+
WarmPools - The Sandbox Warm Pool Orchestrator utilizes a dedicated CRD to maintain a pool of pre-warmed pods, allowing the Sandbox Controller to claim a ready instance upon creation to mitigate cold start latency.
19+
Time to Live (TTL) - Automates deletion using configurable duration (.spec.ttl.seconds) and start policies (.spec.ttl.startPolicy) to set a .status.shutdownAt time, after which the sandbox is immediately removed.
20+
Python API/SDK - Provides a developer-friendly interface to programmatically interact with these CRDs, abstracting away Kubernetes complexities.
21+
22+
23+
![alt](diagram.png)

‎site/content/docs/overview/diagram.png‎

23.7 KB
Loading

0 commit comments

Comments
 (0)