Skip to content

AGENTS.md

Latest commit

 

History

History
146 lines (92 loc) · 5.48 KB

AGENTS.md

File metadata and controls

146 lines (92 loc) · 5.48 KB
Raw

Cloudflare Sandbox SDK

This file provides guidance for AI coding assistants working with this repository.

Documentation Resources

Always consult Cloudflare documentation when working on this repository. Key topics:

  • API usage patterns and examples
  • Architecture concepts and best practices
  • Configuration reference (wrangler, Dockerfile)
  • Troubleshooting guides
  • Production deployment requirements

Use the gh CLI for GitHub interactions. When you need to access GitHub issues, PRs, repository information, or any GitHub-related data, use the gh CLI tool (e.g., gh issue view, gh pr view, gh repo view) instead of trying to fetch GitHub URLs directly.

Project Overview

The Cloudflare Sandbox SDK enables secure, isolated code execution in containers running on Cloudflare. The SDK allows Workers to execute arbitrary commands, manage files, run background processes, and expose services.

Status: Open Beta — API is stable but may evolve based on feedback. Safe for production use.

For the three-layer architecture, request flow, client pattern, container runtime structure, and monorepo layout, see the architecture skill (.agents/skills/architecture/SKILL.md).

Development Commands

Building

npm run build              # Build all packages (uses turbo)
npm run build:clean        # Force rebuild without cache

Testing

See the testing skill (.agents/skills/testing/SKILL.md) for detailed guidance on unit vs E2E tests.

npm test                                           # All unit tests
npm test -w @cloudflare/sandbox                    # SDK unit tests only
npm test -w @repo/sandbox-container                # Container unit tests only

npm run test:e2e                                   # All E2E tests (vitest + browser, requires Docker)
npm run test:e2e:vitest -- -- tests/e2e/file.ts   # Single vitest E2E file
npm run test:e2e:vitest -- -- tests/e2e/file.ts -t 'test name'  # Single vitest E2E test
npm run test:e2e:browser                           # Browser E2E tests only (Playwright)

Note: Use test:e2e:vitest when filtering tests. The test:e2e wrapper doesn't support argument passthrough.

Code Quality

npm run check              # Run Biome linter + typecheck
npm run fix                # Auto-fix linting issues + typecheck
npm run typecheck          # TypeScript type checking only

Docker

Docker builds are typically automated via CI, but you can build locally for testing:

npm run docker:rebuild     # Rebuild container image locally (includes clean build + Docker)

For the release pipeline, npm/Docker version sync, and CF Registry publishing, see the changesets skill (.agents/skills/changesets/SKILL.md).

Running Examples

For running, listing, and adding examples (and the EXPOSE directive note), see the examples skill (.agents/skills/examples/SKILL.md).

Development Workflow

Main branch is protected. All changes must go through pull requests. The CI pipeline runs comprehensive tests on every PR — these MUST pass before merging.

Pull Request Process

  1. Make your changes.

  2. Run code quality checks after any meaningful change:

    npm run check    # Biome linter + typecheck

    This catches type errors that often expose real issues. Fix them before proceeding.

  3. Run unit tests:

    npm test

  4. Create a changeset if your change affects published packages. See the changesets skill for rules (only @cloudflare/sandbox, user-facing descriptions, patch for almost everything).

  5. Push your branch and open a PR.

  6. CI runs automatically:

    • Unit tests for @cloudflare/sandbox and @repo/sandbox-container
    • E2E tests that deploy a real test worker to Cloudflare
    • Both suites MUST pass.

  7. After approval and passing tests, merge to main.

  8. Automated release (no manual intervention) — see the changesets skill.

Coding Standards

See the coding-standards skill (.agents/skills/coding-standards/SKILL.md) for:

  • The no-any rule and where to put new types
  • Uppercase-acronym style guide (SandboxRPCAPI, containerURL, …)
  • Code comment rules (no historical context)
  • API design guidelines

For commits, see the git-commit skill (.agents/skills/git-commit/SKILL.md). Quick reference: imperative mood, ≤50 char subject, explain why not how, no bullet points.

Important Patterns

Error Handling

  • Custom error classes in packages/shared/src/errors/
  • Errors flow from container → Sandbox DO → Worker
  • Use ErrorCode enum for consistent error types

Logging

See the logging skill (.agents/skills/logging/SKILL.md) for the constructor-injection pattern, child loggers, env-var configuration (SANDBOX_LOG_LEVEL, SANDBOX_LOG_FORMAT), and test mocking with createNoOpLogger().

Session Management

  • Sessions isolate execution contexts (working directory, env vars, etc.)
  • Default session is created automatically
  • Multiple sessions per sandbox are supported

Port Management

  • Expose internal services via preview URLs
  • Token-based authentication for exposed ports
  • Automatic cleanup on sandbox sleep
  • Production requirement: Preview URLs require a custom domain with wildcard DNS (*.yourdomain.com). .workers.dev does NOT support the subdomain patterns needed.

Releases

For changeset rules, the automated release pipeline, and Docker/npm version synchronization, see the changesets skill (.agents/skills/changesets/SKILL.md).