Open Vetta

An open-source desktop AI agent for real work — local-first, extensible, and under your control.

English · 简体中文 · Download · Get started · Discussions · Discord · Contributing

Open Vetta brings models, project files, local tools, and reusable capabilities into one desktop workspace. Use it for coding, documents, data, research, creative work, and repeatable workflows without giving up control of the environment where the work happens.

It is more than a chat interface: Vetta can inspect a workspace, use tools with visible permission boundaries, produce real files, and keep the execution trail available for review.

Open Vetta desktop workspace

Why Open Vetta

	What it means
Local-first workspace	Projects, sessions, files, and execution live in the environment you choose.
Bring your own models	Connect supported providers, OpenAI-compatible endpoints, or local inference through BYOK.
Real tools and artifacts	Work with code, documents, spreadsheets, media, commands, and generated files in one task flow.
Reviewable execution	Tool calls, plans, permissions, progress, results, and recovery paths remain visible.
Reusable workflows	Extend the agent with skills, MCP servers, plugins, themes, knowledge, batch tasks, and automation.
Open client stack	The desktop app, CLI, SDK, plugin system, themes, mobile client, and IM gateway are developed in this repository.

Start here

I want to…	Start with
Use the desktop app	Download for macOS, Windows, or Linux, then follow installation and first setup.
Complete a real task	Follow the first-task walkthrough.
Understand the product	Read the product guide and security and data boundaries.
Build an extension	Choose between skills, MCP, plugins, themes, SDK, RPC, and CLI.
Contribute code	Read `QUICKSTART.md` and `CONTRIBUTING.md`.

Run from source

Requires Bun 1.3+ and Node.js 20+.

git clone https://github.com/openvetta/open-vetta.git
cd open-vetta
git switch dev
bun install
cd apps/desktop
bun run dev

The development app uses ~/.vetta-dev by default, keeping installed-app data in ~/.vetta untouched. Root-level bun run dev watches core libraries; it does not launch Electron. See QUICKSTART.md for the complete setup and validation commands.

What you can do

Work in projects and sessions. Keep task history, files, context, artifacts, and execution details together.
Use local and external tools. Run commands, inspect files, connect MCP services, and approve sensitive operations explicitly.
Handle professional artifacts. Preview and work with source code, PDF, Office files, spreadsheets, images, audio, video, SVG, and generated UI.
Scale a proven task. Run the same workflow across directories with batch tasks, or schedule it as an automation.
Reuse organizational knowledge. Build local knowledge bases and install reusable skills or scenarios.
Keep working away from the desk. Use supported IM bridges, webhooks, notifications, quick entry, and native desktop integrations.

The public documentation has the current task guides and screenshots: browse all product capabilities.

Extension model

Vetta exposes several extension levels so a simple workflow does not need to become a full plugin:

Extension	Use it for	Guide
Skill	Teach the agent a repeatable method or domain workflow.	Abilities
MCP	Connect external tools and data over a standard protocol.	MCP connectors
Plugin	Extend the desktop UI, files, messages, tools, and host actions.	Plugin development
Theme	Replace the visual system and provide theme-specific pages.	Theme development
SDK / RPC / CLI	Embed or drive the agent from another application or process.	Developer paths

Build a plugin from any directory

You do not need this repository, or a Vetta source checkout, to build a plugin. Nor does an agent:

npx @vetta-org/plugin-cli init --id my-plugin --name "My Plugin"
cd my-plugin && npm install
npx vetta-plugin-cli docs        # where the manual is, and which SDK version it documents
npm run install:vetta            # build, package, install into the running desktop app
npx vetta-plugin-cli watch       # hot reload: the host loads the plugin from this directory

init also writes an AGENTS.md, so any coding agent — Claude Code, Cursor, or Vetta's own — picks the project up without host-side setup. The plugin manual ships inside @vetta-org/plugin-sdk, so the contract an agent reads is the contract the project compiles against; docs locates it rather than anyone hard-coding a node_modules path.

To publish several abilities from one repository, scaffold a marketplace:

npx @vetta-org/plugin-cli init hub --name my-market \
  --repository https://github.com/me/my-market --min-app-version 0.55.0

That lays down the index, the abilities/ layout, a repository-level AGENTS.md, and CI running vetta-plugin-cli sync --check, which keeps .vetta/marketplace.json reconciled with each ability package. Development commands always act on the nearest ability directory, so working inside a marketplace is identical to working on a standalone plugin.

Plugins declare capabilities in plugin.json; privileged operations are authorized by the host and checked again at runtime. Plugins run inside the desktop renderer and should be treated as curated code, not as an arbitrary-code sandbox. Read the plugin trust and permission model before distributing one.

Data and build modes

A source checkout produces the lite build by default. It has no dependency on a Vetta-operated backend: no account, subscription, remote administration, or hosted marketplace is required. Model requests go to the endpoint you configure, and credentials remain in local credential storage.

Official installers may enable the optional Vetta Serv integration for accounts, subscriptions, and a hosted marketplace. That integration is selected at build time; it is not silently enabled in a lite build.

Local-first does not mean zero network traffic. Model providers, MCP servers, plugins, webhooks, IM integrations, update sources, and optional telemetry can each create their own data boundary. Review:

Repository map

This is a Bun/TypeScript monorepo with additional Swift, Kotlin and Go applications. Dependencies point from applications toward reusable packages; packages/* never depend on apps/*.

Area	Responsibility
`apps/desktop`	Electron desktop host and renderer
`apps/cli-host`	CLI host for the coding agent
`apps/docs-site`	Next.js documentation site published at `docs.openvetta.com`
`apps/mobile/client-apple`	Native iOS client in Swift/SwiftUI (pairs with the desktop over LAN or relay, end-to-end encrypted)
`apps/mobile/client-android`	Kotlin Multiplatform Android client (frozen at protocol v1, kept for reference)
`apps/im-gateway`	Go IM sidecar gateway
`packages/ai` · `packages/agent`	Provider abstraction and the agent loop
`packages/coding-agent` · `packages/runtime-*`	Product composition, runtime contracts, tools, storage, MCP, and host adapters
`packages/plugins` · `packages/themes`	Extension SDKs, presets, and themes

Architecture details and public integration contracts live in the developer documentation and docs/adr/.

Develop and contribute

Use Bun and the repository scripts; do not run bare bun test in this monorepo.

bun run check:quick              # changed-file lint and architecture guards
bun run check                    # full lint, types, and architecture guards
bun run test:pkg <package-name>  # focused package tests
bun run test:changed             # tests affected by the current diff

Pull requests target the dev branch. The contribution map, test expectations, and review bar are in CONTRIBUTING.md. Architecture and Agent collaboration rules are in AGENTS.md.

Questions and early ideas belong in GitHub Discussions. Report vulnerabilities privately through GitHub Security Advisories.

Documentation

The documentation site also publishes llms.txt, llms-full.txt, and a Markdown representation of each page for Agent consumption.

Community

Join the Open Vetta Discord to ask questions, share workflows, skills, plugins and themes, follow release news, and talk to the maintainers.

https://discord.gg/qGqkk22Vg9

Longer, searchable threads still belong in GitHub Discussions, and vulnerabilities go through GitHub Security Advisories — please do not report them on Discord.

Credits and license

Open Vetta builds on work from the wider open-source ecosystem, including pi, Codex CLI, MCP, Electron, React, Bun, models.dev, and the projects listed in NOTICE. The complete third-party inventory and original notices live there.

Licensed under Apache-2.0.

Friends & Links: LINUX DO - A Chinese community for technology enthusiasts. This project is linked with and endorsed by LINUX DO.

open-vetta

Links

README