nanobot

No export/import command exists. State is plain local files under ~/.nanobot (config, workspace, sessions) that the owner can copy at any time without approval, but restoring on another machine means reinstalling nanobot and moving folders by hand (one shortfall: restore is not a single documented action).

• Quick start: data locations
• Deployment: what must persist
• CLI reference
• Troubleshooting: sessions after moves

All agent state (config and credentials, instructions, Markdown memory with its source history, session JSONL, cron jobs and triggers, skills, plugins, files, channel sessions) is on the owner's disk, and HKUDS holds nothing. OAuth integrations re-link through the model vendors' own clients or MCP dynamic client registration, not an HKUDS-registered client; Codex and Copilot token files sit outside ~/.nanobot but can be recreated by logging in again.

• Config paths
• Memory design
• Copilot OAuth client
• xAI OAuth client
• MCP OAuth
• Credential storage

The runtime is MIT-licensed and needs no HKUDS account, licence key, relay or telemetry, so the core agent runs with HKUDS unreachable. The CLI Apps capability (on by default) resolves apps through a hard-coded, HKUDS-hosted catalog (hkuds.github.io/CLI-Anything/registry.json) that the owner cannot repoint; without it or a cached copy, installing and running CLI Apps fails.

• LICENSE (MIT)
• CLI Apps catalog URL and fetch
• CLI Apps catalog fallback
• CLI Apps enabled by default
• On-demand PyPI version check

Ollama, vLLM, LM Studio and any OpenAI-compatible endpoint are documented, and tools, memory, cron and channels run in the runtime. However, no minimum model contract is documented, and some capabilities are lost off hosted models: voice transcription has only hosted backends, and reference-image editing is unsupported for the local image providers.

• Local model setup
• Transcription backends
• Image generation providers
• Tool-call handling

The default offering is local-first: all agent state is written to the owner's disk, with no HKUDS account or hosted store, so provider termination or shutdown cannot remove access to it.

• Quick start: data locations
• Config paths

State is stored as JSONL, JSON, SQLite, Markdown and a git repo, with no nanobot-applied encryption. The docs give file locations and roles but no field-level schema for session records, run records, cron/trigger stores or the llm_usage SQLite tables.

• Session serialization
• Run records
• Usage store (SQLite)
• Architecture: file layout
• Memory layout

Model, tools and access settings are visible through /status, nanobot status, the WebUI and config.json, and compaction summaries and runtime-context blocks are persisted with the session. The assembled system prompt, built each turn from package templates, has no documented viewer: the WebUI context view shows only the session part, and full request capture needs a third-party Langfuse plugin (OpenAI-compatible providers only), which G3 caps at partial. NANOBOT_* environment overrides are not shown in status (edge gap, not counted).

• Prompt assembly
• WebUI context projection scope
• Langfuse guide
• Status command

nanobot is self-hosted, and HKUDS operates no service that receives owner content or usage data. The code contains no telemetry or analytics, and the only HKUDS-related requests (an owner-triggered PyPI version check, the GitHub-hosted CLI Apps catalog, a TUI binary fallback) carry no content.

• Version check (no background polling)
• CLI Apps catalog

The source shows no paid placement or self-preference in the agent's context, provider order, search default (DuckDuckGo) or tool choices, and the setup has no preselected partner provider. Partner and affiliate links appear only in the README and docs. The bundled clawhub skill is visible and can be switched off with disabledSkills.

• Provider registry
• Web defaults
• README partners
• clawhub skill

Main, cron, heartbeat and trigger turns are saved to session JSONL with full tool-call arguments. However, subagent tool calls stay only in memory and Dream runs are ephemeral (unrecorded entry paths), nothing tells the owner when an action goes unrecorded, and by default tool results over 16,000 chars are cut to a 1,200-char preview whose full copy is deleted after 7 days, with run history capped at 20 entries (three shortfalls).

• Subagent run loop (in-memory messages)
• Dream ephemeral run
• Tool-result offload retention
• max_tool_result_chars default
• Trigger run-history cap

Session JSONL is rewritten in full on each save, and sessions, run records and usage data carry no hashes, signatures or chain, so the record can be changed without trace.

• Session save
• Run records

By default (restrictToWorkspace false, no exec sandbox, full access mode, shell guard skipped), the agent's shell and file tools can edit or delete its session JSONL, usage database and logs. The documented bwrap/seatbelt sandbox masks ~/.nanobot from the agent, but cron/trigger run records and tool-result offloads stay in the writable workspace, and Windows has no sandbox.

• restrict_to_workspace default
• Shell guard only in restricted mode
• bwrap masking
• Cron store paths
• Security docs

All components are open source: the core is MIT, the WebUI and TUI source ship in the repo, and the Bun runtime is LGPL with a source offer. The default PyPI wheels (with a prebuilt ~119 MB TUI binary and WebUI bundle) are uploaded by hand, with no attestations, provenance or reproducible-build claim, so the distributed build cannot be tied to source independently.

