Quickstart

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

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

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

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:

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:

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 to configure a control VM and a worker machine.

Get Started

Core Concepts

Guides

Configuration

Reference

1. Install dependencies and run tests

2. Create a local config

3. Start the API

4. Run smoke tests

5. Move to two-machine testing

​1. Install dependencies and run tests

​2. Create a local config

​3. Start the API

​4. Run smoke tests

​5. Move to two-machine testing

1. Install dependencies and run tests

2. Create a local config

3. Start the API

4. Run smoke tests

5. Move to two-machine testing