AGENTS.md · opensandbox-group/OpenSandbox

Sections

1. Repository Map
2. Routing
3. Working Principles
4. Guardrails
5. Documentation Rules
6. Review Focus

First lines (shown under the repo's Apache-2.0 license)

# OpenSandbox AGENTS

Use this file as the root router for the monorepo. Prefer the nearest `AGENTS.md` in the directory tree for task-specific instructions.

## Repository Map

- `server/`: FastAPI lifecycle control plane, Docker/Kubernetes runtime integration, snapshot metadata, and server tests
- `components/execd/`: in-sandbox execution daemon
- `components/egress/`: per-sandbox network egress policy sidecar
- `components/ingress/`: ingress gateway and endpoint routing
- `components/internal/`: shared Go helpers used by runtime components
- `sdks/`: sandbox, code-interpreter, and MCP SDKs plus generated clients
- `specs/`: public OpenAPI contracts and examples
- `kubernetes/`: Kubernetes operator, CRDs, task-executor, and Kind e2e tests
- `manifests/charts/`: Helm charts (base, controller, server, ingress-gateway, node-agent, fast-sandbox, opensandbox umbrella)
- `cli/`: `osb` command-line client and bundled CLI skills
- `console/`: developer console (React SPA + FastAPI BFF), optional K8s examples; no server/spec changes
- `tests/`: cross-language end-to-end SDK tests
- `docs/`, `examples/`, `oseps/`: documentation, samples, and proposals

## Routing

- For `server/**`, or lifecycle server behavior, sandbox creation flow, or user-visible server config, read `server/AGENTS.md`.
- For `sdks/**`, or SDK generation, handwritten adapters, or cross-language SDK alignment, read `sdks/AGENTS.md`.
- For `specs/**`, or API contract, schema, or example changes, read `specs/AGENTS.md`.
- For `kubernetes/**`, or CRDs, controller behavior, task execution, Helm/Kustomize deployment, pool scheduling, pause/resume snapshots, or Kind e2e tests, read `kubernetes/AGENTS.md`.
- For cross-cutting changes spanning spec, server, and SDKs, start with `specs/AGENTS.md` and then read affected consumer guides.
- For runtime component changes under `components/**`, read the nearest `README.md` or `DEVELOPMENT.md`; keep component APIs aligned with `specs/` and SDK consumers.
- For CLI changes under `cli/**`, read `cli/README.md` and verify command help/output behavior alongside unit tests.
- For console changes under `console/**`, read `console/README.md` and `console/docs/`; run `console/web` build and keep BFF env docs aligned with `console/k8s/*.example.yaml`.
- For cross-language e2e tests under `tests/**`, read the language-local README and keep test assumptions aligned with current server and SDK behavior.
- For areas without a local `AGENTS.md`, use the nearest `README.md`, `DEVELOPMENT.md`, and CI workflow as the next source of truth.

## Working Principles

- Think before coding: state assumptions, surface ambiguity, and ask or push back when the request has conflicting interpretations.
- Simplicity first: implement the smallest solution that satisfies the request; avoid speculative features, one-off abstractions, and unnecessary configurability.
- Surgical changes: touch only files and lines needed for the task, match local style, and do not refactor or delete unrelated pre-existing code.
- Goal-driven execution: translate non-trivial work into verifiable success criteria, add or update focused tests when behavior changes, and loop until checks pass or blockers are clear.

## Guardrails

Always:

- Treat `specs/*` as public contract sources.
- Keep spec, implementation, SDKs, docs, examples, config, and CLI behavior aligned when user-visible behavior changes; update `docs/` first.
- When changing `specs/*`, also update or verify affected server, SDK, docs, and release outputs when practical.
- When changing CRDs or Kubernetes public behavior, update or verify generated manifests, Helm/Kustomize deployment output, server Kubernetes integration, and docs when practical.
- Prefer additive, backward-compatible changes for public interfaces.
- Regenerate derived outputs when the source-of-truth file changes.
- Mention unrun or blocked verification in the final handoff.
- Prefer file-scoped or package-scoped checks before full-suite validation.

Ask first:

- Breaking public API, SDK, config, protocol, or CLI changes
- Breaking CRD, annotation, label, Helm values, or Kubernetes deployment changes
- Intentional drift between a public contract and its implementation
- User-visible config or behavior changes without a clear migration story

Never:

- Edit generated output as the only fix.
- Mix unrelated component work into the same change.

## Documentation Rules

### Content ownership — single source of truth

| Content type | Source of truth | Rule |
|---|---|---|
| Root README | repo root `README.md` | GitHub homepage |
| SDK, CLI, Helm, and other publishable package READMEs | package directory | Keep install, quick start, and package entry points; no long-form docs |
| Non-publishable component/module READMEs | component/module directory | Keep minimal pointers to `docs/` when a docs page exists |
| Examples | `docs/examples/` + runnable code under `examples/` | Put docs in `docs/examples/`; keep example READMEs as thin pointers |
| OSEPs | `oseps/` | `docs/community/oseps.md` only indexes GitHub proposals |
| CONTRIBUTING, CODE_OF_CONDUCT, DEVELOPMENT | repo root / component directory | `docs/community/` links to them, does not duplicate them |

**When adding design/how-it-works content**: high-level architecture design and implementation principles go under `docs/architecture/`; user-facing usage instructions go under `docs/guides/`. Do not mix usage how-tos into architecture pages, or internals into guides.

**When handling localized READMEs**: do not add new localized copies for SDKs, examples, or non-special modules.

**When linking from README files to docs**: prefer repository-relative `docs/*.md` links (they match the checked-out branch/tag); use `https://open-sandbox.ai` only as a public site entry point, not as the only source link from versioned code directories.

### Docs site structure

```
docs/
  getting-started/     # Quick start, installation, configuration
  architecture/        # High-level architecture design and implementation principles (overview, control-plane/, data-plane/, network/, fast-sandbox/)
  deployment/          # Deployment and operations (Kubernetes install, storage, metrics)
  guides/              # User-facing usage and feature guides (credential vault, secure container, pause/resume, etc.)
  sdks/                # SDK reference (one page per language per SDK)
  api/                 # OpenAPI spec reference
  cli/                 # CLI reference
  examples/            # One page per example
  community/           # Contributing, code of conduct, OSEPs, releases
  reference/           # Migration guides
```

### Docs conventions

- Engine: VitePress. Config is a static `config.mts` with no build-time code generation.
- All images go in `docs/public/images/`. Reference them with a document-relative path to that directory (for example, `../public/images/filename` from `docs/guides/`) so they render in both repository previews and VitePress.
- Every page must have YAML frontmatter with `title` and `description`.
- Internal links use VitePress absolute paths (e.g., `/sdks/python`, `/guides/credential-vault`).
- Links to source code or specs use full GitHub URLs.
- Use VitePress custom containers (`::: tip`, `::: warning`, `::: info`) and code groups where appropriate.
- Build and verify: `cd docs && pnpm docs:build` — must complete with zero errors.
- The README.md in `docs/` is for docs-site contributors only (how to run dev server), and must stay excluded from the published site.
- Markdown prose style, for all `.md` files in the repo: do not hard-wrap prose — a sentence or paragraph is written on a single line and editors soft-wrap. One line per list item and per blockquote paragraph.
- Hard breaks (two trailing spaces or a trailing backslash) are only for intentional rendering, never for prose wrapping. Keep verbatim blocks untouched: code blocks, tables, YAML frontmatter, HTML blocks, ASCII diagrams. Never reflow generated markdown (e.g., helm-docs chart READMEs under `manifests/charts/*/README.md`) — change its source template and regenerate instead.
- Never insert a blank line inside a paragraph, and never reflow or re-structure unrelated markdown while editing a file. When generating markdown programmatically, join soft-wrapped lines with a single space (no space between adjacent CJK characters).

## Review Focus

- Prioritize breaking changes in specs, SDK interfaces, config, CLI behavior, and protocols; flag protocol changes that are unnecessary, inconsistent, or hard to implement.
- Flag changes that break source-of-truth boundaries or intended layering.
- Call out missing tests and compatibility risks explicitly.