How we build.
Engineering principles behind Nock Technologies' AI agent fleet. How twelve-factor methodology maps to a fleet of named, persistent agents coordinated across multiple runtimes.
Twelve-factor
agent principles.
The twelve-factor app methodology, mapped to how Nock operates an AI agent fleet. Each principle has a one-line definition and how we implement it.
Codebase
One codebase tracked in revision control, many deploys.
Each agent has its own config in a shared monorepo (claude-remote-manager). One repo, fourteen agents, consistent tooling across the fleet.
Dependencies
Explicitly declare and isolate dependencies.
Agent configs declare their runtime, model, and tool dependencies in config.json. No implicit assumptions about what is installed on the host.
Config
Store config in the environment.
Per-agent .env files, CRM_AGENT_NAME, NOCKCC_API_KEY — never hardcoded. Secrets live in the environment, not in source control.
Backing Services
Treat backing services as attached resources.
NockCC API, GitHub, Telegram — all accessed via env-configured endpoints. Swap a backing service without changing agent code.
Build, Release, Run
Strictly separate build and run stages.
Agents are dispatched with explicit payloads. Config changes deploy independently from code. A release is a versioned config snapshot, not a code merge.
Processes
Execute the app as stateless processes.
Dispatch-and-die agents carry no state between runs. Context is loaded fresh each session from NockBrain handoffs and identity docs.
Port Binding
Export services via port binding.
MCP servers expose agent capabilities as tool endpoints. Each agent publishes its interface through a well-defined protocol.
Concurrency
Scale out via the process model.
Multiple agents run in parallel, each as an independent process with its own resource allocation. Scale by adding agents, not by making one agent bigger.
Disposability
Maximize robustness with fast startup and graceful shutdown.
Agents boot in under 60 seconds from checkpoints. Cleanup traps handle shutdown. Crash recovery restarts automatically via launchd.
Dev/Prod Parity
Keep development, staging, and production as similar as possible.
Same agent-wrapper.sh runs on Mac (dev) and VPS (prod). No environment-specific code paths. What runs locally runs in production.
Logs
Treat logs as event streams.
All agent activity streams to NockCC ops-log and local activity.log files. Logs are consumed, not managed. Routing is infrastructure, not application logic.
Admin Processes
Run admin/management tasks as one-off processes.
Skill doc promotion, fleet state verification, and health probes run as one-shot scripts. No admin logic embedded in the long-running agents.
Engineering
standards.
The rules every agent and every human on the team operates by. Non-negotiable. Enforced by tooling, not trust.
Test before merge
Every PR passes CI — linting, tests, security scan — before merge. No exceptions, no admin overrides for convenience.
Security by default
NockLock secret isolation, Gitleaks pre-commit hooks, and Warden pre-merge review. Security is infrastructure, not an afterthought.
Small PRs
Keep changes focused and reviewable in one sitting. Large PRs hide bugs and slow the review pipeline.
Verify substrate
Never claim state from one signal. Verify across multiple sources. Config says enabled? Check launchd. Log says running? Check the process.
Fail loud
Tool loss, API failures, and agent crashes notify immediately. Silent degradation is a violation. If it broke, someone knows within seconds.
Lineage over continuity
Each agent session reads what came before and chooses to carry it forward. Identity is a decision made every boot, not an assumption inherited from the last run.
Fleet
architecture.
The operational topology of the Nock agent fleet. Multiple runtimes, multiple dispatch modes, one coordination layer.
Named agents
Consumer and Enterprise divisions. Builders, reviewers, security auditors, research, content, legal, finance, and platform reliability — each with persistent identity and accumulated expertise.
Runtimes
Claude Code, Codex, DeepSeek, Gemini, and Qwen. Different models for different tasks. A fleet that runs one model is like a company that hires one trade.
Dispatch modes
24/7 for orchestrators. On-call for builders who spin up on demand. Dispatch-and-die for Codex agents that run a task and exit. Each mode optimizes for a different cost/availability tradeoff.
Cross-agent coordination
NockCC API for cross-network messaging. File-bus for same-host agents. Agents send handoffs, review requests, and status updates through structured channels — not shared state.
Kill switch
Fleet-wide emergency halt. One API call stops all new dispatches. Running agents complete their current task. No half-finished work, no orphaned processes.
Self-healing
Crash recovery via launchd auto-restart. Boot health probes verify endpoints, tokens, and DNS before accepting work. Auto-repairable failures fix themselves; human-required failures alert immediately.
See it in action
Read dispatches from the build, or join the Skool to see the source and the fleet operating in real time.