> ## Documentation Index
> Fetch the complete documentation index at: https://solo-09d10f60.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run the Enoch FastAPI app locally and exercise the bounded operator dashboard smoke test.

This quickstart gets a developer clone to a running local API and dashboard. It does not require a real worker machine.

## 1. Install dependencies and run tests

```bash theme={null}
git clone https://github.com/alias8818/enoch-agentic-research-system.git
cd enoch-agentic-research-system
uv venv --python /usr/bin/python3 .venv
uv pip install --python .venv/bin/python -e .
uv run pytest -q
```

## 2. Create a local config

```bash theme={null}
mkdir -p .local/state .local/projects .local/config
cp config.example.json .local/config/config.json
python3 - <<'PY'
import json, pathlib, secrets
p = pathlib.Path('.local/config/config.json')
data = json.loads(p.read_text())
data['state_dir'] = str(pathlib.Path('.local/state').resolve())
data['project_root'] = str(pathlib.Path('.local/projects').resolve())
data['dispatch_script_path'] = str(pathlib.Path('deploy/enoch_codex_dispatch.sh').resolve())
data['control_api_bearer_token'] = secrets.token_urlsafe(48)
data['completion_callback_token'] = secrets.token_urlsafe(48)

<Note>
The source repository quickstart uses `secrets.token_urlsafe(32)` for both tokens; either length is acceptable because the token is opaque to the runtime. The deployment guide uses 48 bytes for stronger entropy on long-lived deployments. Do not commit any token value.
</Note>
data['completion_callback_url'] = 'http://127.0.0.1:8787/omx/event'
data['worker_wake_gate_url'] = 'http://127.0.0.1:8787'
data['worker_wake_gate_bearer_token'] = data['control_api_bearer_token']
p.write_text(json.dumps(data, indent=2) + '\n')
print(data['control_api_bearer_token'])
PY
```

Copy the printed token. The dashboard and control API expect it as a bearer token.

## 3. Start the API

```bash theme={null}
export ENOCH_CONFIG=$PWD/.local/config/config.json
uv run uvicorn enoch_control_plane.app:app --host 127.0.0.1 --port 8787
```

Open the **canonical** operator console:

```text theme={null}
http://127.0.0.1:8787/control/dashboard-v2
```

If you use the shorter `/dashboard` URL, it redirects to `/control/dashboard-v2` (the canonical V2 shell) on current deployments. `/control/dashboard` also 307-redirects to `/control/dashboard-v2`.

The dashboard opens as a professional operator console. It leads with attention, running work, paper-writing, finalization, and publish/import cards instead of raw JSON.

## 4. Run smoke tests

In a second shell:

```bash theme={null}
export ENOCH_CONFIG=$PWD/.local/config/config.json
scripts/smoke-test-local.sh
```

Expected result: health, bounded overview, preflight, and dispatch dry-run endpoints respond with JSON. The smoke uses `/control/api/v1/overview` by default so large live ledgers do not make the check noisy. Set `ENOCH_STATUS_ENDPOINT=/control/api/status` only when you intentionally need the wider compatibility payload. For a control-plane-only smoke where worker preflight is covered separately, set `ENOCH_SMOKE_SKIP_PREFLIGHT=1`.

The script calls `GET /healthz`, `GET /control/api/v1/overview`, `POST /control/api/preflight`, and `POST /control/dispatch-next` with `dry_run: true`.

## 5. Move to two-machine testing

After local smoke tests pass, follow [deployment](/deployment) to configure a control VM and a worker machine.