Skip to content

Latest commit

 

History

History
148 lines (108 loc) · 3.6 KB

CONTRIBUTING.md

File metadata and controls

148 lines (108 loc) · 3.6 KB

Contributing

Documentation lives in docs/ (Mintlify). Start with:

  • docs/index.mdx for the overview
  • docs/quickstart.mdx to run the daemon
  • docs/http-api.mdx and docs/cli.mdx for API references

Development Setup

Prerequisites

  • Rust (latest stable)
  • Node.js 20+
  • pnpm 9+
  • just (optional, but recommended)

Quickstart

Run the agent locally:

sandbox-agent --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468

Extract API keys from local agent configs (Claude Code, Codex, OpenCode, Amp):

# Print env vars
sandbox-agent credentials extract-env

# Export to current shell
eval "$(sandbox-agent credentials extract-env --export)"

Run the web console (includes all dependencies):

pnpm dev -F @sandbox-agent/inspector
# or
just dev

Common Commands

# Run checks (cargo check, fmt, typecheck)
just check

# Run tests
just test

# Format code
just fmt

# Build the agent
just build

Releasing

Releases are managed through a release script that handles version bumps, artifact uploads, npm/crates.io publishing, and GitHub releases.

Prerequisites

  1. Install dependencies in the release script directory:

    cd scripts/release && pnpm install && cd ../..

  2. Ensure you have the following configured:

    • gh CLI authenticated
    • npm authenticated (npm login)
    • CARGO_REGISTRY_TOKEN for crates.io (or run cargo login)
    • R2 credentials: R2_RELEASES_ACCESS_KEY_ID and R2_RELEASES_SECRET_ACCESS_KEY (or 1Password CLI for local dev)

Release Commands

# Release with automatic patch bump
just release --patch

# Release with minor bump
just release --minor

# Release with specific version
just release --version 0.2.0

# Release a pre-release
just release --version 0.2.0-rc.1 --no-latest

Release Flow

The release process has three phases:

1. setup-local (runs locally via just release):

  • Confirms release details with user
  • Runs local checks (cargo check, fmt, typecheck)
  • Updates version numbers across all packages
  • Generates artifacts (OpenAPI spec, TypeScript SDK)
  • Commits and pushes changes
  • Triggers the GitHub Actions release workflow

2. setup-ci (runs in CI):

  • Runs full test suite (Rust + TypeScript)
  • Builds TypeScript SDK and uploads to R2 at sandbox-agent/{commit}/typescript/

3. binaries (runs in CI, parallel with setup-ci completing):

  • Builds binaries for all platforms via Docker cross-compilation
  • Uploads binaries to R2 at sandbox-agent/{commit}/binaries/

4. complete-ci (runs in CI after setup + binaries):

  • Publishes crates to crates.io
  • Publishes npm packages (SDK + CLI)
  • Promotes artifacts from {commit}/ to {version}/ (S3-to-S3 copy)
  • Creates git tag and pushes
  • Creates GitHub release with auto-generated notes

Manual Steps

To run specific steps manually:

# Run only local checks
cd scripts/release && pnpm exec tsx ./main.ts --version 0.1.0 --only-steps run-local-checks

# Build binaries locally
just release-build-all

Project Structure

sandbox-daemon/
├── server/packages/     # Rust crates
│   ├── sandbox-agent/   # Main agent binary
│   ├── agent-schema/    # Agent-specific schemas (Claude, Codex, etc.)
│   └── ...
├── sdks/
│   ├── typescript/      # TypeScript SDK (npm: sandbox-agent)
│   └── cli/             # CLI wrapper (npm: @sandbox-agent/cli)
├── frontend/packages/
│   └── inspector/       # Web console UI
├── docs/                # Mintlify documentation
└── scripts/release/     # Release automation