(formerly Thoth)

Row-Bot is a local-first desktop AI assistant for doing real work with models, memory, and tools. Its name is the operating model: Reason through messy context, Orchestrate tools and model providers, and Work inside the files, repos, workflows, and channels you choose.

It combines chat, durable memory, tool use, Agent Profiles, Goal Mode, automatic parent-led agent orchestration, profile-first workflows, Developer Studio, Designer Studio, Smart Skills, Skills Hub, Custom Tools, Plugin System v2, progressive external-tool and skill discovery, context metering and rolling compaction, provider-aware reasoning controls, messaging channels, authenticated multi-device owner access with durable trusted addresses, a native Buddy desktop overlay, managed visible-browser automation, opt-in native Computer Use, centralized conversation cleanup, realtime voice, and provider-aware model routing. Durable app data stays local by default.

For larger tasks, Row-Bot can keep a visible goal, run the thread through a focused Agent Profile, and orchestrate scoped child agents for research, review, implementation, or follow-up work. The original parent remains responsible for joining required results and answering, while durable checkpoints preserve approvals, steering, retries, stops, and recovery. Checkpoint-safe work budgets and application-wide delegation limits keep long or repetitive runs bounded and visible. Parallel writers can be assigned to distinct existing local folders as separate Developer workspaces; folder-scoped locks let those children work concurrently while preserving one writer at a time inside any shared folder. If an app restart interrupts delegation or owned shell work, Row-Bot closes unanswered tool calls without replaying them and resumes the saved parent when its required child results are ready.

Recommended Auto capability loading keeps permitted core tools directly available and searches enabled MCP, plugin, Custom Tool, and channel capabilities only when a request needs them. Enabled manual and plugin skills can be selected for the current parent or child task under the same profile, approval, workspace, and execution-budget boundaries. For long conversations, the responsive desktop composer meters the complete next model input and Row-Bot can compact complete older turns into durable untrusted reference context while preserving the newest turn and atomic tool-call/result groups. It validates the rebuilt prompt before saving and fails with an exact capacity message when the fixed prompt and tool schemas cannot fit the selected window.

Choose the model path that fits the task: local models through Ollama; provider keys for OpenAI, Anthropic, Google AI, xAI, MiniMax, OpenRouter, Atlas Cloud, Requesty, Ollama Cloud, OpenCode Zen, and OpenCode Go; subscription or OAuth sign-in for ChatGPT / Codex, Claude Subscription, and xAI Grok; or custom OpenAI-compatible endpoints such as oMLX, LM Studio, vLLM, llama.cpp, LocalAI, LiteLLM, and SGLang. Row-Bot keeps provider identity, capability labels, reasoning choices, context limits, media surfaces, and chat-only fallbacks explicit so local, hosted, subscription, and self-hosted models can sit side by side.

Row-Bot itself has no account system, no Row-Bot-hosted inference server, and no first-party telemetry pipeline. Provider calls go to the provider or endpoint you choose, and provider keys, OAuth tokens, and subscription tokens are stored in the OS credential store when available. Official Docker deployments use a separate persistent encryption-key volume and encrypted credential records instead. The optional Computer Use beta depends on Cua Driver, whose separately disclosed upstream telemetry must be accepted before Row-Bot installs or invokes it.

Download the latest installer from GitHub Releases. Windows and macOS use one-click installers. Linux has a one-line user installer.

Turn Research Into a Client-Ready Report with Row-Bot	Turn Your Inbox Into an Action Plan with Row-Bot
Create a Background AI Workflow with Row-Bot	Create Launch Campaign Designs with Row-Bot Designer Studio

See docs/ARCHITECTURE.md for the full subsystem reference.

1. Download the latest Windows installer.
2. Run it. The installer bundles the embedded Python runtime, app source, and Python dependencies. Ollama is optional and only needed for local models.
3. Launch Row-Bot from the Start Menu or desktop shortcut.

User data lives in %USERPROFILE%\.row-bot. Repairing or upgrading replaces the bundled runtime and preserves your data. Startup logs are written to %USERPROFILE%\.row-bot\row_bot_app.log, including recovery hints for known optional audio package issues such as TorchCodec.

1. Download the latest macOS DMG.
2. Drag Row-Bot.app into Applications.
3. Launch Row-Bot from Applications or Launchpad.

The first run may ask you to confirm that the app was downloaded from the internet. The packaged app uses its bundled Python runtime and dependencies, and it starts Ollama if Ollama is already installed. Apple Silicon and Intel Macs are supported on macOS 12+.

If you only want provider models or a custom endpoint, you can skip model downloads during setup.

Run:

curl -fsSL https://raw.githubusercontent.com/siddsachar/row-bot/main/installer/install-linux.sh | bash

To install a specific version:

curl -fsSL https://raw.githubusercontent.com/siddsachar/row-bot/main/installer/install-linux.sh | bash -s -- 4.9.1

