agent-box

AgentBox

English | 简体中文

A private, powerful desktop client for multi-model AI agents

Built with React 19, TypeScript 5.7, and Electron 44, with native adapters for the OpenAI Chat Completions API, OpenAI Responses API, and Anthropic Messages API, plus Agent Skills and Model Context Protocol (MCP) servers.

Highlights

• Local-first encrypted storage: the renderer is sandboxed, and stored API keys are never returned to it in plaintext. A random data key is protected by OS secure storage, and the local vault is encrypted with AES-256-GCM.
• Portable conversation backups: export lossless JSON and human-readable Markdown. Shallow backups contain conversations; deep backups also include unique conversation working directories. Optional password protection uses WinZip AES-256 (AE-2).
• Providers and API formats are independent: configure providers, models, and wire protocols separately. AgentBox supports the OpenAI Chat Completions API, OpenAI Responses API, and Anthropic Messages API, with presets for OpenRouter and local CLIProxyAPI connections.
• MCP server integration: connect local stdio servers or remote Streamable HTTP servers, with fallback support for legacy HTTP+SSE. BM25 tool retrieval, per-conversation server selection, approval policies, and Tool Explorer keep large tool catalogs manageable.
• Resumable Agent execution: Agent mode can run up to 30 tool-call turns by default, configurable from 1 to 100. Safe provider failures use an encrypted LangGraph checkpoint sidecar; agentTrace remains the portable fallback for output limits, cancellation, and uncertain tool-side-effect states.
• Integrated terminal and workspace tools: use an automatically detected cross-platform shell or configure a custom executable and arguments. Native workspace tools read UTF-8 files in chunks and create, overwrite, or append files without shell escaping.
• Isolated multi-tab browser: optionally open multiple remote pages in sandboxed Electron WebContentsView tabs. Agent mode tracks stable tab IDs, reads bounded semantic snapshots, and requests approval for reference-based interaction. Separate settings opt into Vault-encrypted persistent cookies, Agent screenshots, user-selected manual uploads plus workspace-scoped Agent uploads, and controlled downloads; remote pages never receive Node.js or AgentBox IPC.
• Conversation-scoped development environments: every conversation has a working directory. Configure JDK, Go, PHP, and Python runtimes; Python supports project .venv/venv, system interpreters, virtual environments, Conda environments, and custom interpreters.
• Multi-file Agent Skills: Skills can include Markdown instructions, reference documents, and non-automatic Python or shell reference scripts. Pin Skills to a conversation, invoke $skill-id, use automatic retrieval, or let the model load a relevant Skill on demand. ZIP skill archives can be imported and exported.
• Rich chat interface: Markdown, GFM, syntax-highlighted code, KaTeX math, multimodal attachments, image optimization and preview, editable conversation trees, regenerated branches, and version navigation.
• Reasoning, usage, context reuse, and web search: normalize reasoning output and per-model-request token usage—including cached-input and cache-write counters—across supported providers. Optional Agent context reuse supports stable-prefix caching and Responses native continuation with compatibility fallback. OpenRouter web search uses the openrouter:web_search server tool with automatic or provider-native search modes and structured citations.
• English and Simplified Chinese UI: language resources are shared by the renderer and Electron main process. On first launch, Chinese system locales default to Simplified Chinese; all other locales default to English. The selection is persisted in encrypted settings.

Screenshots

Captured from the running Electron application with the English UI.

Agent mode with the built-in browser

The Agent opens the Electron website, reads a page snapshot, and summarizes its findings. The split view shows the live page alongside completed navigate and snapshot tool calls, activated Skills, and token usage.

Agent Skills

Browse built-in Skills, inspect their files, and manage ZIP imports and exports.

Model configuration

Select a provider and API format, and configure each model's client-side context and output budgets.

Technical documentation

The English documentation is in docs/. The corresponding Chinese documentation is in docs_zh/.

• System architecture and process isolation
• Encrypted storage and vault security
• API protocols and request gateway
• Agent Skills system
• MCP servers and tool retrieval
• UI and interaction model
• Development, testing, and releases
• Working directories and developer runtimes
• Internationalization
• LangGraph Agent Runtime
• Encrypted LangGraph checkpoints

Quick start

Requirements

• Node.js 24 or later (Node.js 24 is the CI baseline)
• pnpm 11.24.0 (pinned by packageManager). Node.js 25+ no longer bundles Corepack, so install standalone Corepack or make the pinned pnpm version available before using the setup command below.
• An OS credential backend: Windows credential protection, macOS Keychain, or Linux Secret Service

Install and run

git clone https://github.com/ac-1e9plus7/agent-box.git
cd agent-box
# Node.js 24 ships Corepack. On Node.js 25+, install standalone Corepack first,
# or ensure pnpm 11.24.0 is already available.
corepack enable
pnpm install

# Start Electron with the Vite development server
pnpm dev

# Validate the project
pnpm check

# Build production bundles
pnpm build

Additional packaging commands:

# Build an unpacked application directory
pnpm package

# Build distributable artifacts for the current platform
pnpm dist

Electron Builder produces an NSIS installer and portable executable on Windows, a DMG on macOS, and an AppImage on Linux. The release workflow builds Windows x64/arm64, macOS native, and Linux x64/arm64 artifacts.

Security invariants

1. The renderer cannot read stored API keys. It may submit a newly entered key, but persisted keys are write-only and are represented only by hasApiKey or masked fields; network requests and authentication stay in the main process.
2. There is no plaintext credential fallback. If OS secure storage is unavailable, AgentBox refuses to load or persist protected local data.
3. OpenRouter routing is privacy-oriented by default. New model configurations default to data_collection: "deny" and zdr: true.
4. Workspace file tools are scoped. File tools reject traversal and symbolic-link escapes. The terminal starts in the conversation working directory but is not an OS sandbox; approved commands can access other paths and the network.

License

AgentBox is available under the Apache License 2.0.

Data platform MCP servers support exact confirmation and per-operation delegated credentials. See data-plat integration.