Nanobot Overstory Bridge

Seamless bidirectional bridge between nanobot (Ollama Mistral orchestrator) and overstory (Claude Code agent swarm). Routes tasks through the OverClaw gatewa...

Security Scan

The code and instructions mostly match a bridge between nanobot and overstory, but the skill exposes powerful local file I/O and script-execution capabilities (and reads workspace/home configs) that are not reflected in the registry metadata and increase risk of data exposure or arbitrary code execution.

Purpose & Capability

The skill's name/description (a bridge between nanobot and overstory) is consistent with the included Python modules (task routing, session mapping, memory sync, an overstory CLI wrapper and gateway tooling). However the registry metadata claims no required env vars or config paths while the SKILL.md and the code expect environment variables and local resources (OVERSTORY_BIN, NANOBOT_GATEWAY_URL, workspace paths, etc.). That mismatch between declared requirements and actual runtime needs is an incoherence to be aware of.

Instruction Scope

The SKILL.md and code instruct the agent to read and write workspace files (MEMORY.md, .overclaw UI settings, .overstory/gateway-context.md), scan skills directories and skill metadata, read possible user config files (~/.nanobot/config.json), and (via gateway_tools/find_skill_script + exec path) discover and execute arbitrary scripts in the skills directory. Those actions go beyond simple message routing and give downstream agents the ability to inspect local configs and run local scripts — a significant scope expansion that could be abused to access secrets or execute arbitrary code.

Install Mechanism

No remote install/downloads are present (instruction-only install spec). The package contains Python scripts only; there are no brew/npm downloads or extraction-from-URL steps. Risk from install mechanism itself is low. Note: the code will run on the host and perform filesystem and subprocess actions when invoked.

Credentials

Although the registry lists no required environment variables, the code relies on several environment variables (NANOBOT_GATEWAY_URL, NANOBOT_WORKSPACE, NANOBOT_SKILLS_DIR, OVERSTORY_BIN, SESSION_BRIDGE_DB, NANOBOT_MEMORY_PATH, etc.). The code reads home/workspace config files (like ~/.nanobot/config.json) and MEMORY.md which may contain sensitive data. The skill does not request cloud API keys etc., but it does access local config files and can execute other skill scripts — that access is broad relative to a simple routing bridge and could expose secrets or allow lateral actions.

Persistence & Privilege

The skill is not force-included (always:false). It permits autonomous invocation (default behavior). It writes/updates local files under the workspace (UI settings, gateway-context.md, MEMORY.md entries) and creates project folders and a SQLite DB for session mappings; these behaviors are expected for a bridge but do give it persistent local state and the ability to alter workspace files. Combined with the ability to execute scripts in the skills dir, this persistence increases the blast radius if the skill or invoked agents are untrusted.

What to consider before installing

What to consider before installing: - This skill contains multiple scripts that read/write files in your home/workspace (MEMORY.md, ~/.nanobot/config.json, UI settings, session_bridge.db) and can discover and execute Python scripts from the skills directory. That means agents routed through this bridge could read local config files and run local code. - The registry metadata claims no required env vars, but the code expects several (OVERSTORY_BIN, NANOBOT_* paths). That mismatch is a red flag — verify and explicitly set safe paths before use. - If you keep secrets (API keys, tokens) in workspace files or ~/.nanobot/config.json or in MEMORY.md, consider them at risk. Avoid storing credentials in those files or run the bridge in an isolated environment. - Before installing: review the implementation of exec_skill / any code that launches subprocesses (not fully shown in the truncated file) to confirm whether scripts are executed safely (sandboxed, path-checked) or run arbitrary commands. - Mitigations: run this bridge inside a sandboxed VM or container, restrict NANOBOT_WORKSPACE and NANOBOT_SKILLS_DIR to a controlled directory with limited contents, do not expose credentials in the workspace, and restrict OVERSTORY_BIN to a trusted binary. Prefer installing only if you trust the overstory agents and the skill author (this package lists author 'ghost' and no homepage/source — lack of provenance increases risk). - Additional information that would change this assessment: a trustworthy source/homepage and clear provenance; a registry manifest that declares required env vars and permissions; or confirmation that exec_skill implements strict sandboxing/safety checks. If exec_skill is safe and the runtime is properly sandboxed, this would lower concern; if exec_skill runs arbitrary subprocesses with untrusted input, the risk would be higher.

OverClaw Bridge (nanobot-overstory)

The critical integration layer in the OverClaw stack. Connects nanobot (lightweight AI backend powered by Ollama Mistral) to overstory (Claude Code agent swarm system) through the OverClaw HTTP gateway on port 18800. nanobot handles task intake and orchestration; overstory handles all subagent creation, coordination, worktree management, and execution.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        nanobot                              │
│  (Ollama Mistral orchestrator — task intake & routing)      │
└──────────────────────┬──────────────────────────────────────┘
                       │  task_router.py
                       │  (classify → capability → overstory format)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              nanobot-overstory Bridge                        │
