OPENCLAW_TESTBOX=1

OPENCLAW_TESTBOX=1

• Pre-warm a Testbox early for longer, wider, or uncertain work.
• Prefer Testbox for

  pnpm

  gates, e2e, package-like proof, and broad suites.
• Reuse the same Testbox ID for every run command in the same task/session.
• Use local commands only when the task explicitly sets

  OPENCLAW_LOCAL_CHECK_MODE=throttled|full

  , or when the user asks for local proof.

--organization

--non-interactive

blacksmith auth login --non-interactive --organization <org-slug>

BLACKSMITH_ORG

--org

blacksmith auth login --non-interactive --organization acme-corp
blacksmith --org acme-corp auth login --non-interactive --organization acme-corp

--api-token

• --dashboard-url <url>

  — Override dashboard URL (e.g. for staging)

• the repo documents a supported local test/build workflow
• you are iterating on unit tests, lint, typecheck, formatting, or other local-only validation
• the value comes from warm local caches and fast repeat runs
• the command does not need remote secrets, hosted services, or CI-only images

• the repo explicitly requires CI-parity or remote validation
• the command needs secrets, service containers, or provisioned infra
• you are reproducing CI-only failures
• you need the exact workflow image/job environment from GitHub Actions

OPENCLAW_TESTBOX=1

• pnpm check:changed

• pnpm test:changed

• pnpm test <path-or-filter>

• pnpm test:serial

• pnpm build

OPENCLAW_TESTBOX=1

OPENCLAW_LOCAL_CHECK_MODE=throttled

Package Acceptance

source=npm

source=ref

source=url

source=artifact

package-under-test

workflow_ref

package_ref

run

1. The testbox VM starts from a clean

   actions/checkout

   at the warmup ref. The workflow's setup steps (e.g.

   npm install

   ,

   pip install

   ,

   composer install

   ) run during warmup and populate dependency directories on the remote VM.
2. On each

   run

   , the CLI uses git to detect which files changed locally since the last sync. It syncs ONLY tracked files and untracked non-ignored files (i.e. files that

   git ls-files

   reports).

3. .gitignore

   'd directories are never synced. This means directories like

   node_modules/

   ,

   vendor/

   ,

   .venv/

   ,

   build/

   ,

   dist/

   , etc. are NOT transferred from your local machine. The testbox uses its own copies of those directories, populated during the warmup workflow steps.
4. If nothing has changed since the last sync (same git commit and working tree state), the sync is skipped entirely for speed.

• Changing dependencies: If you modify

  package.json

  ,

  requirements.txt

  ,

  composer.json

  ,

  go.mod

  , or similar dependency manifests, the lock/manifest file will be synced but the actual dependency directory will NOT. You must re-run the install command on the testbox:

  blacksmith testbox run --id <ID> "npm install && npm test"
  blacksmith testbox run --id <ID> "pip install -r requirements.txt && pytest"
  blacksmith testbox run --id <ID> "composer install && phpunit"

• Generated/build artifacts: If your tests depend on a build step (e.g.

  npm run build

  ,

  make

  ), and you changed source files that affect the build output, re-run the build on the testbox before testing.
• New untracked files: New files you create locally ARE synced (as long as they are not gitignored). You do not need to

  git add

  them first.
• Deleted files: Files you delete locally are also deleted on the remote testbox. The sync model keeps the remote in lockstep with your local managed file set.

• running database migrations or destructive environment checks
• running commands that depend on secrets or environment variables not present locally
• reproducing CI-only failures or validating against the workflow image
• validating behavior that needs provisioned services or remote runners
• doing a final parity check before commit/push when the repo or user wants that

1. Decide whether the repo's local loop is the right default. For OpenClaw,

   OPENCLAW_TESTBOX=1

   makes Testbox the maintainer default.
2. If Testbox is warranted, warm up early:

   blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90

   → save the ID, then

   pnpm testbox:claim --id <ID>

3. Write code while the testbox boots in the background.
4. Run the remote command when needed:

   pnpm testbox:run --id <ID> -- "OPENCLAW_TESTBOX=1 pnpm check:changed"

5. If tests fail, fix code and re-run against the same warm box.
6. If you changed dependency manifests (package.json, etc.), prepend the install command:

   blacksmith testbox run --id <ID> "npm install && npm test"

7. If a narrow PR reports a full sync or the box was reused/expired, sanity check the remote copy before a slow gate:

   pnpm testbox:run --id <ID> -- "pnpm testbox:sanity"

   . If it reports missing root files or mass tracked deletions, stop the box and warm a fresh one. Use

   OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1

   only for an intentional large deletion PR.
8. If you need artifacts (coverage reports, build outputs, etc.), download them:

   blacksmith testbox download --id <ID> coverage/ ./coverage/

9. Once green, commit and push.

blacksmith testbox run --id <ID> "env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test"

• 173-180s on a warmed box
• 219s on a fresh 32-vCPU box

pnpm check:changed

pnpm testbox:sanity

pnpm-lock.yaml

Check status of a specific testbox

blacksmith testbox status --id <ID>

# List all active testboxes for the current repo
blacksmith testbox list

# Stop a testbox when you're done (frees resources)
blacksmith testbox stop --id <ID>

blacksmith testbox warmup ci-check-testbox.yml --idle-timeout 90
blacksmith testbox warmup ci-build-artifacts-testbox.yml --idle-timeout 90