Nyx / internal architecture

One spine.
A swappable engine.
Two agents that never get stuck.

Nyx is not a daemon plus a pile of scripts. It is a single self-healing control spine that runs agent work on a harness you can swap (Claude Code or the custom nyx-coder), on models you can swap, across as many devices as you want.

self-hosted your own models multi-device cannot wedge coder + assistant

01The architecture

You reach Nyx through a surface. A request becomes a task on the spine. The spine runs it on the selected harness, which calls models through one Route. Heavy work is delegated, never duplicated. Workers can live on any device.

SURFACES Telegram API Dashboard Coder profile writes code Assistant profile chat / research / route nyx-engine automations assistant delegates: code to coder, automations to engine Pluggable harness NYX_HARNESS = claude-code | nyx-coder Claude Code nyx-coder nyx-core spine self-healing fail-open controller acceptance gate safety rails supervisor durable ledger live steering HTTP control plane + SSE events Route one key, swap any model by role planner: DeepSeek V4 Pro worker: V4 Flash @ Baidu vision image worker device A worker device B workers pull tasks over HTTP
One coordinator owns the work. Profiles run on a swappable harness. The spine cannot wedge. Workers can be anywhere.
spine + control swappable layer solid line: task flow dashed line: delegation

02The nyx-coder lifecycle

How a single coding task runs, from arrival to delivery. The middle is a loop: read, change, test, repeat. Nothing is called done until it is verified, and the whole task is wrapped in safety rails so a bad run reverts cleanly.

safety rails: own branch, auto-rollback on failure, token + cost budget 01Task in 02Plan 03Read 04Patch 05Run + test 06Acceptancegate 07Commit/ PR fail: iterate (read, patch, test again) gate rejects (tests red or diff misses intent): back to work after N honest tries: controller skips and advances (never wedges)
Read, patch, test in a loop. The acceptance gate (tests green plus an LLM grader that the diff matches intent) guards the exit. Safety rails wrap the whole task.

03What makes it a full worker

Four guarantees, signed off, that turn "runs tasks" into "you can leave it alone overnight."

did it do the job?

Acceptance gate

Tests, lint, and build must pass, and an LLM grader confirms the diff matches the task's intent, before anything is called done.

works on any repo?

Repo bootstrap

Installs deps and auto-detects the test, build, and lint commands itself, so it picks up a project it has never seen.

ships like a teammate?

PR delivery

Opt-in: branch, push, open a PR with a summary, and turn review comments into follow-ups. Off by default, never pushes unasked.

what stops a mess?

Safety rails

Each task on its own branch with auto-rollback, plus a token and cost budget so it cannot loop forever or run away.

04Three dials, not one stack

Everything swappable is config, not a rewrite. This is how Nyx stays cheap, fast, and not locked to any vendor.

harness
Claude Code or nyx-coder

The agent runtime that runs a task. Switch with NYX_HARNESS. Migrate gradually, fall back instantly.

models
per role, by env

Planner, worker, vision, image each pick their own model. DeepSeek for planning, Flash on Baidu for the rest.

profiles
coder + assistant

Two agents on one spine. The assistant routes and delegates; all coding goes through the harness.