mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 22:03:48 +00:00
148 lines
3.6 KiB
Markdown
148 lines
3.6 KiB
Markdown
# 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](https://github.com/casey/just) (optional, but recommended)
|
|
|
|
### Quickstart
|
|
|
|
Run the agent locally:
|
|
|
|
```bash
|
|
sandbox-agent --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
|
|
```
|
|
|
|
Extract API keys from local agent configs (Claude Code, Codex, OpenCode, Amp):
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```bash
|
|
pnpm dev -F @sandbox-agent/inspector
|
|
# or
|
|
just dev
|
|
```
|
|
|
|
### Common Commands
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
```
|