Worker Overview

A worker is a process that connects to the Molf server over WebSocket, registers its tools and skills, and executes tool calls dispatched by the server on the local machine.

What the Worker Does

The worker handles all local execution on behalf of the LLM. It runs shell commands, reads and writes files, searches codebases, and manages skills and MCP connections. Workers connect to the server and wait for instructions -- they never communicate directly with clients.

Key responsibilities:

• Execute tool calls (shell commands, file I/O, search) dispatched by the server
• Load and report skills and agent definitions from the working directory
• Handle file uploads and filesystem read requests from clients
• Reconnect automatically after disconnections
• Watch for file changes and hot-reload skills, agents, and project instructions

Starting a Worker

pnpm dev:worker -- --name my-worker

On first run, the worker will prompt you to trust the server's TLS certificate (TOFU) and walk you through a pairing flow to obtain an API key. On subsequent runs, saved credentials are used automatically.

CLI Flags

Flag	Short	Env Var	Default	Description
--name	-n	--	(required)	Worker name
--workdir	-w	--	Current directory	Working directory for tool execution
--server-url	-s	MOLF_SERVER_URL	wss://127.0.0.1:7600	Server WebSocket URL
--token	-t	MOLF_TOKEN	--	Auth token or API key
--tls-ca	--	MOLF_TLS_CA	--	Path to trusted CA certificate PEM file

The default server URL uses wss:// (TLS enabled). If the server has TLS disabled via --no-tls, use ws:// instead.

Example -- point a worker at a specific project:

pnpm dev:worker -- \
  --name my-project \
  --workdir ~/projects/my-app \
  --server-url wss://192.168.1.10:7600

Startup Flow

The worker performs these steps on startup, in order:

1. Parse CLI arguments
2. Get or create a persistent worker UUID from .molf/worker.json
3. Resolve TLS trust (CA certificate > saved pinned cert > TOFU interactive prompt)
4. Resolve auth token (CLI/env > ~/.molf/credentials.json > auto-pair flow)
5. Configure LogTape logging (console + optional file sink)
6. Load built-in tools, skills, agents, and the root instruction document
7. Connect to the server and register via worker.register
8. Initialize SyncCoordinator for state synchronization
9. Load worker plugins from the server's plugin list
10. Start StateWatcher for filesystem hot-reload
11. Dispatch the worker_start hook

Worker Identity

Each worker has a persistent UUID stored at {workdir}/.molf/worker.json:

{ "workerId": "550e8400-e29b-41d4-a716-446655440000" }

• Created automatically on first run
• Reused on subsequent runs from the same working directory
• Regenerated if the file is corrupt
• Sessions are bound to a worker by its UUID, so they persist across restarts

TLS and Pairing

First-Run TLS Trust

When connecting to a server with TLS (the default), the worker probes the server certificate and prompts for interactive approval:

Server TLS fingerprint: SHA256:abc123...
Trust this server? [Y/n]

The approved certificate is saved to ~/.molf/known_certs/ and used for all future connections (pinned trust).

Pairing Flow

If no token is provided via --token or MOLF_TOKEN, the worker runs an automatic pairing flow:

1. Probe and trust the server certificate (TOFU)
2. Connect to the server without auth
3. Prompt the user for a 6-digit pairing code (generated by an authenticated client)
4. Exchange the code for an API key (yk_ prefix)
5. Save the API key to ~/.molf/credentials.json

On subsequent runs, the saved API key is used automatically.

CA Certificates

For production deployments with proper CA-signed certificates, use --tls-ca or MOLF_TLS_CA to provide a CA certificate file instead of TOFU.

Connection and Reconnection

The worker connects to the server over WebSocket with TLS. After connecting, it registers itself with worker.register, reporting its tools, skills, agents, and metadata. It then subscribes to three server streams:

• worker.onToolCall -- receive tool calls dispatched by the LLM
• worker.onUpload -- receive file uploads from clients
• worker.onFsRead -- receive filesystem read requests (max 30 MB per file)

Automatic Reconnection

If the connection drops, the worker reconnects automatically with exponential backoff:

Parameter	Value
Initial delay	1 second
Maximum delay	30 seconds
Multiplier	2x
Jitter	+/-25%
Connection timeout	5 seconds

Tool result delivery retries up to 3 times with a 1-second delay if the initial submission fails.

State Watching and Hot-Reload

The worker watches the filesystem for changes and automatically syncs updates to the server. No restart is required.

Watched Paths

Path	Effect
.agents/skills/**/SKILL.md (or .claude/skills/)	Skills reloaded and synced to server
.agents/agents/*.md (or .claude/agents/)	Agents reloaded and synced to server
AGENTS.md (or CLAUDE.md)	Project instructions updated in server metadata

How It Works

• Uses chokidar for cross-platform file watching
• 500 ms write stabilization debounce
• All change handlers are serialized through a queue to prevent concurrent syncState races
• If the skill directory does not exist yet, the worker polls every 5 seconds until it appears

Changes are synced to the server via the SyncCoordinator, which reads the canonical state at send time to ensure freshness. The server's ConnectionRegistry replaces the worker's full state snapshot, making changes visible to the LLM on the next prompt.

Worker Plugins

The server sends a list of plugin specifiers to the worker on registration. The worker imports each plugin and calls its descriptor.worker(api) function.

The worker plugin API provides:

• addTool / removeTool -- register or deregister tools
• syncState -- trigger a state sync to the server
• workdir -- the worker's working directory
• log -- structured logger
• hookRegistry -- register hooks for tool execution lifecycle

The default worker plugin is @molf-ai/plugin-mcp, which loads external MCP tool servers. See MCP Integration for details.

For the full plugin API reference, see Plugins.

Workdir Layout

{workdir}/
  AGENTS.md                        # Root instruction document (or CLAUDE.md)
  .mcp.json                        # MCP server configuration (optional)
  .agents/
    skills/
      deploy/
        SKILL.md                   # Skill definition
      review/
        SKILL.md
    agents/
      explore.md                   # Custom agent definition
      reviewer.md
  .molf/
    worker.json                    # Persistent worker UUID
    logs/
      worker.log                   # JSONL rotating log (5 MB x 5 files)
    uploads/                       # Uploaded files
    tool-output/                   # Full output of truncated tool results

Logging

The worker logs to both the console and a rotating file.

Sink	Location	Format
Console	stdout	Pretty-formatted
File	{workdir}/.molf/logs/worker.log	JSONL, 5 MB max, 5 files

Control logging via environment variables:

Variable	Default	Description
MOLF_LOG_LEVEL	info	debug, info, warning, error
MOLF_LOG_FILE	Enabled	Set to none to disable file logging

See Logging for the full reference.

See Also

• Built-in Tools -- reference for all six worker tools
• Skills -- SKILL.md format, AGENTS.md, nested instructions
• MCP Integration -- connect external MCP servers
• Tool Approval -- per-worker approval rules (server-side)
• Subagents -- custom agent definitions loaded from the workdir
• Configuration -- full CLI flags and env var reference
• Plugins -- plugin system and worker plugin API