eeebot

This repository is the canonical eeebot project for the eeepc self-improving runtime and its operator-facing control/dashboard workflow.

Naming and compatibility (final state, decided in #619):

• the repository/project and public identity are eeebot
• the implementation and internal imports remain in the nanobot package permanently
• eeebot/ is a thin external compatibility layer for existing imports and user-facing surfaces
• both CLI entrypoints are supported and must be preserved unless compatibility is explicitly retired:
  • nanobot
  • eeebot
• runtime paths and environment variables retain their established nanobot names, with documented eeebot fallbacks/aliases where applicable

It is not a plain mirror of the upstream HKUDS/nanobot repository. It contains fork-specific work for:

• bounded self-improving runtime slices
• eeepc live authority integration
• experiment contracts, outcomes, frontier tracking, credits, and revert records
• proof-oriented docs and the host-side operator dashboard (scripts/eeebot_dashboard.py)

GitHub repositories:

• Canonical main project repo: https://github.com/ozand/eeebot
• Ops-dashboard repo (canonical for the dormant WSGI dashboard since #617, 2026-07-05): https://github.com/ozand/eeebot-ops-dashboard
  • The dashboard actually running on eeepc is scripts/eeebot_dashboard.py (this repo, port 8080). The sibling repo holds the more capable, not-yet-deployed replacement, extracted from here with full history.
• Upstream source project: https://github.com/HKUDS/nanobot

What this fork is for

This fork is focused on making Nanobot operationally useful for a real bounded self-improvement loop on eeepc, not just preserving upstream defaults.

Key fork-specific capabilities include:

• live authority reads from eeepc control-plane state
• durable self-evolving cycle reports under workspace/state/
• approval-gated bounded apply behavior
• promotion/write-path/read-path convergence notes and proofs
• experiment contracts with keep / discard / crash / blocked
• credits ledger and durable subagent/task correlation

The HADI hypothesis/WSJF prioritization surface and operator dashboard now live in the separate ozand/eeebot-ops-dashboard repo (extracted in #617); the live host dashboard in this repo is scripts/eeebot_dashboard.py.

Canonical docs to start with

Top-level docs index:

• docs/README.md

End-to-end system reference (read this first):

• docs/SYSTEM_OPERATION_REFERENCE.md — roles, timers, coordinator cycle, artifacts, subagent bridge (cycle-branch → import-smoke → integrate-to-main), models, diagnostics
• docs/OBSERVABILITY.md — how to see what the system is doing
• docs/ARCHITECTURE.md — high-level map

Core operating docs:

• docs/EEEBOT_SELF_IMPROVING_RUNTIME_OPERATING_CONTRACT.md
• docs/EEEBOT_INSIGHT_HYPOTHESIS_LOOP_CLOSURE.md
• docs/EEEBOT_BUDGET_AND_REWARD_MODEL.md
• docs/EEEBOT_EXPERIMENT_AND_OUTCOME_CONTRACT.md
• docs/EEEBOT_OPERATOR_WORKFLOW.md

Capability specs (current product truth) live under docs/specs/ — see docs/specs/README.md. Notably:

• docs/specs/self-evolving-runtime/spec.md, docs/specs/subagent-bridge/spec.md
• docs/specs/promotion-and-release/spec.md, docs/specs/host-runtime/spec.md
• docs/specs/migration/spec.md (final nanobot → eeebot naming state and permanent compatibility guardrails)

Host runbooks:

• docs/EEEPC_DEPLOY_VERIFY_ROLLBACK_RUNBOOK.md
• docs/EEEPC_APPLY_OK_OPERATOR_RUNBOOK.md

Tasks/backlog: GitHub Issues + status labels (not a markdown file). See AGENTS.md. Archived/superseded docs were removed 2026-07-05 (#613); recoverable from git history.

Upstream relationship

We still track upstream HKUDS/nanobot, but we do not blindly merge everything.

Merge policy for this fork:

• take safe, high-value upstream fixes selectively
• avoid merges that would break the eeepc 32-bit/runtime constraints
• preserve fork-specific bounded self-improvement behavior and operator surfaces

Examples of upstream updates that are good candidates:

• session durability and corruption repair
• safe subagent/session routing fixes
• narrowly-scoped agent reliability improvements

Examples that require extra scrutiny before merge:

• packaging/layout changes
• provider/model defaults
• heavy WebUI or channel changes
• features that assume environments unavailable on eeepc

LiteLLM configuration — single source of truth

All LiteLLM credentials and routing settings for the eeepc runtime live in one place:

/etc/eeepc-agent/litellm.env

Never set LITELLM_API_KEY, LITELLM_BASE_URL, or LITELLM_MODEL anywhere else.

File layout

File	Role
/etc/eeepc-agent/litellm.env	Source of truth — key, endpoint, model, timeouts
/etc/eeepc-agent/instances/self-evolving-subagent-bridge.env	Bridge-specific settings only (state dirs, sync flags)
/etc/systemd/system/eeepc-self-evolving-subagent-bridge.service.d/override.conf	systemd drop-in that injects litellm.env into the bridge service
/home/opencode/.nanobot-eeepc/config.template.json	Gateway wrapper template — reads key from same values

Key rotation procedure

# 1. Edit only litellm.env
sudo nano /etc/eeepc-agent/litellm.env

# 2. Restart the service — no other files need touching
sudo systemctl restart eeepc-self-evolving-subagent-bridge.service

# 3. Verify
curl -s -o /dev/null -w "%{http_code}" \
  "$LITELLM_BASE_URL/models" \
  -H "Authorization: Bearer <new-key>"
# expect: 200

Current endpoint/key/model configuration lives only in /etc/eeepc-agent/litellm.env on the host — it is not duplicated here. Models are referenced with the cl/, an/, or un/ gateway prefixes required by the proxy.

Current state

This repo should be understood as:

• a maintained operational eeebot repository
• still carrying nanobot compatibility internally in code/runtime names
• not a vanilla upstream checkout
• not a marketing landing page

Release and rollback

Releases reach the eeepc host through host/eeepc/scripts/deploy_release.sh (release directory + current symlink, previous releases kept for rollback); the bridge integrates cycle branches into main. The earlier "guarded self-evolution" path (nanobot/runtime/autoevolve.py, github_ops.py, scripts/guarded_self_evolve.py, scripts/health_check_release.py, scripts/create_candidate_release.py, scripts/commit_and_push_self_evolution.py, scripts/export_selfevo_repo.py) was decommissioned in #1224: no unit or timer had invoked it since 2026-06-20 and every duty it performed is owned by deploy_release.sh or the bridge. Recoverable from git history. The dev-machine systemd/ units that drove it were removed earlier in #597/#613. See docs/specs/promotion-and-release/spec.md for the current contract.

For current runtime and dashboard state, see the fork docs and the separate dashboard repo.