dynobox

Cross-harness testing for multi-step agent and skill workflows.

Dynobox runs agent scenarios through local harnesses such as Claude Code, Codex, OpenCode, Pi, Cursor CLI, and Google Antigravity CLI, captures observable behavior, and evaluates assertions against what actually happened.

• Site: dynobox.xyz
• Docs: docs.dynobox.xyz
• GitHub: github.com/dynobox/dynobox

Install

npm install -g dynobox

Dynobox requires Node.js 22 or later. The selected harness executable must already be installed, authenticated, and available on PATH: claude, codex, opencode, pi, cursor-agent, or agy 1.1.14 or newer.

Quick Start

Create a starter dyno file, then run it:

dynobox init                         # Claude Code (default)
dynobox init --harness codex         # OpenAI Codex
dynobox init --harness opencode      # OpenCode
dynobox init --harness pi            # Pi
dynobox init --harness cursor        # Cursor CLI
dynobox init --harness antigravity   # Google Antigravity CLI
dynobox discover
dynobox run

Run one init command for a harness that is installed and authenticated. dynobox init writes dynobox/example.dyno.mjs by default. dynobox run with no argument discovers *.dyno.{mjs,js,ts,mts,yaml,yml} files recursively under the current directory. dynobox discover prints the same file list without loading configs or running harnesses.

Only run dynos you trust. JavaScript and TypeScript configs are imported, and setup and verification commands execute on your machine. Temporary work directories separate job files, but they are not security sandboxes; processes can access the host according to their permissions.

Scope a run to a directory or file:

dynobox run .agents/skills/
dynobox run my-skill.dyno.yaml

Pick one or more installed and authenticated harnesses at runtime when needed:

dynobox run --harness claude-code
dynobox run --harness codex
dynobox run --harness opencode
dynobox run --harness pi
dynobox run --harness cursor
dynobox run --harness antigravity
dynobox run --harness claude-code,codex,opencode,pi,cursor,antigravity

Repeat each selected scenario/harness pair when you want a pass-rate signal:

dynobox run --harness claude-code,codex,opencode,pi,cursor,antigravity --iterations 5

What You Can Assert

Dynobox supports assertions for:

• Tool calls with tool.called(...) and tool.notCalled(...).
• Normalized commands with command.called(...) and command.notCalled(...).
• File tool path matchers such as tool.called('read_file', {path: 'package.json'}).
• Ordered behavior with sequence.inOrder(...) and alternatives with anyOf(...).
• Skill instruction file references.
• Work-directory artifacts, including unchanged and absent files.
• Harness transcript and final response text.
• HTTP requests from local child-process tools that honor proxy environment variables.
• Post-run executable checks with verify.command(...).

Scenario-scoped CLI mocking is experimental. It can replace bare executable calls with static, sequential, or handler-based responses and expose recorded calls to command assertions. See CLI Mocks for the contract and current limits.

Common Run Flags

• --quiet: compact discovery, dots-and-failures, and summary output for CI.
• --verbose: expand every job with phase rows and assertion details.
• --debug: include verbose details plus work directory, artifact paths, and debug log paths.
• --reporter json: emit newline-delimited JSON reports.
• --scenario <pattern>: run only matching scenarios.
• --iterations <count>: repeat each selected scenario/harness pair.
• --permission-mode default|dangerous: override harness permission behavior.
• --save-run: upload a compact summary to the dashboard or DYNOBOX_UPLOAD_URL.

Authentication And Uploads

Use dynobox login to paste a dashboard-generated CLI token into local config, then dynobox whoami to verify the saved identity. dynobox logout removes the saved token. CLI tokens expire after 24 hours; when a token expires, run dynobox login again to re-authenticate.

Authenticated runs can upload a compact dashboard summary with dynobox run --save-run. You can also set DYNOBOX_TOKEN instead of using the saved local config. To post the schema v4 JSON payload to your own endpoint without Dynobox authentication, set DYNOBOX_UPLOAD_URL to the exact destination URL. The CLI does not send a Dynobox Authorization header to custom upload URLs.

Saved-run data is length-capped but not redacted. It includes available Git commit, branch, dirty-state, and configured user name/email metadata. All jobs can include authored assertion data and matched evidence such as requested endpoint URLs, tool commands, and verification output. Failed jobs can additionally include command or harness diagnostics. Do not use --save-run when those values should not be shared.

Documentation

• Getting Started
• Config Authoring
• CLI Reference