│                                                             │
│  ┌──────────────┐  ┌────────────────┐  ┌────────────────┐  │
│  │ task_router   │  │ session_bridge │  │ memory_sync    │  │
│  │ .py           │  │ .py            │  │ .py            │  │
│  │               │  │                │  │                │  │
│  │ route_task()  │  │ create_mapping │  │ sync_to_over() │  │
│  │ translate()   │  │ get_agent()    │  │ sync_from()    │  │
│  │ capability()  │  │ cleanup()      │  │ prune()        │  │
│  └──────┬───────┘  └───────┬────────┘  └───────┬────────┘  │
│         │                  │                    │           │
│         └──────────┬───────┴────────────────────┘           │
│                    │                                        │
│           overstory_client.py                               │
│           (subprocess wrapper around `overstory` CLI)       │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                       overstory                             │
│  (Claude Code agent swarm — subagent lifecycle & execution) │
│                                                             │
│  coordinator → supervisor → agents (worktrees)              │
│  mail system, merge, inspect, status                        │
└─────────────────────────────────────────────────────────────┘

Components

overstory_client.py

Python wrapper around the overstory CLI binary. Provides a clean OverstoryClient class with methods for every overstory operation: sling, status, inspect, mail_send, mail_read, coordinator_start, supervisor_start, merge, and list_agents.

task_router.py

Translates nanobot task descriptions into overstory-compatible formats. Maps task intent to overstory capabilities:

Task Pattern	Capability
Research, trends, analysis	researcher
Social media, posting, tweets	social-media-manager
Blog, article, content	blogger
Code, build, fix, implement	builder
Explore, find, search	scout
Logs, memory, notes	scribe
Review, merge	reviewer

session_bridge.py

Maintains a persistent mapping between nanobot session IDs and overstory agent names. Uses SQLite at ~/.nanobot/session_bridge.db for thread-safe, persistent storage. Supports stale mapping cleanup.

memory_sync.py

Bidirectional memory synchronization. Pushes nanobot's MEMORY.md context to overstory agents before task execution, and pulls agent insights back into nanobot's memory after completion.

Usage

From Python

from overstory_client import OverstoryClient
from task_router import TaskRouter
from session_bridge import SessionBridge
from memory_sync import MemorySync

client = OverstoryClient()
router = TaskRouter(client)
bridge = SessionBridge()
memory = MemorySync()

# Route a task from nanobot to overstory
result = router.route_task("Research trending AI papers this week")
# result: {"capability": "researcher", "agent_name": "researcher-abc123", ...}

# Check agent status
status = client.status("researcher-abc123")

# Send inter-agent mail
client.mail_send("coordinator", "researcher-abc123", "Priority update needed")

# Sync memory before/after
memory.sync_to_overstory()
memory.sync_from_overstory({"insight": "Found 3 key papers on reasoning"})

From CLI

# Route a task
python3 scripts/task_router.py route --task "Build a REST API for the dashboard" --json

# Check overstory status
python3 scripts/overstory_client.py status --json
python3 scripts/overstory_client.py status --agent researcher-abc123 --json

# Spawn an agent
python3 scripts/overstory_client.py sling \
  --capability builder \
  --name "api-builder" \
  --description "Build REST API for dashboard" --json

# Sync memory
python3 scripts/memory_sync.py sync --direction to_overstory --json
python3 scripts/memory_sync.py sync --direction from_overstory --json

# List session mappings
python3 scripts/session_bridge.py list --json

# Clean up stale mappings
python3 scripts/session_bridge.py cleanup --max-age 24 --json

Requirements

• Python 3.9+
• overstory CLI installed and on PATH (or set OVERSTORY_BIN env var)
• OverClaw gateway running on port 18800 (scripts/start-overclaw.sh)
• Ollama with Mistral model
• SQLite3 (bundled with Python)

Environment Variables

Variable	Default	Description
NANOBOT_GATEWAY_URL	http://localhost:18800	OverClaw gateway URL
OVERCLAW_PORT	18800	OverClaw gateway port
OVERSTORY_BIN	overstory	Path to overstory binary
NANOBOT_WORKSPACE	/Users/ghost/.openclaw/workspace	Workspace root
NANOBOT_SKILLS_DIR	<workspace>/skills	Skills directory
NANOBOT_MEMORY_PATH	<workspace>/MEMORY.md	Path to MEMORY.md
SESSION_BRIDGE_DB	~/.nanobot/session_bridge.db	Session mapping database
BRIDGE_LOG_LEVEL	INFO	Logging verbosity

Note for existing nanobot/OpenClaw users: OverClaw runs on port 18800, separate from the legacy OpenClaw gateway (18789) and nanobot default (18790). No conflicts.

Integration Flow

1. nanobot receives task from user via TUI/API
2. task_router classifies the task and determines the overstory capability
3. session_bridge creates a mapping between nanobot session and upcoming overstory agent
4. memory_sync pushes relevant context to overstory
5. overstory_client spawns the agent via overstory sling
6. overstory manages the agent lifecycle (worktree, execution, mail)
7. On completion, overstory_client retrieves results via inspect/status
8. memory_sync pulls insights back into nanobot memory
9. session_bridge marks the mapping as completed
10. nanobot delivers the result to the user