Deployment

The reference deployment splits Enoch across two machines:

Control VM — runs the FastAPI control plane, the professional operator dashboard, bounded read models, publication automation APIs, timers, and optional corpus/export tooling.
Worker machine — runs the worker-gate API used by Codex jobs, tracks processes and telemetry, and stores project workspaces and evidence.

You can also run both roles on one host for development. For the canonical current reference host paths, storage authority, worker gate, paper gate, and compatibility boundaries, see current runtime snapshot.

Prerequisites

Control VM:

Linux with systemd
Python 3.11+
uv
git
network access to the worker API

Worker machine:

Linux with systemd or an equivalent process manager
Python 3.11+
uv
git
the Codex stack used by your dispatch script
NVIDIA telemetry libraries if you want GPU visibility

Install the control plane

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

The helper can copy the checkout into /opt, create config and state directories, install dependencies, and write systemd units when run as root:

sudo scripts/install-control-plane.sh \
  --prefix /opt/enoch-control-plane \
  --config-dir /etc/enoch-control-plane \
  --state-dir /var/lib/enoch-control-plane \
  --user enoch

The script defaults to those paths when you omit the flags. Edit /etc/enoch-control-plane/config.json before enabling the service. Replace every placeholder token and URL.

Configure required secrets

Generate distinct values for control_api_bearer_token and worker_wake_gate_bearer_token:

python3 -c "import secrets; print(secrets.token_urlsafe(48))"

When completion_callback_url targets the control plane at /control/api/worker-callback, set worker-side completion_callback_token to the same value as control_api_bearer_token. Preflight checks that the worker callback token matches the control plane bearer fingerprint. Keep completion_callback_token as a separate secret only when the callback URL points at an external webhook that is not the control plane. Never commit live config files, legacy Notion tokens, Pushover credentials, provider API keys, private hostnames, or production logs.

Run the control service

sudo systemctl daemon-reload
sudo systemctl enable --now enoch-control-plane.service
sudo systemctl status enoch-control-plane.service
curl -fsS http://127.0.0.1:8787/healthz

Open the dashboard and authenticate with the configured inbound token:

http://<control-vm>:8787/control/dashboard

/dashboard redirects to the same shell. The dashboard uses bounded /control/api/v1/* read models by default, so the first screen stays focused on operator questions rather than raw JSON.

Configure the worker

On the worker host:

git clone https://github.com/alias8818/enoch-agentic-research-system.git
cd enoch-agentic-research-system
scripts/install-worker.sh

The worker can run the same app with a worker-focused config:

ENOCH_CONFIG=$HOME/.config/enoch-worker/config.json \
  uv run uvicorn enoch_control_plane.app:app --host 0.0.0.0 --port 8787

curl -fsS -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8787/control/health

Optional timers

scripts/install-control-plane.sh always installs enoch-source-lineage-check.timer and recommends enabling it as a provenance guard. It also installs enoch-queue-alert-check.timer. Additional units are opt-in at install time:

Timer	Install flag	Notes
`enoch-source-lineage-check.timer`	installed by default	Enable after install; validates source-lineage reports
`enoch-queue-alert-check.timer`	installed by default	Optional Pushover alerts and queue pump when configured
`enoch-paper-draft-next.timer`	`ENOCH_INSTALL_PAPER_DRAFT_NEXT_UNITS=1`	Legacy unattended paper drafting; keep disabled unless intentionally tested
`enoch-research-autopilot.timer`	`ENOCH_INSTALL_RESEARCH_AUTOPILOT_UNITS=1`	Bounded Research Facility autopilot
`enoch-notion-sync.timer`	`ENOCH_INSTALL_LEGACY_NOTION_UNITS=1`	Legacy Notion compatibility only

The repo also ships enoch-corpus-import-autopilot.timer, but the install script does not enable it automatically. Copy and enable that unit separately when you have tested corpus import automation. Enable only the timers you have configured and tested.

Smoke-test before live dispatch

export ENOCH_BASE_URL=http://<control-vm>:8787
export ENOCH_CONTROL_TOKEN=<control_api_bearer_token>
scripts/smoke-test-local.sh

The smoke script uses /control/api/v1/overview by default. That keeps the test bounded and aligned with the operator dashboard. If you need the broader compatibility payload, set ENOCH_STATUS_ENDPOINT=/control/api/status explicitly. Then test worker preflight:

curl -fsS -H "Authorization: Bearer $ENOCH_CONTROL_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"wake_gate_url":"http://<worker>:8787","bearer_token":"<worker-token>","require_paused":false,"strict":false}' \
  "$ENOCH_BASE_URL/control/api/preflight" | python3 -m json.tool

Use dry-run dispatch first:

curl -fsS -H "Authorization: Bearer $ENOCH_CONTROL_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"dry_run":true,"requested_by":"operator-smoke-test"}' \
  "$ENOCH_BASE_URL/control/dispatch-next" | python3 -m json.tool

Paper artifact workflow

Paper generation is optional and depends on evidence and paper rows. The default paper_writer_provider is deterministic. The code also supports an OpenAI-compatible synthetic.new provider with paper_writer_base_url, paper_writer_model, and paper_writer_api_key settings. Do not publish generated artifacts until corpus import, packaging/provenance checks, and strict claim/evidence audit status are explicit. Human review or replication may still be needed before treating claims as reliable science, but paper finalization itself is automated. The public paper counts should stay gate-aware:

paper_pipeline.write_needed is actionable positive work only.
paper_pipeline.raw_completed_no_paper_candidates is informational/debug only.
paper_pipeline.publish_ready means finalized drafts still missing corpus import.

Review the dispatch flow

Every live dispatch request passes through the following checks in order. Understanding this sequence helps you diagnose failures at each stage:

No conflicting active GPU lane exists.
A queue item exists.
Live dispatch is enabled (live_dispatch_enabled must be true in config).
The control plane is not paused and maintenance mode is not active.
Worker preflight is healthy.
The dispatch script launches the agent run.
The worker gate tracks process and telemetry truth.
The completion callback or status update is emitted only after the gate is satisfied.

Always use dry-run dispatch first when testing a new deployment. It exercises the core dispatch guards without launching a real agent run. Worker preflight is only performed during live dispatch, not dry-run.

What is not included

This repository does not include live secrets, private production config, generated paper corpus artifacts, old workflow-tool exports, private run state databases, or production logs. Those are intentionally excluded. Use the example config and this guide to recreate a clean deployment from scratch.

Get Started

Core Concepts

Guides

Configuration

Reference

Deployment

Deployment

Prerequisites

Install the control plane

Configure required secrets

Run the control service

Configure the worker

Optional timers

Smoke-test before live dispatch

Paper artifact workflow

Review the dispatch flow

What is not included

​Deployment

​Prerequisites

​Install the control plane

​Configure required secrets

​Run the control service

​Configure the worker

​Optional timers

​Smoke-test before live dispatch

​Paper artifact workflow

​Review the dispatch flow

​What is not included

Deployment

Prerequisites

Install the control plane

Configure required secrets

Run the control service

Configure the worker

Optional timers

Smoke-test before live dispatch

Paper artifact workflow

Review the dispatch flow

What is not included