The installer downloads the release tarball, verifies its SHA256 from the GitHub release manifest, installs under ~/.local/share/row-bot, creates ~/.local/bin/row-bot, and stores user data in ~/.row-bot. The default Linux build opens in your system browser. Native window and tray support are available when the required GTK, Qt, and AppIndicator libraries are installed.

Manual tarball install:

tar -xzf Row-Bot-X.Y.Z-Linux-x86_64.tar.gz
cd Row-Bot-X.Y.Z-Linux-x86_64
./install.sh
row-bot

If ~/.local/bin is not on PATH, run ~/.local/bin/row-bot or add it to your shell profile. On Linux, provider secrets use Secret Service or KWallet when available. WSL and headless systems can run without a keyring, but new secrets are session-only until secure storage is configured. For persistence in headless Linux, run Row-Bot inside a D-Bus session with a Secret Service backend such as gnome-keyring-daemon, or explicitly configure another secure Python keyring backend such as an encrypted file keyring.

Browser Automation installs its Playwright-matched managed Chromium only after you choose the explicit install or repair action in Settings. Linux may still need distribution packages that the tarball cannot install; if Playwright reports a missing operating-system dependency, install that dependency and run the Browser repair action again. Normal startup and readiness checks never download a browser.

The official image is a complete single-owner server deployment for amd64 and arm64. From the repository root, pin the release and start the hardened loopback-only Compose profile:

export ROW_BOT_IMAGE=ghcr.io/siddsachar/row-bot:4.9.1
docker compose -f deploy/docker/compose.yaml up --detach
docker compose -f deploy/docker/compose.yaml ps

After the service is healthy, create the first one-time owner invitation from a trusted terminal:

docker compose -f deploy/docker/compose.yaml exec row-bot \
  row-bot access invite --layout desktop --origin http://127.0.0.1:8080

Compose persists app data and a separately mounted encryption key in two named volumes. Back up both together. The container does not grant owner access from a Docker bridge address, and every browser must authenticate. Read Docker And VPS Operations before adding LAN, Tailscale, SSH, reverse-proxy, or public VPS reachability.

Row-Bot v4 is the renamed successor to Thoth. Current Row-Bot releases no longer run the old automatic Thoth-to-Row-Bot rebrand migration during startup. That migration shipped for multiple Row-Bot releases after the v4 rename and has now been removed from the hot startup path.

Users still on Thoth or an early Row-Bot build should first install and launch a previous migration-capable Row-Bot release, then upgrade to the current release. The current Migration Wizard remains focused on selected Hermes/OpenClaw data and is separate from the removed Thoth rebrand bridge.

On first launch, Row-Bot opens a setup wizard. Pick one of three paths:

For routine chats, use Row-Bot normally. For longer work, create a Goal so progress and blockers stay visible, choose an Agent Profile for the role you want, and let the parent orchestrate child agents when subtasks can run separately under tighter tool and approval boundaries. Required children join the same live parent turn; detached children can continue without blocking it. When independent children need to write in parallel, give each one a distinct existing local folder as its Developer workspace. Changing only a shell working directory does not partition writer ownership, and children assigned to the same folder still serialize. Use child worktrees when the task instead needs Git-backed branch isolation.

Capability loading defaults to the recommended Auto mode. Core tools permitted by the active Agent Profile stay directly available; enabled external tools and skills are searched locally and loaded for the current task as needed. Use Settings -> Tools -> Capability loading to select eager compatibility mode for an older provider or integration that requires every external schema.

Supported models expose a Thinking control beside the desktop model picker and inside compact mobile Chat controls. The available effort, On/Off, and token-budget choices come from the exact provider-qualified model and persist only for that model in that chat. Use /reasoning in Chat or a connected messaging channel to inspect or change the same setting; Provider default sends no per-thread override and remains the compatibility choice.

To use the same running Row-Bot from another computer, phone, or tablet, open Settings -> System -> Remote Access on an authorized owner device. Select a current route or add one exact trusted HTTP or HTTPS address, create a one-time invitation with either desktop or compact presentation, then open or scan it on the new device. Both layouts receive the complete owner product, including Settings. The host must remain running, every resulting device session can be revoked independently, and a saved trusted address can be removed when the route is no longer used.

For website navigation, Browser Automation uses a visible task-owned page with opaque snapshot-bound controls. Open Settings -> System -> Browser & Computer Use to install or repair the exact Chromium revision matched to Row-Bot's Playwright package. A supported installed Chrome or Edge channel can be used without a probe launch; a real channel launch failure falls back at most once to an already-ready matching managed Chromium.

To let an interactive local task operate a native Windows or macOS app, use the same Settings section. Review the Cua Driver 0.20.0 telemetry notice, explicitly install the checksum-verified private runtime, grant the requested operating-system permissions, and complete the Calculator test. Computer Use is off by default and unavailable to channels, schedules, background workflows, child agents, plugins, mobile clients, and headless/server callers. Browser Automation remains the preferred tool for websites, and the two engines never silently substitute for one another after a structured refusal.

