Core Principles

Scientific Method

This project is driven by the scientific method. A plan or hypothesis is the origin of any actions taken.

All work follows this process:

1. Hypothesis/Plan: Define what you intend to build and why. State assumptions explicitly.
2. Design: Specify the approach and expected outcomes
3. Experimentation: Execute through deliberate experiments designed to test assumptions
4. Observation: Measure and record results objectively
5. Analysis: Evaluate whether results prove or disprove assumptions
6. Iteration: Refine hypothesis based on experimental findings

Experimentation

Experimentation is the primary methodology for proving or disproving assumptions.

• Every assumption must be tested through experimentation
• Design experiments that can clearly validate or invalidate hypotheses
• Document expected outcomes before running experiments
• Record actual results, even if they contradict expectations
• Failed experiments are valuable — they disprove assumptions and guide better solutions
• Successful experiments validate assumptions and provide confidence to proceed

Before implementing:

• What assumptions are you making?
• How will you test these assumptions?
• What experiments can prove or disprove them?

After experimenting:

• What did the experiment reveal?
• Which assumptions were validated?
• Which assumptions were invalidated?
• What new questions emerged?

Non-Negotiables

• No code without a clear plan
• No changes without understanding purpose and expected impact
• No assumptions without testing

Security Through Isolation

WorkFort’s security model prioritizes hardware-enforced isolation over software-level controls:

• Work VMs execute agent tool calls in sandboxed environments
• Credentials never enter VMs — all credential operations happen in the host (Nexus)
• Communication via vsock eliminates network attack surface between Nexus and VMs
• Firecracker provides hypervisor-level isolation stronger than containers
• Portal/Work VM separation ensures the agent runtime cannot interfere with its own execution environment

The security boundary is the hypervisor, not kernel namespaces or cgroups.

Provider Independence

WorkFort’s architecture maintains independence from specific AI providers:

• MCP (JSON-RPC 2.0) is the tool-calling interface — not provider-specific formats
• Agent runtimes are pluggable — any runtime that speaks MCP works in a portal VM
• Same guest-agent binary works with any AI provider
• No provider SDKs in Work VMs — keeps VMs simple and focused

This separation ensures Work VMs remain generic execution environments while portal VMs and agent runtimes handle provider-specific concerns.

Centralized Control

All operations flow through Nexus for observability and policy enforcement:

• Token usage tracking across all AI conversations
• Cost attribution per user, project, or VM
• Rate limiting and quota management
• Security policies enforced at a single point
• Audit trail for all VM and credential operations

Nexus is the vsock router — all inter-VM communication flows through it. Distributed access to AI APIs would require instrumenting every VM and prevent centralized control features.

Clear Boundaries

The system is organized into distinct components with well-defined responsibilities:

• nexusctl: Thin CLI client, uses HTTP to communicate with Nexus
• nexusd: Control plane, orchestration, vsock routing, state persistence
• guest-agent: Execution interface within Work VMs (MCP server)
• nexus-lib: Shared types, vsock protocol, storage abstractions

This separation:

• Reduces cognitive load during development
• Minimizes AI assistant context (work on CLI without loading daemon code)
• Enables focused testing and debugging
• Allows independent evolution of components