# Conseqa runner 0.1.4 — public installation

These curated files require no access to the private GitHub repository. Node.js 22.13+ and Docker Compose are needed. Linux amd64 and arm64 runner images are published.

Download `install.mjs` from https://www.conseqa.dev/runner-release/install.mjs and review it before running. The owned canonical origin is `https://www.conseqa.dev`; `https://conseqa.vercel.app` is a transitional fallback. The release version, image digest and signing-key fingerprint are unchanged by this origin migration.

```sh
node install.mjs --directory ./conseqa-local
cd conseqa-local
npx --yes --package @conseqa/cli@0.1.4 conseqa init
npx --yes --package @conseqa/cli@0.1.4 conseqa contracts build
npx --yes --package @conseqa/cli@0.1.4 conseqa contracts test
```

The installer creates a fresh folder only. It downloads explicitly allowlisted public files, generates independent random secrets into `.env`, and never starts services or overwrites an existing folder. It does not copy the private repository, upload credentials, install packages or contact a provider. Keep `.env` private; Unix file mode is 0600. On Windows, check folder ACLs yourself before putting real credentials in it.

The CLI starter is deliberately PARTIAL: its verification callback returns Unknown until you implement a read-only source-of-record check. A passing offline regression demonstrates the test format, not successful real-world verification. Customize the client, runner and schemas before protecting real actions.

## Verify the runner image

Pin the public key's SPKI DER SHA-256 fingerprint through a trusted channel:

`68e5412daf00ef00c43c0e93b1e342add20e2e4239c6833bdc3d8a72fb79441d`

Use Node.js 22.13+ and ORAS 1.3.4+. Follow https://www.conseqa.dev/docs#docker-verification to check the fingerprint and verify the signed descriptor. Stop if it is missing or invalid; do not bypass signature verification. The compose file pins the released image digest, not `latest`:

`ghcr.io/devrajsinh-jhala/conseqa-runner@sha256:37fe678130cbb12140e0388a7afc140f07fba072a0e8d5b1d77d4ee94e7350aa`

## Start locally

```sh
docker compose up -d conseqa
```

Load `.env` into the CLI process without printing it. With Node 22+ this is portable when the CLI is a local dependency:

```sh
npm install --save-dev @conseqa/cli@0.1.4
node --env-file=.env node_modules/@conseqa/cli/dist/index.js contracts install --runner http://127.0.0.1:4319
node --env-file=.env node_modules/@conseqa/cli/dist/index.js doctor
```

The runner is accessible only at `127.0.0.1:4319` on the host. Sidecar and administration tokens are independent. Do not publish this port or put either token in a browser. Read-only verifier credentials belong in the runner environment, never the hosted service or the contract manifest. Add only the provider credential names your installed contract needs.

## Connect the hosted workspace

Create an environment API key in workspace Settings. In the private `.env`, set both:

```dotenv
CONSEQA_INGEST_ENDPOINT=https://www.conseqa.dev
CONSEQA_ENVIRONMENT_KEY=<your-environment-key>
```

Then enable the file-backed Collector queue and publish only contract metadata:

```sh
docker compose --profile cloud up -d
node --env-file=.env node_modules/@conseqa/cli/dist/index.js contracts publish --cloud https://www.conseqa.dev
```

Configure your application's OpenTelemetry exporter to `http://127.0.0.1:4318` (host) or `http://otel-collector:4318` (same Compose network). No prompts/tool bodies are captured by default. Do not assume arbitrary custom attributes are sanitized: configure your own allowlist/redaction as appropriate. The collector queues traces locally while the control plane is unavailable.

## Persistent production placement

Run one runner instance per environment beside your application on a private network. Persist the three runner volumes and the Collector queue. Back up the SQLite database, contract packages and encryption keys safely; keys must be recoverable independently. The hosted Neon backup does not back up your runner or provider databases.

A host application can omit an SDK spool and required actions then fail closed if the runner is unavailable. Offline SDK spooling requires mounting **the same** `conseqa-spool` volume into the application, matching the runner's UID/GID 10001, and supplying the same spool key/key ID. A separate host directory is not a shared durable spool. Never enable required fallback before the contract hash has been validated in that environment.

Do not run `docker compose down -v` against production: it deletes the persistent volumes. High availability, automatic remediation and managed customer credentials are not provided by this bundle.