Common first prompts:

• Remember that my mom's birthday is March 15
• Search for recent papers on transformer architectures
• Read report.pdf in my workspace
• Run git status on my project
• Open Calculator and work out the total from these figures
• Create a goal to update the release docs and track blockers
• Delegate competitor research to a focused child agent and summarize the risks
• Create a six-slide pitch deck for my startup
• Show my headache trends this month
• Remind me to call the dentist tomorrow at 9am
• Review this repo and suggest the highest-risk issues
• Turn this GitHub repo into a Custom Tool
• What did I ask about taxes last week?

For local and self-hosted servers, keep context on Auto or choose a verified window large enough for Row-Bot's complete prompt, images, history, and tool schemas. Ollama Auto targets 65,536 tokens and remains capped by native or observed capacity; fixed 32K is still available for smaller-memory setups. Custom endpoints use detected or manually declared server capacity in Auto and stay unavailable when that capacity is unknown until you declare it or set a verified Custom cap. Exact advanced values from 16,384 through 4,194,304 tokens are accepted, but an app cap does not reconfigure the server: set llama.cpp --ctx-size or the equivalent server option separately. The desktop meter shows the estimated next input and automatic rolling compaction begins at 75 percent of the effective window when capacity is known. Models that are useful for normal conversation but not reliable with tools can still run through chat-only mode.

Buddy starts in the Row-Bot sidebar. In the native Windows and macOS apps, drag Buddy itself away from the dock to create a compact always-on-top desktop overlay. The overlay stays inside the nearest monitor's usable work area, supports multi-monitor placement, and can be collapsed, hidden, docked again, or recovered from the tray. A new app launch returns it to the sidebar dock; browser/server mode, Linux browser-first launch, compact mobile presentation, and remote browsers keep Buddy inside Row-Bot.

The overlay operates the thread named in its header rather than creating a second assistant. It shares that Chat, Developer, or Designer thread's saved draft, model, tools, approval mode, progress, and latest answer. Sending captures the selected thread and surface at that moment, Stop affects only that thread's active generation, and Buddy never adds an implicit screenshot or attachment. Simple well-described approvals can be accepted or denied in the overlay; complex or incomplete approvals open the full thread. Undocking Buddy grants no new tool or approval authority.

The conversation library uses one parent-only dataset for Chat, Designer, Code, and Workflow counts and filters; Agent child conversations remain owned by their parent and are not shown as duplicate user conversations. Filter-aware Select all and Clear all keep selections from other filters intact, while bulk deletion runs behind a persistent progress view instead of blocking the UI.

Deletion is centralized and ownership-aware. Removing a conversation cancels its active generation and child Agents, blocks late writes, and clears its checkpoints, drafts, attachments, approvals, notifications, skills state, and other owned data. A Designer conversation detaches without deleting the design; deleting the design removes its assets, history, published copy, and linked conversations. Developer deletion never removes the real repository or selected folder: clean managed worktrees may be removed, while dirty worktrees and sandboxes with unimported changes are retained for recovery. Workflow audit records remain, with live thread and sensitive approval links scrubbed.

Row-Bot is a single-owner, multi-device application. Remote Access lets one owner use the same local instance from several trusted browsers; it is not a multi-user hosting or tenant-isolation system. Normal desktop launches remain local-first and keep the existing loopback owner experience. First-class server mode is stricter: every browser must authenticate, including a browser reaching the server through loopback.

An invitation and a session are different:

• An invitation is a secret link used to add one device. It expires after 10 minutes and can be consumed only once, when the recipient explicitly presses Connect.
• A session is the separate HttpOnly browser credential created after the invitation is accepted. A trusted-device session lasts up to 30 days; a temporary session lasts up to 12 hours. Sessions survive normal restarts and can be revoked without changing any invitation.
• A desktop or compact invitation changes only the initial presentation. Every authenticated browser receives full owner access, including Settings. Rich Developer and Designer editors remain desktop-layout-oriented.

Treat an unused invitation like a password until it expires. Row-Bot stores only hashed invitation and session secrets in the existing mobile.db access database; raw session secrets are never placed in URLs.

Settings shows reachability and authorization separately. “LAN enabled” or an active Tailscale route means a browser can reach the connection screen, not that the browser is trusted.

From the invitation dialog, Add another trusted address accepts one exact http:// or https:// origin, saves it in access_routes.json, applies it to new HTTP and WebSocket admission immediately, and creates the invitation. Saved addresses survive restart and can be removed with confirmation; current access through a removed address may stop immediately. Credentials, paths, queries, fragments, wildcards, malformed ports, and non-HTTP(S) schemes are rejected. Origins from ROW_BOT_PUBLIC_ORIGINS are visible but read-only, and setting ROW_BOT_ALLOWED_HOSTS makes Host admission externally managed so the UI cannot override deployment policy.

