Contributing to AgentBox

Thanks for taking the time. Bug reports, docs fixes, and provider work are all welcome.

Before you start

For anything larger than a bug fix, open an issue first and describe what you want to do. It saves you from building something that doesn't fit the direction of the project.

If you are adding a new sandbox backend, you probably want a provider plugin rather than a change to this repo — see Build a provider and docs/provider-plugins.md.

Development

Node 22 and pnpm. docs/development.md has the full loop; the short version:

pnpm install
pnpm build
pnpm lint && pnpm typecheck && pnpm test

CI runs exactly those checks on every pull request, so run them locally first. Unit tests must stay pure — no docker, no network. Integration testing is manual for now.

A few conventions worth knowing: TypeScript strict + ESM (import type for types), tsup per package, vitest for tests, commander + @clack/prompts for CLI surface, and comments only where the why is non-obvious. CLAUDE.md documents the architecture and the house style in more detail.

If your change adds or alters a CLI command, flag, config key, default, or provider behavior, update the matching page under apps/web/content/docs/ in the same pull request. Stale public docs are treated as a bug.

Contributor License Agreement

Before your first pull request can be merged, you need to accept the Contributor License Agreement. A bot will comment on the pull request with a one-line sentence to post as a reply; that's the whole process, and it only happens once.

You keep the copyright to your work — the CLA is a license grant, not an assignment. It exists so the project has a clear, written chain of rights over everything it ships.

Reporting security issues

Please don't open a public issue. See SECURITY.md.