OpenAgent

A desktop AI agent for working with files, tools, and long-running tasks in your workspace.

English · 简体中文
Downloads · Changelog · Contributor guide

OpenAgent combines a streaming chat interface with an agent that can inspect projects, edit files, run commands, and use external tools. Choose your model service and workspace, keep conversation history and application data on your device, and extend the agent with skills, roles, MCP servers, and plugins.

The desktop application targets Windows, macOS, and Linux. It uses Svelte 5 with SvelteKit 2 for the interface, Tauri 2 for the native shell, and a Rust Runtime maintained in the pinned private SDK. The project is under active development; source access to the public host does not include access to the private SDK.

What you can do

Image, PDF, and text attachments support drag/paste, previews, checkpoint restoration, and branch editing. Actual model and attachment capabilities depend on the selected provider and model.

Install and start

Download an installer or application bundle for your platform from GitHub Releases. Choose a release that includes desktop installers; component-only releases update an existing installation.

• Offline bundle (full): includes Runtime, frontend, embedding, and platform helpers; Windows also includes WebView2.
• Online bundle: starts the desktop shell first, then downloads and verifies application resources. Updates download resources concurrently, replace the shell first, and continue installation after restart.

On first launch, the setup window guides you through preferences, a model service, default models, and resource readiness. Select a workspace folder, enter your service credentials and endpoint, verify the connection, and choose the Chat and Flash models. Chat handles the main conversation; Flash handles smaller background tasks. Sending remains disabled until an available chat model is configured.

You can change services and defaults later from the Models menu. OpenAgent supports Anthropic, OpenAI, and compatible services, including custom endpoints. For an OpenAI-compatible service, the endpoint may be a host, a /v1 root, or a full /chat/completions URL; the application normalizes it to the API root.

Approvals and execution permissions

The composer offers an approval selector. The Agent → Execution & Permissions surface configures approval and sandbox policy separately.

Approval never expands filesystem or network access. The default managed profile permits host-wide reads and workspace-scoped writes, keeps .git, .agents, and .codex read-only beneath broad writable roots, and restricts networking. Read-only presets and explicit path rules are also available. Disabled isolation uses the application's ambient process access.

Managed terminals use Bubblewrap on Linux, Seatbelt on macOS, and the pinned Codex sandbox on Windows. Built-in file tools enforce the same filesystem policy. Missing helpers or failed sandbox setup stop execution. See the permissions contract for the exact rules.

Skills, roles, and plugins

A skill is a reusable instruction file. Place SKILL.md in either ~/.agents/skills/<name>/ for global use or <workspace>/.agents/skills/<name>/ for project use:

---
name: python-review
description: Review Python changes for error handling, type hints, and maintainability.
metadata:
  category: code-review
---

Read the changed code and report actionable findings with file locations.
Prioritize incorrect behavior, silent failures, and missing error handling.

Skills are discovered progressively and their full instructions are loaded when relevant. Roles store reusable agent workflows and can be selected for conversations or delegated work.

Open Integrations → Extensions to manage external MCP services and Integrations → Plugins to browse or manage Agent Plugins. The official catalog includes Goal, Graph, Chat Groups, Cua Driver, Message Board, and Plugin Developer. Plugins can provide commands, MCP tools, skills, lifecycle automation, and embedded UI. Cua Driver provides desktop automation and requires an explicit host-access grant.

Goal, Graph, and Chat Groups own their workflows inside their packages. Child-agent coordination is a Runtime capability. Plugin versions and updates are independent of the desktop version. For package authoring and local source setup, start with the plugin development skill.

Memory and local data

Application configuration and durable data use one root:

The application root contains config.toml, the conversation SQLite database, attachments, logs, installed plugins, plugin data, and versioned resources. Valid external configuration edits reload automatically. The Runtime owns persistence, backup, and migration behavior; see configuration and application data.

User memory supplies standing context. Structured agent memory is stored separately and supports local hybrid text/vector retrieval. Manage the background memory task and retrieval controls under Agent → Flash Tasks; automatic retrieval is disabled by default. The Memory surface manages user and agent memory.

Local storage does not make model requests offline: prompts, selected context, and attachments are sent to the configured model service. MCP services and plugins may also contact their configured services.