The complete public guide, including current UI screenshots, invitation layouts and lifetimes, Tailscale ownership, browser-local voice, recovery, and proxy diagnostics, is Remote Access And Server Mode. Docker and VPS operators should use the pull-first Docker And VPS Operations runbook.

When Row-Bot creates and verifies its own Tailscale Serve route, it persists an exact ownership record and restarts the child app. Startup then trusts only the local loopback proxy for that exact app port and allows only the verified owned .ts.net host and HTTPS origin. If the launcher is unavailable, Settings asks for a manual restart. Manually managed Tailscale and reverse-proxy routes still require explicit public-origin, allowed-host, and trusted-proxy configuration.

For a zero-configuration SSH path, start Row-Bot on the remote host and forward it from the workstation:

row-bot serve --host 127.0.0.1 --port 8080
ssh -N -L 18080:127.0.0.1:8080 user@row-bot-host

Then create an invitation on the host for the browser-facing origin:

row-bot access invite --layout desktop --origin http://127.0.0.1:18080

For direct server operation, row-bot serve defaults to loopback, one worker, no tray or splash, no opened browser, and no automatic Ollama startup. Bind more broadly only after choosing the route and canonical origin:

row-bot serve \
  --host 127.0.0.1 \
  --port 8080 \
  --public-url https://row-bot.example.com \
  --allowed-host row-bot.example.com \
  --trusted-proxy 127.0.0.1/32

The legacy row-bot --server --no-open form remains as a deprecated compatibility path and now uses authenticated server behavior. New scripts and service definitions should use row-bot serve.

Useful offline access-management commands are:

row-bot access invite --layout desktop --origin https://row-bot.example.com
row-bot access invite --layout compact --temporary --origin https://row-bot.example.com
row-bot access list
row-bot access revoke DEVICE_ID
row-bot access revoke SESSION_ID --session
row-bot access revoke-all --yes
row-bot access doctor

If the owner loses every browser session, use a trusted local terminal, SSH session, or docker compose exec to create a new one-time computer invitation. The list and doctor commands never print reusable session secrets. Invitation commands are the only commands that print the raw one-time link, so keep their terminal output and scrollback private.

Docker users should follow the public Docker And VPS Operations guide. The repository's deploy/docker/README.md retains source-build and operator detail. Both preserve the loopback-only Compose default, explicit invitation bootstrap, and separate persistent data and encryption-key volumes. The normal Compose path creates its encryption key once without additional credential-store setup and stores owner-entered credentials as encrypted records under /data/secure-secrets. deploy/reverse-proxy/Caddyfile.example and deploy/systemd/row-bot.service.example are reviewed starting points for operator-managed VPS deployments.

For a reverse proxy, configure ROW_BOT_PUBLIC_URL, ROW_BOT_ALLOWED_HOSTS, and ROW_BOT_TRUSTED_PROXY_CIDRS explicitly. Do not trust a broad Docker network or accept caller-supplied forwarding headers. Keep NiceGUI at one worker, preserve WebSocket upgrades, and terminate public traffic with HTTPS. Public ingress also requires operator-owned rate limiting, firewall policy, log review, and recovery procedures; Row-Bot does not modify the host firewall.

Remote browser voice captures the requesting browser's microphone, performs transcription in Row-Bot with the selected local STT engine (Whisper by default, or SenseVoice after its explicit installation), and returns local Kokoro audio to that same browser. Remote microphone capture requires HTTPS; plain LAN HTTP is not a secure browser context. Voice model downloads remain explicit and OpenAI Realtime voice remains a separate provider feature.

SenseVoice installation is an explicit ~940 MB download from ModelScope under the model's Apache-2.0 license. ModelScope receives the download request and standard SDK user-agent; Row-Bot sends no audio, prompts, or usage data, and normal inference uses only the verified local snapshot with update checks disabled. SenseVoice is unavailable on Intel macOS because matching PyTorch/Torchaudio CPU wheels are not published for that runtime; local Whisper remains available.

Back up the complete active ROW_BOT_DATA_DIR while Row-Bot is stopped, and protect that backup as private user data. It contains conversations, configuration, instance identity, invitations, devices, and sessions. OS keyring credentials may need a separate recovery plan. Docker deployments must back up the data and encryption-key volumes together; either one alone is insufficient to recover saved provider credentials. Test restore and rollback with an isolated instance before relying on a backup.

Most tools work without API keys. Add keys only for the providers and integrations you use.

