The runtime behind nenjo run: bootstrap, event bus, command routing, sessions, and Provider execution.

Worker

The worker is the long-running runtime behind nenjo run. It connects a local machine to the platform, fetches the user's manifest resources, builds a SDK Provider, and handles platform-routed commands.

The worker is not a separate nenjo-worker command in the current implementation. The CLI package builds a nenjo binary, and the worker starts with:

nenjo run

Startup Flow

Step	What happens
Load config	Reads `.nenjo/config.toml`, applies environment overrides, validates `NENJO_API_KEY`, and prepares local directories
Configure local git	If `GITHUB_TOKEN` is present, writes an isolated `.nenjo/gitconfig` and credential helper for worker git operations
Bootstrap	Calls the platform manifest endpoint and caches manifest resources under `.nenjo/manifests`
Enroll crypto identity	Loads or creates worker crypto state and waits until enrollment is active when approval is required
Build Provider	Creates model registry, tool factory, memory backend, external MCP pool, and SDK `Provider`
Connect transport	Uses NATS settings from bootstrap, explicit config, or defaults, then wraps the event bus with secure envelopes
Register and listen	Sends worker registration and heartbeat responses, restores schedules, then routes incoming commands

The worker retries startup and the event loop with exponential backoff. If the backend or event bus is temporarily unavailable, the process keeps trying until it can reconnect or receives a shutdown signal.

Command Capabilities

Worker capabilities are command families, not individual tools. Empty capability config means the worker handles all capability families.

Capability	Commands it covers
`chat`	Chat messages, domain enter/exit, chat cancellation, and local chat session deletion
`task`	Task execution plus execution cancel, pause, and resume
`cron`	Task schedule synchronization and scheduled task execution
`manifest`	Manifest changes and worker account-key updates
`repo`	Project repository sync and unsync
`ping`	Worker health pings

These capabilities are declared when the worker registers and in periodic worker heartbeats.

Command Routing

The event loop receives encrypted platform commands, acknowledges each command, creates a CommandContext, and dispatches handling work into an independent task.

SecureEnvelopeBus
    -> Command
    -> handlers::route_command
    -> CommandContext
    -> Provider / sessions / API / tools
    -> Response

Handlers do not write to the event bus directly. They send typed responses through the response channel, and the bus task routes the response back to the correct user.

Provider Runtime

The harness builds one provider snapshot from the cached manifests. When manifest updates arrive, the harness can rebuild the manifest view and swap the provider without rebuilding the entire process.

Dashboard package, plugin, and skill installs use that same manifest update path. A running worker can receive the updated package resources, rebuild its provider snapshot, and expose newly installed resources without a process restart.

At runtime the provider is responsible for:

Resolving agents and routines by ID or name
Creating model clients from model manifests
Creating tools from platform scopes, MCP assignments, local config, and security policy
Injecting memory tools and prompt memory summaries
Building project, routine, step, domain, and context block prompt variables

Local State

The worker keeps durable local state under .nenjo.

Directory	Purpose
`.nenjo/workspace`	Project working directories, synced repositories, and task worktrees
`.nenjo/state`	Worker memory, sessions, session content, and crypto state
`.nenjo/manifests`	Cached platform resource manifests and bootstrap transport/auth data

This local state lets the worker restore domain sessions, reconcile recoverable chat/task sessions, and restart active schedules after a process restart.

Tools

Agents can receive local tools such as shell, file read/write/edit/delete, git operations, content search, glob search, and generic knowledge tools depending on worker config, scopes, and runtime assembly.

Additional tools are added from:

Agent platform scopes such as projects:read or routines:write
Assigned external MCP servers
Assigned abilities
Memory backend
Enabled worker config sections such as web search, web fetch, HTTP request, browser, and screenshot support

See Scopes for the platform tools each scope adds.

Encryption

The worker uses the secure-envelope event bus for command and response transport. Bootstrap also handles encrypted agent prompt config and context block content when the worker has the needed account content key.

If a command cannot be decoded, the worker returns a generic execution failure response when the envelope contains enough session context to route that response.

Worker

On this page