FAQ

Why are agents data instead of code?

So you can create, clone, and tune agents from the UI without a deploy. A new agent is a new document; a tweak is a field edit. The nexus-agent-runner image never changes when you add a role. This is the core design principle — see Architecture.

Does the runner need to know about every agent type?

No. The pod receives a config payload (system prompt, skills, memory, tools, permissions) and becomes whatever that payload describes. One image runs a planner, implementer, reviewer, or tester.

How is this different from Hermes?

Hermes is great inspiration — named agents/profiles, a durable Kanban board, handoffs, comments, heartbeats, persistent identity, and a skills system that grows over time. But Hermes Kanban is local/single-host with SQLite. Nexus generalizes the idea to MongoDB + Kubernetes + multi-agent isolation, with external-board compatibility (Plane first).

Why MongoDB and not Postgres?

MongoDB is used as the dynamic configuration store: agents, skills, memory, and runs are documents whose shapes evolve. Text search + tags is enough for MVP memory retrieval; vector search (Atlas Vector Search or Qdrant) comes later.

Why NATS JetStream for events?

Durable, replayable, stream-based messaging with crash recovery — important for long-running autonomous agents. Events like nexus.agent.run.completed survive restarts and can be replayed.

Can agents write to memory freely?

Not at the start. The first flow is: agent proposes memory → Nexus stores it as pending → a human approves it in the UI → it becomes active. Later you can auto-approve low-risk memory. This prevents agents from polluting shared context. See Memory.

What happens when an agent keeps failing?

It gets quarantined: if success rate drops below 50% over the last 10 runs, or after 3 consecutive critical failures, the agent's status flips to quarantined and no new tasks are assigned. See Lifecycle.

Is Plane required?

No. Nexus has its own internal board and is the authority. Plane (and later Jira) is only a projection through the BoardProvider trait. You can run with the internal board only.

What's the smallest thing I can run?

The MVP: Nexus Core + MongoDB + the UI (Agents/Skills/Board/Runs) + a Plane adapter + the Telegram gateway + a Kubernetes job launcher + one generic agent-runner container. See Roadmap.

What does the first Telegram command look like?

/nexus create goal "Build authentication system for my app"

Nexus replies: Goal created. Drafted 8 tasks. Waiting for approval in Nexus UI. You approve the plan in the UI, Plane tasks are created, and agents are scheduled as Kubernetes jobs.