Model catalog browsing, pinning, defaults, and Quick Choices live in Settings -> Models. Model choices stay provider-qualified, so the same model ID from a local runtime, OpenRouter, Atlas Cloud, Requesty, xAI API keys, xAI Grok OAuth, a custom endpoint, or a direct provider remains distinct. Row-Bot also tracks whether a selected model is ready for full agent/tool use, supports vision, belongs on an image or video surface, should run chat-only, or needs a larger context window or different endpoint profile. Live catalogs such as Atlas Cloud, MiniMax, and Requesty refresh through the same provider path. xAI API-key and OAuth refreshes also query the live image-generation catalog, preserve published quality/resolution options, defaults, and valid combinations, and keep media rows out of chat, agent, and vision model surfaces. Automatic targeted and scheduled refreshes preserve each provider's last-known-good rows when a fetch is empty, fails, or stops part-way through pagination; Settings labels live, cached, and fallback catalog outcomes.

OpenCode Zen and OpenCode Go refresh each gateway's live /models list and intersect it with OpenCode's public native routing registry. Row-Bot persists the resulting provider-qualified context, modality, tool, streaming, reasoning, and OpenAI Chat, OpenAI Responses, Anthropic Messages, or Google GenAI transport metadata, so newly listed supported models can become usable without a hardcoded name update. A failed gateway or registry refresh preserves the last known good rows; a cold failure uses the bundled static fallback.

Live catalog refreshes resolve credentials through the same provider-scoped auth store used by Settings. A key saved in the provider dialog can therefore refresh its catalog and populate provider-qualified rows immediately without a duplicate legacy environment-key entry.

For local Ollama models, Row-Bot uses the daemon's native capability metadata when it is available. A new model family that advertises tools can therefore enter Agent mode without waiting for a maintained family-list update or an unnecessary live probe, while a model whose native metadata omits tools is not promoted merely because its name resembles a historically tool-capable family.

Reasoning controls are exact-model capabilities rather than a provider-wide switch. A supported selection is stored locally per chat and canonical model, mapped into that transport's native request shape, and shown as a separate collapsed Thinking section when replayable reasoning content is returned. If a provider rejects an explicit choice before returning output, Row-Bot retries once with Provider default, clears the rejected choice, and tells you; it does not replay authentication, rate-limit, timeout, cancellation, server, or mid-stream failures.

Configure providers in Settings, Channels, and Accounts. Keys and in-app ChatGPT / Codex, Claude Subscription, and xAI Grok OAuth tokens are stored in Windows Credential Manager, macOS Keychain, or Linux Secret Service/KWallet when available. If secure storage is unavailable, newly entered secrets are usable for the current Row-Bot process only and must be re-entered after restart unless a secure keyring backend is configured. The official Compose path automatically creates a persistent ROW_BOT_SECRET_STORE_KEY in its isolated secrets volume and uses it to encrypt owner-entered credentials under /data/secure-secrets; advanced operators can replace that volume with an explicit read-only secret file. Back up the key and data together; see Docker And VPS Operations. ~/.row-bot/api_keys.json and ~/.row-bot/providers.json keep metadata only, such as saved state, provider status, Quick Choices, compatibility profiles, runtime and vision probe results, OAuth client-id diagnostics, model-count status, and masked fingerprints.

OpenAI-compatible chat requests use a 900-second read-inactivity timeout. Set ROW_BOT_OPENAI_COMPATIBLE_READ_TIMEOUT to a positive number of seconds to override it for all OpenAI-compatible endpoints.

Atlas Cloud uses an OpenAI-compatible API, but Row-Bot treats it as a first-class provider with its own setup, auth, catalog refresh, provider identity, capability labels, streaming behavior, and chat/agent/vision surface filtering.

Requesty is also a first-class OpenAI-compatible provider path. It uses provider-qualified refs, maps Requesty's catalog metadata into Row-Bot capability labels, and filters non-chat media/audio/embedding/realtime rows out of Brain and agent choices.

xAI Grok OAuth is also a first-class provider path. It keeps subscription/OAuth Grok runtime state separate from XAI_API_KEY, reports token health and runtime readiness in Settings, and scopes Grok Imagine image/video models to media surfaces instead of chat and agent pickers. Image generation and editing select quality and resolution only from complete combinations published by the exact model. If a requested tier is unavailable or metadata is incomplete, Row-Bot uses the provider default and reports that choice instead of inventing an unsupported request; an uncertain timed-out generation is never retried.

Custom/Self-hosted endpoints keep server capacity and Row-Bot's planning cap separate. Auto uses model metadata or the endpoint's manually declared native limit and does not invent a generic context window. Probe evidence is scoped to the exact tested model, so one successful model cannot promote an untested sibling to Agent mode or streaming tool use. Advanced provider settings also offer explicit reasoning compatibility controls; enable reasoning replay only when the endpoint documents and accepts its preserved thinking format.

Embedding providers are configured separately from chat models. Local embeddings are available for private document and vector indexing and load strictly from the existing local Hugging Face cache during normal use. First-run setup offers Mixedbread Embed Large v1 as a checked-by-default, disclosed 675 MB download; it can be skipped. Download or repair a local embedding model later from Settings; if it is missing, failed, or still loading, bounded memory recall continues with lexical and graph fallback instead of silently downloading or blocking the turn. Optional cloud embeddings show a privacy warning because document text is sent to the selected embedding provider.

