Skip to main content

​
Your first local gate

This is the fastest proof that EvalGate is useful: create a baseline, run the gate, break one behavior, and watch the same gate block it. The workflow runs inside the checkout with no EvalGate account, browser, organization, API key, GitHub remote, or network request. It is the intended start for an ephemeral cloud-agent sandbox; local describes the execution boundary, not a laptop.

​
What you need

  • A repository with at least one real test or EvalGate spec.
  • A terminal or non-interactive cloud-agent process.
  • No EvalGate account or GitHub remote for this local proof.

​
Step 1 — Preview the local scaffold

Install the package and inspect the complete machine-readable plan:
Availability: the credential-free init --local lifecycle below is a ships in @evalgate/sdk@3.10.0. Check feature status before depending on it in a critical release path. The examples below also work from a locally packed candidate. See the public feature-status page before depending on it.
JSON and non-TTY init is preview-only unless --apply is explicit. The preview lists every proposed file and command, writes nothing, and performs no network request.
If the product is unfamiliar, evalgate understand --format json can produce a bounded evidence-linked working theory first. understand is Experimental and optional; it is not required for init, baseline acceptance, or gating.

​
Step 2 — Apply the reviewed setup

Apply writes exactly the reviewed durable scaffold and one managed ignore block for regenerable run/report artifacts. It preserves existing files and user .gitignore content; repeating it is idempotent. The local scaffold does not create .evalgate/project.json, an organization ID, repository ID, activation ID, cloud snapshot, or credential.

​
Step 3 — Accept the first baseline

Replace any generated placeholder with at least one real deterministic case, commit the durable source/config/spec scaffold, then run:
The baseline remains pending unless a non-empty run passes. Acceptance checks source dirtiness before run-owned writes: a real source edit blocks and lists its exact path, while EvalGate-owned ephemeral reports do not make the workflow reject itself.

​
Step 4 — Prove pass → block → pass

The unchanged implementation passes. Introduce one controlled regression and run the same command: the established non-zero regression exit blocks and the report names the exact failing cases and tolerances. Repair the behavior and run again to return to PASS. No provider or EvalGate credential participates. Run evalgate status --json at any point. readiness.localGate tells an agent whether this local gate can run; hosted and cloud fields may remain false. Status exit zero means a status document was produced, not that all readiness dimensions are true. Follow nextActions.local or nextActions.primary instead of treating login as a local prerequisite.

​
Optional — Add hosted evidence later

Login is human-approved, expiring, and remotely revocable. Link adds non-secret durable organization/repository/root context plus exact cloud snapshots without replacing the local specs, baseline, config, reports, or customizations. An EVALGATE_API_KEY is for authorized automation against an already established hosted context; it is not a bootstrap shortcut for identity or linkage.

​
Troubleshooting

  • Baseline missing: follow the local init/baseline action from status; login is unrelated to the local gate.
  • Dirty worktree: commit or restore the exact source paths listed by the error. A failed attempt must not add more blocking paths.
  • The gate passed when it should block: confirm the baseline was accepted from real non-empty cases and inspect the case-level report.
  • Hosted evidence unavailable: continue the local gate. Configure login/link separately only when shared cloud evidence is intended.

​
Up next

When you want real production failures to feed the same loop, connect a model provider key or add hosted collaboration. Model-backed workflows remain BYOK.