> ## Documentation Index
> Fetch the complete documentation index at: https://evalgate.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Your first local gate

> Give a cloud coding agent a credential-free baseline and block a regression.

# 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.

Use the [complete five-minute example](https://evalgate.com/docs/quickstart-typescript.md) for a copyable
case and exact file paths. This page explains the checkpoints in that loop.

## 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:** this credential-free `init --local` lifecycle follows the
> Experimental qualification boundary in feature status. Check the installed
> package's capabilities and the current inventory 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.

```bash theme={null}
npm install --save-dev @evalgate/sdk
npx @evalgate/sdk init --local --format json
```

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.

## Step 2 — Apply the reviewed setup

```bash theme={null}
npx @evalgate/sdk init --local --apply --format json
```

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.

| File | What it is for |
| - | - |
| `evalgate.project.json` | Local project target and baseline lineage; not hosted identity |
| `evals/baseline.json` | Pending baseline, with no fabricated passing evidence |
| `evalgate.config.json` | Local gate configuration |
| `.github/workflows/evalgate-gate.yml` | Optional reviewable CI gate |

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 every generated placeholder with at least one real deterministic case.
Register changed specs before the reviewed-source commit:

```bash theme={null}
npx @evalgate/sdk discover --manifest
```

Review and commit the durable source/config/spec scaffold and dependency
lockfile as shown in the five-minute example, then run:

```bash theme={null}
npx @evalgate/sdk baseline update
git add evals/baseline.json
git commit -m "accept reviewed passing baseline"
```

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

```bash theme={null}
npx @evalgate/sdk gate --format json
```

The unchanged implementation passes. Introduce one controlled regression and
run the same command: exit `2` blocks the behavioral regression 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

```bash theme={null}
evalgate login
evalgate link
evalgate status --json
```

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](https://evalgate.com/docs/help/evalgate-101/connect-provider-key.md) or add hosted
collaboration. Model-backed workflows remain BYOK.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.