External Codex CLI and Claude Code login files are metadata/reference only. Row-Bot can detect that a CLI login exists, but direct Codex runtime requires the in-app ChatGPT sign-in and direct Claude Subscription runtime requires Row-Bot-owned Claude OAuth or an explicit user import. Row-Bot does not copy runnable tokens from ~/.codex/auth.json or ~/.claude/*, and Claude Subscription never falls back to ANTHROPIC_API_KEY.

Claude Subscription supports two Row-Bot-owned auth paths in Settings -> Providers: in-app Claude OAuth, or explicit import of a token printed by claude setup-token. The setup-token path is a user paste/import action; Row-Bot still does not silently read Claude Code environment variables or credential files.

After connecting Claude Subscription, Settings -> Providers can run a Claude Subscription runtime test that checks native OAuth chat, a forced Row-Bot tool call, and tool-result replay. A failed runtime test is stored as provider metadata and prevents Row-Bot from advertising Claude Subscription as tool-ready until it is fixed or reconnected; claude -p remains a separate Claude Code delegation path, not the provider runtime.

Row-Bot's tools can be enabled or disabled from Settings. In the recommended Auto mode, core tools stay directly available under the active profile while enabled external MCP, plugin, Custom Tool, and channel tools are searched and selected only when a request needs them. Search runs locally over bounded metadata and never enables an integration or authorizes execution; the selected target keeps its exact schema, real trace label, approval mode, execution budget, cancellation, and workspace boundary. Eager compatibility mode can still bind every enabled external schema.

Many tools expose multiple operations, Agent Profiles and Goal Mode add orchestration-specific tools, Developer Studio adds code-specific tools, Skills Hub can add manual or automatically selected skills, Custom Tools can be promoted after review, and running channels add send/photo/document tools automatically. Automatically loaded skills are scoped to one parent or child task, persist when that task is reopened, and appear as a compact Using skill receipt and active chip. Collapsed tool traces use a quieter compact row while keeping the full result available inside the expansion.

Safety controls are built into the tool layer:

• Destructive operations require confirmation, including file delete/move, moderate-risk shell commands, Gmail send, calendar move/delete, memory delete, tracker delete, and task delete.
• Computer Use is off by default, interactive-local-only, restricted to one task-scoped target window, and protected by an allowlisted Cua 0.20.0 surface, current-generation targets, exact semantic filters, bounded action-specific recovery, point-of-risk confirmation, ephemeral screenshots, typed-value redaction, and direct Stop/Take over/Resume controls. Routine actions return truthful delivery receipts without hidden captures or automatic replay.
• Every logical agent turn has a checkpointed model-iteration budget. Exact repeated tool actions are blocked before they can loop indefinitely, and Settings can cap nested depth, per-parent and global child concurrency, and optional child active time.
• Child-agent approval requests are surfaced in the parent thread and durable channel/mobile approval surfaces instead of waiting invisibly in a background run.
• Write-capable child Agents retain one writer per assigned workspace. Distinct registered folders may run concurrently; a shared folder stays serialized, and changing a shell CWD does not bypass the workspace lock.
• Stop propagates through the active generation to stalled provider responses, pending approvals, shell and Developer subprocesses, MCP and Browser waits, native Computer Use, Buddy, voice turns, and generation-linked child agents without cancelling unrelated runs.
• Filesystem access is sandboxed to the configured workspace folder, which defaults to ~/Documents/Row-Bot.
• Shell commands are classified as safe, moderate, or blocked. High-risk commands such as shutdown, reboot, and mkfs are blocked.
• Background workflows can have per-task command prefix and email-recipient allowlists.
• Agent Profiles and child-agent runs can narrow tools through profile/tool allowlists.
• Browser tabs, popups, and element handles are isolated per task and thread. Snapshot targets are opaque and short-lived; typed values stay out of Browser history, and normal startup never downloads or repairs the managed runtime.
• Conversation deletion is explicit, confirmation-gated, path-confined, and race-safe. It preserves real repositories, selected Developer folders, dirty recovery workspaces, retained Designer artifacts, and workflow audit rows according to their ownership contracts.
• Developer Studio has its own approval modes for edits, commands, Git operations, commits, pushes, and PR prep.
• Docker Sandbox is opt-in and runs commands in a shadow workspace until you explicitly import changes.
• Agent Profile saves, child-agent promotion, and Agent-run workflow promotion stay reviewable and approval-gated.
• Controlled self-evolution produces bounded, reviewable proposals and does not silently modify repos or app code.
• Smart Skills, slash commands, and Skills Hub imports stay user-controlled; installed skills can be enabled, disabled, reviewed, and removed. Enabled skills can be discovered progressively and loaded per parent task or child Agent, but skill instructions cannot add tools or relax profile, approval, execution-budget, or workspace boundaries.
• Plugin System v2 supports only native tools, plugin-packaged MCP servers, bundled skills, and channels. Plugins install disabled by default, cannot add arbitrary app UI or provider runtimes, and are enabled only after permission, settings, secrets, and health review in Plugin Center.
• Custom Tools are reviewed, smoke-tested, enabled, promoted, disabled, and removed without deleting their source repos.
• Gmail and Calendar permissions are tiered for read, compose/write, and destructive actions.
• MCP servers stay disabled until tested. External tools are namespaced, destructive MCP tools require approval, and broken servers degrade to diagnostics instead of blocking startup.
• Progressive capability search operates only on enabled, profile-permitted external tools and enabled skills. Loading a skill grants no tool, approval, workspace, or delegation authority, and parent, child, and sibling task state remain isolated.
• Remote HTTP and WebSocket access is session-gated. Invitations are short-lived and single-use, device and session secrets are hashed at rest in mobile.db, sessions use HttpOnly cookies, forwarded localhost headers do not bypass the gate, and devices or individual sessions can be revoked from Remote Access settings.
• Prompt-injection scanning is advisory. It reports only bounded categories for explicit role markers, instruction overrides, exfiltration requests, and hidden-control anomalies; ordinary words or model prose are not treated as authorization evidence or a hard automation failure.

Row-Bot is organized around reasoning, orchestration, and work: Agent Profiles, Goal Mode, a durable parent/child orchestrator, checkpoint-safe agent budgets, explicit prompt context/cache sections, a durable document queue and sharded retrieval index, memory, profile-first workflows, the single-owner access gate with runtime-managed exact origins and full/compact browser shells, authenticated server mode, progressive capability catalogs and bridges, one complete-input context preparation and rolling-compaction pipeline with explicit capacity sources and fixed-envelope preflight, exact per-thread/per-model reasoning plans, native OpenCode catalog-to-transport routing, separate browser and native Computer Use engines with small shared automation contracts, the native Buddy overlay, centralized ownership-aware thread cleanup, shared channel streaming, Designer Studio, Developer Studio worktrees and folder-scoped child writers, provider runtime and bounded subprocess cancellation, interrupted-parent checkpoint repair, Plugin System v2/MCP boundaries, and safety controls.

Explore the visual architecture gallery: docs/architecture.html

Read the full architecture reference: docs/ARCHITECTURE.md

Read the complete public user guide: row-bot.ai/docs

Review the Docusaurus docs source and local preview instructions: docs-site/README.md

Core Agent	Context Assembly
Knowledge Graph	Background Workflows
Multi-Channel Runtime	Designer Studio
Developer Studio	Skills System
Safety, Privacy & Control	Self-Evolution

Your default Brain model is set by the setup wizard. If you choose the local path, Row-Bot uses one of the models already exposed by your local runtime; 14B-class models are recommended for stronger agent/tool behavior, while smaller 8B-class models are better for 8 GB machines. Hosted and custom endpoint setups can skip local model downloads entirely.

Install Ollama first if you want Row-Bot's supported local model runtime. Provider-only and custom-endpoint setups can skip local model downloads.

git clone https://github.com/siddsachar/row-bot.git
cd row-bot
python -m venv .venv

Activate the environment:

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

Install dependencies and launch with the locked dependency set:

python -m pip install "uv>=0.7,<1.0"
uv sync --locked --all-extras --group test
uv run python launcher.py

requirements.txt is kept only as a generated pip-compatible export for installers and repair helpers. If you cannot use uv, the fallback is:

python -m pip install -r requirements.txt
python launcher.py

On Windows and macOS, launcher.py starts the tray icon and opens the app on the first available local port, normally http://localhost:8080. On Linux it opens in the browser without a tray by default. If port 8080 is busy, Row-Bot picks the next free port.

Authenticated headless/server mode:

uv run python launcher.py serve --port 8080

The installed console entry point is row-bot serve. The legacy python launcher.py --server --no-open form remains temporarily compatible but is deprecated.

Direct app launch:

python app.py

Direct launches default to http://localhost:8080. Set ROW_BOT_PORT to choose a different port.

Dependency edits go through pyproject.toml, not requirements.txt:

# edit pyproject.toml
uv lock
python scripts/export_locked_requirements.py
uv sync --locked --all-extras --group test
uv run python scripts/verify_runtime_dependencies.py all

Supported optional extras are voice, designer, browser, channels, mcp, developer, local-embeddings, and media. Development and packaged app builds use all; lightweight source installs can choose only the extras they need. The voice and all extras include the platform-supported FunASR, ModelScope, and matching CPU PyTorch/Torchaudio runtime, but the SenseVoice model snapshot is still downloaded only through the explicit Voice settings action.

Recovery helpers:

python launcher.py --reset-tasks-db
python launcher.py --reset-db
python launcher.py --restore-data

These commands back up local SQLite files before recreating or restoring known task, memory, and thread databases.

Docs site preview:

cd docs-site
npm ci
npm run start

Local model runs stay on your machine. Documents, memories, conversations, knowledge graph data, Agent Profiles, Goal Mode records, child-agent run history, workflows, plugin state, logs, and user settings are stored locally under ~/.row-bot or the platform-specific Row-Bot app data paths used by the installer. Current Row-Bot startup reads Row-Bot data only and no longer scans, copies, repairs, or rewrites old .thoth data.

Invitations, devices, hashed session credentials, revocation state, and display-safe access events are stored locally in mobile.db. Remote access has no Row-Bot cloud relay: each browser connects directly to the running Row-Bot host through the route you choose. Every authenticated browser is the full owner, so keep invitation links and public origins private and revoke devices or sessions you no longer trust. In Docker, saved provider credentials are encrypted locally with the key from the separate secrets volume.

Computer Use is also opt-in. Row-Bot downloads only the reviewed Cua Driver 0.20.0 full archive after a separate Install action, verifies its SHA-256, and keeps the runtime private with upstream update checks disabled. The expanded version-2 disclosure requires fresh acceptance before the upgraded process can start. Reviewed upstream telemetry can include pseudonymous installation and process-session identifiers plus bounded product/platform/client/tool/outcome, duration/output, aggregate usage, permission, and lifecycle categories. Its tagged event builders exclude prompts, tool arguments/results, typed content, screenshots, accessibility trees, app/window names, URLs, paths, raw values, and raw errors. Target-window screenshots remain ephemeral, and typed values are excluded from durable history, logs, checkpoints, approvals, memory, and media.

Buddy overlay placement, visibility, collapse state, appearance, and per-thread drafts are local app data. The overlay reads the selected conversation rather than copying it into a second store, and undocking does not change the thread's model, tools, approval policy, or provider boundary. Conversation cleanup uses local ownership records and deletion guards; retained dirty worktrees and unimported sandboxes should still be reviewed or removed manually when they are no longer needed.

Provider and custom models are opt-in. When selected, the current conversation, model-visible tool context, and tool results are sent to that endpoint. Memories, documents, files, graph data, and other conversations stay local unless you explicitly include them in the current conversation or expose them through a tool result. Memory recall happens locally before any selected memory is inserted into the active turn.

Reasoning choices are stored locally per chat and model, but the selected provider receives the resulting reasoning parameter and may bill for additional tokens. Returned reasoning can contain sensitive intermediate material. Custom endpoint reasoning replay remains off unless you explicitly declare support; enable it only for an endpoint whose format and trust boundary you understand. An explicit OpenCode catalog refresh contacts both the configured Zen or Go gateway and the public native routing registry to resolve current model routes.

External-tool and skill matching also happens locally over enabled capability metadata. Search does not contact an embedding or model provider. When rolling compaction is needed, Row-Bot uses the task's selected model to summarize a bounded older conversation range; a cloud-selected task therefore sends that range to the already selected cloud provider as part of normal model use.

Installing SenseVoice is a separate explicit network action to ModelScope and discloses the model size, license, and SDK request before it begins. Row-Bot persists only a verified contained snapshot, disables FunASR update checks, and sends no audio, prompts, or usage data during installation or normal offline transcription.

Developer Studio only touches repos you link, clone, or explicitly allocate as worktrees. Local execution runs in that repo or worktree. Docker Sandbox runs in a shadow copy and requires explicit import before changing the real repo. Inside the official server container, nested Docker Sandbox mode is unavailable and fails closed rather than substituting local execution. Skills Hub imports, plugins, Custom Tools, Agent Profiles, child-agent promotion, and promoted Agent workflows are opt-in, testable or reviewable, removable where applicable, and only affect normal chat or workflows after you enable, select, or promote them.

Row-Bot does not require a Row-Bot account, and there is no Row-Bot-hosted middleman for provider calls.

The public row-bot.ai website is separate from the Row-Bot application. Its marketing pages load Google tag services and measure page/download, Linux-install-view, and installation-guide interactions. The installed application does not load that site tag and still has no Row-Bot first-party telemetry pipeline.

• Complete public user guide
• Remote Access and server mode
• Docker and VPS operations
• Progressive tools and skills
• Reasoning controls
• Buddy desktop overlay
• Browser and Computer Use
• Release notes
• Architecture
• Visual architecture gallery
• Public docs site source
• Computer Use security decision
• Plugin System v2
• Prompt context and cache contract
• Contributing guide
• Branching strategy
• Release process
• Installer and CI verification plan
• Source layout and packaging
• Security policy
• Code of conduct

All changes should go through a pull request. main is intended to stay releasable.

Apache 2.0. See LICENSE.

Built with NiceGUI, LangGraph, LangChain, Ollama, FAISS, Cua Driver, Kokoro TTS, faster-whisper, FunASR/SenseVoice, HuggingFace, and tiktoken.