• LICENSE
• Release process (no automatic PyPI publication)
• TUI wheel bundler
• TUI source offer
• PyPI release metadata

nanobot has no agent-level identity (no keypair, DID or agent card). The agent acts through owner-configured channel accounts, such as an email sender on the owner's domain, which HKUDS cannot revoke or impersonate, so attribution is per channel only.

• Agent social network doc
• Email channel config
• Pairing store (sender approval only)

A dulwich git repo versions SOUL.md, USER.md and MEMORY.md, and /dream-restore reverts a Dream commit. All commits are attributed to Dream, owner or agent edits between Dream runs are folded into the next Dream commit, and config, skills, AGENTS.md, cron, the model and the runtime version have no history or rollback (agent self-changes via the my tool are only a log line).

• GitStore author
• Tracked files
• Restore limited to Dream commits
• my tool audit

SOUL.md, USER.md, AGENTS.md, the Dream and evaluator prompts and built-in skills can be overridden or disabled from the workspace, and updates never overwrite owner files. The core system-prompt templates (identity, platform policy, tool contract and others) load only from the installed package, with no documented override.

• Template loader
• Prompt assembly
• Prompt override README
• Skills precedence
• No-overwrite sync

SOUL.md, USER.md and memory/MEMORY.md are plain, editable Markdown. The cross-session memory/history.jsonl archive is documented as append-only, with no supported item-level edit or delete, and past sessions the agent can search and read can only be deleted as whole topics.

• Memory docs
• Session tools
• history.jsonl write guard

Owner tools can be added without review through MCP (with enabledTools filters), entry-point plugins, skills and CLI apps, and exec, file, web, my, CLI Apps and image generation each have an enable switch. Built-ins such as message, spawn, cron, goals and the session tools have no switch and register whenever their services exist.

• Tool loader
• Base enabled() returns True
• ToolsConfig

Sandbox, workspace restriction, SSRF guard (via ssrfWhitelist), exec timeout, rate limit and the exec deny list (via allowPatterns) are all owner-configurable. The http/https-only URL restriction for web_fetch and MCP HTTP, and the refusal to bind the WebUI to 0.0.0.0 without auth, have no owner override.

• SSRF guard
• Exec allowPatterns override
• Wildcard bind check
• Security config

There is no auto-update, remote flag or server-side setting. The PyPI version check runs only when the owner clicks it and installs nothing, and model, instruction and runtime changes happen only when the owner upgrades or edits config.json, so a self-hosted install stays pinned indefinitely.

• Version check
• Installer
• Updating

Instruction sources are limited per sender (allowFrom plus pairing), and spend is met under G11 (no payment capability). Contact and network egress are on/off only (no per-recipient or per-domain lists). By default the shell guard is skipped and the agent's file and shell tools can rewrite ~/.nanobot/config.json and pairing.json, changing its own permissions (two shortfalls, and limits can be overridden by model output).

• Channel sender check
• Message tool
• restrict_to_workspace default
• Shell guard only in restricted mode
• Network block list
• my tool protected keys

nanobot v0.3.5 has no mechanism for the owner to require approval before a tool call or action class runs. Access modes are scope limits, and approval exists only for pairing new senders.

• Goal permission (internal flag)
• Pairing approval

`nanobot gateway stop` terminates the single local process that runs turns, subagents, cron, heartbeat and shell sessions (SIGTERM, then SIGKILL after a 20 s default). Interrupted turns come back as awaiting_user rather than replaying. In-chat /stop covers one session only, and completion within seconds needs a hands-on check.

• Process stop
• Gateway shutdown
• Recovery awaits user
• CLI reference

nanobot sends no telemetry, and HKUDS receives no owner content. By default web search queries go to DuckDuckGo and every fetched URL goes to Jina Reader (useJinaReader true), third-party destinations the owner did not specifically choose, disclosed only in the configuration reference. Both can be switched off, and no data terms are published.

• Web tool defaults
• Jina reader disclosure
• Version check

All credentials are local, in plaintext config.json and OAuth token files, and HKUDS holds none. Each can be removed through `nanobot provider logout`, WebUI settings or MCP server removal. There is no single list of credentials (Codex and Copilot tokens sit in platform data folders outside ~/.nanobot), and after Codex logout the oauth-cli-kit dependency re-imports ~/.codex/auth.json if present.

• Provider logout
• Copilot token path
• Codex provider token storage
• Credential handling

No uninstall-and-purge command or documented delete-all procedure exists; `gateway uninstall-service` removes only the service unit. Agent data spans ~/.nanobot, OAuth token folders outside it and the installed package environment, and nothing confirms removal.

• Quick start: data locations
• CLI reference
• Deployment: uninstall-service