Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

8.5 KB
Raw Blame

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.