Skip to main content

​
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, completion_callback_token, and worker_wake_gate_bearer_token: 
python3 -c "import secrets; print(secrets.token_urlsafe(48))"
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

The repo includes systemd units for optional workflows:
  • enoch-queue-alert-check.timer — periodically checks queue health and can send Pushover alerts when configured.
  • enoch-notion-sync.timer — legacy compatibility only; syncs Notion intake/projection data when those environment variables are configured.
  • enoch-paper-draft-next.timer — legacy unattended paper drafting path. Keep disabled unless you intentionally run a controlled, bounded drain and have verified the decision gate.
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:
  1. No conflicting active GPU lane exists.
  2. A queue item exists.
  3. Live dispatch is enabled (live_dispatch_enabled must be true in config).
  4. The control plane is not paused and maintenance mode is not active.
  5. Worker preflight is healthy.
  6. The dispatch script launches the agent run.
  7. The worker gate tracks process and telemetry truth.
  8. 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.