An AI agent is easy to demo when it only returns text. It becomes an engineering problem when it must remember a task, select context, choose a model, call tools, respect permissions, and prove what happened. Nerva is an upcoming local-first desktop agent designed around that complete control loop.
The planned architecture is intentionally split into small responsibilities. The model should not own permissions, the tool should not decide policy, and a successful command should not be confused with a verified result.
The short answer
Nerva’s control spine is planned as:
UI -> Task Manager -> Context Manager -> Model Router
-> Agent Loop
-> Tool Gateway
-> Rust Permission Engine
-> sandboxed tool
-> verificationThe UI explains the task and shows state. The task manager tracks progress. The context manager selects data. The model router chooses a local model or an approved provider. The agent loop decides what step to propose next. The gateway turns approved proposals into narrow tool calls. The permission engine decides whether those calls are allowed.
Why one giant agent service is risky
A single service that reads files, chooses a model, runs commands, and writes results can be convenient to build. It is difficult to inspect when something goes wrong. A model response might accidentally become a shell command, and there may be no clear place to enforce a boundary.
Separating the components creates useful questions:
- Which context was selected?
- Why was this model chosen?
- Which tool call was proposed?
- What permission allowed it?
- What evidence proved completion?
These questions are important for Nerva because a developer needs to trust the workflow, not just the final prose.
A request moving through the system
Imagine asking Nerva to explain a failing TypeScript test. The task manager records the request. The context manager selects the test, implementation, and relevant error lines. The router chooses a local model if the context fits. The model proposes an explanation or a patch. No file changes happen until the permission engine approves a write.
After an approved edit, the tool gateway runs the selected test in the workspace. The verification step reports whether it passed, failed, or was not run. A green-looking answer without that result is not completion.
The architecture is a product promise
This design is not only an implementation diagram. It communicates how Nerva should behave: local context first, provider choice visible, actions narrow, permissions independent, and results verifiable. Those boundaries are what make a desktop agent feel like a controlled workbench instead of an invisible automation script.
The useful design question
The useful question here is not whether an AI agent can produce an impressive demo. It is whether the workflow stays understandable when the task is incomplete, the repository is messy, or the model is wrong. For this part of Nerva, the focus is the boundary between proposing work and executing it. That means each state should have a visible owner, a small input, and a result that another part of the system can inspect.
A concrete scenario
Consider a failed TypeScript test in a queue worker. A good Nerva run would first state the scope, identify the files or operation it needs, and show the next proposed step. It would keep the original request separate from model-generated instructions. If an action needs approval, the user would see what will happen before it happens. Afterward, the task history would retain the command, result, and verification status instead of reducing everything to a confident paragraph.
This approach also makes a failure useful. A denied permission, unavailable provider, missing package, or changed file is information about the task state. Nerva should preserve it and explain the smallest recovery option. It should not silently broaden the request, retry a side effect, or claim completion because a model supplied plausible-looking text.
What I would test first
For an early implementation, I would test three paths: a normal successful run, a denied action, and an interrupted run resumed after the workspace changes. The key test is which component owns each decision before adding another service. In each path, the interface should make clear what Nerva knows, what it proposed, what actually ran, and what remains unverified.
Useful acceptance checks include:
- the user can inspect the selected context before model execution;
- sensitive paths and credentials are excluded or redacted;
- every side effect has a narrow permission decision;
- failures remain attached to the step that caused them;
- a final answer links to evidence instead of implying that unrun work succeeded.
Nerva is still an upcoming project, so these are design and implementation goals rather than claims that a finished product already provides them. That distinction matters: a trustworthy agent should earn confidence through observable behavior, not through a feature list.
The boundary that matters in production
A useful implementation boundary is to make every handoff typed: a task has scope, context has provenance, a model response has a proposal, a tool call has arguments, and verification has evidence. This makes logs readable and lets tests exercise the control spine without calling a real model. It also gives the UI stable states instead of parsing arbitrary prose.
For the first vertical slice, keep the boundary small enough to explain in a code review. Define the input, the decision, the side effect, and the evidence for completion. Add a test for the denied path as well as the successful path. This is where a local-first design earns trust: the user can inspect the context and history on the device, see when a provider is involved, and stop before an action crosses the permission boundary. The design should remain honest about its limits. Nerva is planned software, not a claim that every workflow can be made safe automatically. A clear “cannot verify” state is more useful than a polished but unsupported success message.
The design is informed by the boundaries I have had to think through in CryptoEx and SentinelFi: backend work becomes easier to review when context, permissions, side effects, and verification are explicit.
Discussion
What would you try, change, or challenge after reading this guide? Specific results and errors help the next reader.
Comments will load as you reach this section.