Messaging and browser access

Integrations → Channels supports Feishu/Lark, Telegram, QQ, WeChat, Discord, and Slack. Each peer keeps a durable conversation and its own workspace, model, and role selection. Current channel messaging supports text; setup, allowlists, and commands are documented in messaging channels.

The same surface offers the Gateway for paired browser access. Enable it, explicitly allow a workspace, and pair using the displayed one-time code. Remote users can work with conversations, attachments, approvals, questions, and branches while the desktop remains running. Remote access and direct LAN access are disabled by default; provider administration and unrestricted desktop operations stay local. See the remote gateway guide for connection and security details.

Updates and diagnostics

OpenAgent has Beta, RC, and Stable update channels. The frontend, supervised Runtime, native shell, and installed plugins have separate delivery boundaries. Component updates are verified before activation; frontend and Runtime activation support rollback. Updates wait for active agent work to finish, and a native-shell update requires an application restart. See the component update contract.

Local host and Runtime logs live in <OPENAGENT_HOME>/logs, with up to 15 files retained per rolling log family. Privacy-filtered remote error collection is enabled by default and can be turned off in General → Privacy & diagnostics. It excludes conversation content, prompts, model output, tool arguments, credentials, and raw frontend errors. Optional Langfuse model tracing is separate and may contain model context; its environment variables are listed in .env.example. See the diagnostics contract.

Develop from source

Public frontend development (no private SDK access)

Install Bun 1.2.21 and Node.js; native debugging also requires Rust and your
platform's Tauri build dependencies. Choose a source tag with a published kit:

git clone https://github.com/BANG404/openagent.git
cd openagent
git checkout <published-source-tag>
bun install --frozen-lockfile
bun run dev:prepare
bun run dev:desktop

Preparation verifies and downloads the TypeScript snapshot, Runtime and helpers
matching the source's SDK SHA, without initializing private submodules. Select a
desktop release kit with bun run dev:prepare --release vX.Y.Z; its client SHA
must match source. Interrupted downloads resume; desktop launch rechecks cached
bytes. Browser-only development uses bun run dev:frontend.
See public development kits.

SDK source and delivery

With private SDK access, use bun run prepare:worktree:dev, then
bun run dev:desktop:source for SDK watching and Runtime rebuilding. Keep the
default directory on master for debugging; use isolated OWT worktrees for
changes and release tags for reproducible product versions.

Online installers contain the shell and standalone bootstrap. First launch
downloads Runtime, frontend, helpers and embedding resources concurrently.
Offline installers include the same complete platform resources and Windows
offline WebView2. Updates download shell and resources together, replace the shell
first, then install resources. The bootstrap supports retry and offline import.

Architecture and repository layout

flowchart LR
  UI["SvelteKit interface"] -->|"Typed SDK client"| Host["Thin Tauri host"]
  Host -->|"Authenticated loopback HTTP / SSE"| Runtime["Supervised SDK Runtime"]
  Host --> Native["Native windows, tray, dialogs, updater"]
  Runtime --> Data["Configuration, conversations, memory"]
  Runtime --> Tools["Providers, tools, MCP, plugins"]

The host remains thin; runtime state machines and durable data belong to the SDK. The public frontend and host can be contributed to separately, and Runtime source changes need the pinned private dependencies.

Contribute

Read AGENTS.md and the applicable subsystem skill before editing. Repository changes use isolated OWT worktrees: preserve the default checkout on local master, implement and verify in a task worktree, then fast-forward the verified result back. Inspect the complete diff, stage intended files, and run bun run preflight before a Conventional Commit.

Update the primary owner documentation when behavior changes. Visible desktop changes also require the matching real-window native black-box scenario. SDK and plugin changes follow their own repository instructions before the parent gitlink is advanced.

For runtime model checks, use the SDK-owned instructions and .env.example. bun run test:sonar runs the host and SDK test gates before submitting analysis to the locally configured SonarQube instance.

License

OpenAgent is available under GPL-3.0-or-later, with a separate commercial licensing option. Commercial rights require a written agreement. The project name and branding are covered by TRADEMARKS.md.