AGNT
The local-first agent operating system for workflows, goals, memory, plugins, subagents, evals, and self-improving AI work.
Chat when you need judgment. Use workflows when you need repeatability. Set goals when you want AGNT to keep working. Delegate when work should happen in parallel.
๐ Website ยท
๐ฅ Download ยท
๐ง What is AGNT? ยท
๐งฉ Runtime model ยท
โจ Features ยท
๐ฆ Install ยท
๐ API Docs ยท
๐ Plugins ยท
๐ฌ Discord
---
## ๐ง What is AGNT?
AGNT is a **local-first agent operating system**: a desktop app and self-hostable backend for building, running, evaluating, and evolving AI work.
It brings agents, workflows, goals, tools, memory, plugins, evals, traces, messaging, and APIs into one local workspace.
That is the product: **AI work becomes durable, inspectable, repeatable, and improvable.**
---
## ๐ฅ Download AGNT
Pre-built desktop apps for Windows, macOS, and GNU/Linux. No build step, no terminal.
Or run it yourself: build from source ยท Docker ยท all install options
---
## ๐ผ๏ธ Screenshots
---
## โก The short version
AGNT gives you:
- ๐ค **Agents** โ memory, tools, skills, providers, and streaming chat.
- ๐งฉ **Workflows** โ 60+ nodes, triggers, branches, checkpoints, and nesting.
- ๐ฏ **Goals** โ plan, execute, evaluate, re-plan, pause, resume, and revert.
- ๐ฅ **Subagents** โ delegate across agents, workflows, async tools, MCP, plugins, APIs, and parallel branches.
- ๐ฃ **Event automation** โ Telegram, Discord, Slack, email, Gmail, webhooks, schedules, Zapier, and custom APIs.
- ๐ง **Memory + insights** โ facts, preferences, corrections, bottlenecks, patterns, and tool choices.
- ๐งฌ **SkillForge** โ turn execution traces into better reusable skills.
- ๐ **Plugins** โ `.agnt` packages with tools, triggers, widgets, hot reload, and marketplace distribution.
- ๐ ๏ธ **Local API** โ port `3333` for agents, workflows, goals, tools, files, plugins, MCP, skills, insights, and executions.
- โก **Real-time UX** โ SSE streams and Socket.IO updates.
- ๐๏ธ **Local-first storage** โ SQLite plus filesystem data you control.
- ๐ง **Provider freedom** โ OpenAI, Anthropic, Gemini, Grok, Groq, Cerebras, DeepSeek, OpenRouter, Together, Kimi, MiniMax, Z.AI, local CLI auth, and custom endpoints.
- ๐ฅ๏ธ **Run anywhere** โ desktop, Docker, headless server, VPS, homelab, Raspberry Pi, local files, CLIs, browser automation, MCP, and custom APIs.
---
## โก Quick start
```bash
git clone https://github.com/agnt-gg/agnt.git
cd agnt
npm install
cd frontend && npm install && cd ..
npm start
```
For development with frontend hot reload:
```bash
# Terminal 1
cd frontend
npm run dev
# Terminal 2
npm start
```
The local backend runs on:
```text
http://localhost:3333
```
---
## ๐งญ Choose your install path
| You want to... | Use this |
| -------------------------------------------- | -------------------------------------------- |
| Try AGNT locally | `npm install` then `npm start` |
| Develop the UI/backend | Vite dev server + Electron/backend |
| Run AGNT as a local server | Build frontend, then `npm start` |
| Self-host on a VPS, homelab, or Raspberry Pi | Docker |
| Build plugins | Clone repo + `backend/plugins/dev` templates |
| Script AGNT from other tools | Local API at `http://localhost:3333/api` |
Most developers should start with the Quick start above, then use Docker or headless mode once they know how they want to run AGNT.
---
## โ
Does AGNT fit your use case?
Use AGNT if your work needs:
- ๐ฅ events that trigger AI work
- ๐ repeatable automations
- ๐ฏ long-running objectives
- ๐ฅ delegated work across agents, tools, APIs, and workflows
- ๐ง memory across runs
- ๐ inspectable traces, costs, outputs, and decisions
- ๐ custom tools, plugins, MCP, or provider auth
- ๐ฅ๏ธ local or self-hosted ownership
Probably not if you only need:
- ๐ฌ a hosted chatbot
- ๐งช a prompt playground
- โ๏ธ a SaaS-only automation tool
- ๐ข public multi-tenant hosting for unrelated organizations
- ๐ช a zero-config cloud product with no local data, APIs, plugins, or providers
---
## ๐ How AGNT compares
AGNT overlaps with agent frameworks, workflow tools, plugin ecosystems, and self-improving skill systems. Its strength is the union.
| If you are comparing AGNT to... | The difference |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hermes Agent** | Hermes is a narrower autonomous-agent framework. AGNT can run the same single-agent style of work, then go further: multi-agent systems, visual workflows, long-running goals, plugins, evals, traces, dashboards, provider management, APIs, messaging triggers, custom tools, local memory, and local-first persistence. |
| **OpenClaw** | OpenClaw focuses on CLI-driven tool use. AGNT includes tool use, then adds a desktop app, local backend, visual workflows, goals, plugins, evals, dashboards, provider management, messaging triggers, MCP, custom APIs, and persistent local state. |
| **n8n / Zapier** | AGNT has visual automation, but also persistent agents, memory, goals, SkillForge, MCP, provider auth, local traces, custom APIs, and plugin-native AI execution. |
| **LangChain / AutoGen / CrewAI** | AGNT is not just a framework. It includes the desktop UI, local backend, workflow canvas, goals, plugins, storage, dashboards, and runtime APIs. |
| **OpenWebUI / chat apps** | AGNT has chat, but chat is only one execution mode. Workflows, goals, tools, plugins, memory, and evals are first-class. |
| **Claude Code / coding agents** | AGNT can work with local projects and tools, but also orchestrates workflows, messaging triggers, custom APIs, dashboards, skills, and long-running goals. |
Other tools cover fragments of the stack. **AGNT is the full local-first agent operating system.**
---
## ๐ฆ Installation
### โ
Prerequisites
- Node.js 18+
- npm 9+
- Git
### ๐ Quick install from source
```bash
git clone https://github.com/agnt-gg/agnt.git
cd agnt
npm install
cd frontend && npm install && cd ..
npm start
```
### ๐งโ๐ป Development mode
```bash
# Terminal 1: frontend dev server with Vite HMR
cd frontend
npm run dev
# Terminal 2: Electron app and backend on port 3333
npm start
```
### ๐ญ Production mode
```bash
cd frontend && npm run build && cd ..
npm start
```
## ๐ณ Docker install
Use Docker for an isolated self-hosted deployment.
> **Docker snap users on Linux:** If you installed Docker via snap, set `AGNT_HOME` with an absolute path, for example `AGNT_HOME=/home/username docker compose up -d`, to avoid snap home directory isolation issues.
> **Updating an existing Docker deployment:** `docker compose up -d` alone does not always fetch a newer image when the tag already exists locally. Run `docker compose pull` first, or use `docker compose up -d --pull always`.
### ๐ฅ Pull pre-built images from GHCR
```bash
# Full image with browser automation, about 1.5GB
docker run -d \
--name agnt \
-p 3333:3333 \
-v agnt-data:/app/data \
ghcr.io/agnt-gg/agnt:latest
# Visit http://localhost:3333
```
Available tags:
- `latest`: latest release with browser automation
- `0.6.6`: specific version
- `0.6`: latest patch on that minor line
### ๐๏ธ Build the Docker image from source
```bash
git clone https://github.com/agnt-gg/agnt.git
cd agnt
docker-compose up -d
# Or use the Makefile
make run
```
๐ See [Self-Hosting Guide](docs/SELF_HOSTING.md) for complete Docker setup.
---
### ๐ฅ๏ธ Headless / $5 VPS / Raspberry Pi mode
AGNT can run without the Electron desktop shell. In headless mode the Express backend serves the built Vue frontend and the local API from port `3333`, so you can run AGNT on a homelab box, a Raspberry Pi, a small cloud VM, or a low-cost VPS.
AGNT ships one Docker image with the full feature set, including Chromium for web scraping and browser automation.
Recommended small-server targets:
| Target | Recommendation |
| -------------------------- | ------------------------------------------------- |
| VPS | 2 vCPU, 2GB RAM, Ubuntu 22.04/24.04 |
| Raspberry Pi 5 | 8GB RAM recommended, 64-bit OS |
| Raspberry Pi 4 | 4GB minimum, 8GB preferred, 64-bit OS |
| Mini PC / NUC / old laptop | 4GB+ RAM |
For Raspberry Pi, use a **64-bit OS** such as Raspberry Pi OS 64-bit or Ubuntu Server arm64. SSD storage is strongly preferred over a microSD card for always-on use. The image is multi-arch, so `ghcr.io/agnt-gg/agnt:latest` runs on ARM64 devices too.
```bash
# On a fresh Ubuntu VPS, homelab server, or Raspberry Pi OS 64-bit install
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
# Create persistent data directories
mkdir -p ~/.agnt/data ~/.agnt/logs
# Run AGNT headlessly on port 3333. AGNT_TENANT_OWNER is the email you sign in
# to AGNT with: a container is reachable from the network, so it admits only
# the accounts you name and refuses to start until one is. Secrets are
# generated on first boot and kept under ~/.agnt/data/secrets โ do not set them.
docker run -d \
--name agnt \
--restart unless-stopped \
-p 3333:3333 \
-e NODE_ENV=production \
-e AGNT_TENANT_OWNER=you@example.com \
-v "$HOME/.agnt/data:/app/data" \
-v "$HOME/.agnt/logs:/app/logs" \
ghcr.io/agnt-gg/agnt:latest
```
Teammates: add `-e AGNT_TENANT_MEMBERS=a@example.com,b@example.com`. See
[docs/SELF_HOSTING.md](docs/SELF_HOSTING.md) for compose, secrets and updates.
Then open:
```text
http://YOUR_SERVER_IP:3333
```
For public internet deployments, put AGNT behind HTTPS with a reverse proxy, Cloudflare Tunnel, Tailscale, or another access layer you control. Do not leave production secrets as `CHANGE_ME_IN_PRODUCTION`. On very small machines, add swap.
You can also run headless from source:
```bash
git clone https://github.com/agnt-gg/agnt.git
cd agnt
npm install
cd frontend && npm install && npm run build && cd ..
PORT=3333 npm run dev
```
`npm run dev` starts `node backend/server.js`; if `frontend/dist` exists, the backend serves the web UI as well as the API.
---
## โญ Star history
---
## ๐งฉ The runtime model
AGNT is built around three execution modes.
| Mode | Use it when | What AGNT provides |
| ------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Agents** | You need judgment, language, reasoning, tool use, or collaboration. | Persistent chat, memory, tools, skills, streaming, traces, token and cost accounting. |
| **Workflows** | You need repeatable automation. | A visual DAG engine, triggers, 60+ nodes, checkpoints, versioning, nested workflows, live status. |
| **Goals** | You need an objective pursued over time. | Planning, task decomposition, execution, evaluation, re-planning, pause/resume/revert, golden standards. |
The three modes are designed to feed each other.
A chat can delegate to a tool. A workflow can call an agent. A goal can run tasks, evaluate results, and use the traces to improve a skill. A plugin can add new capabilities to every layer. A dashboard can display the outputs. The local API can drive it all from outside the UI.
---
## ๐ฅ Delegation graphs: AGNT's subagent model
AGNT supports subagent-style delegation natively.
A delegated workstream in AGNT can be:
- another AGNT agent
- a goal task assigned to a specialized agent
- a workflow branch running in parallel
- a nested workflow
- an async background tool run
- a plugin tool
- an MCP tool
- a Telegram, Discord, Slack, email, webhook, or scheduled trigger
- a custom API call
- a human approval step
- an evaluation step
Example:
```text
Goal: launch a product announcement
โโ Research agent gathers source material
โโ Copy agent drafts messaging
โโ Design workflow creates visuals
โโ Engineering agent edits files
โโ QA agent reviews output
โโ Evaluation node scores the result
โโ SkillForge extracts reusable lessons
```
AGNT does not stop at spawning workers. Every workstream can have durable execution records, local database state, tool-call traces, token and cost accounting, retries, pause/resume/revert, human approval gates, memory extraction, skill evolution, plugin access, dashboard visibility, and API access.
That is the difference between a single autonomous agent and an agent operating system.
---
## ๐ฏ Why AGNT exists
AI agents fail when they are trapped in disposable chats.
They need durable state, trusted tools, repeatable workflows, memory, evaluation, provider access, human approval, plugins, and a runtime that can keep working after the chat ends.
AGNT supplies that runtime.
### ๐ Local-first by design
Agents, workflows, goals, skills, traces, insights, provider settings, plugins, and dashboards live under your AGNT data directory unless you explicitly publish, sync, or call an external service.
### ๐งฌ Extensible and self-improving
AGNT can install, build, AI-generate, hot reload, share, or keep private agents, workflows, tools, widgets, plugins, skills, evals, marketplace items, and MCP servers.
Every run can become reusable signal:
```text
messages + tool calls + costs + errors + outputs + evals โ insights โ memory โ skills
```
---
## ๐งฑ Core building blocks
- ๐ค **Agents** โ persistent AI workers.
- ๐งฉ **Workflows** โ visual DAG automations.
- ๐ฏ **Goals** โ autonomous objectives.
- ๐ง **Skills** โ reusable instructions.
- ๐ **Plugins** โ packaged extensions.
- ๐ **Widgets** โ custom dashboards.
- ๐งช **Experiments** โ eval and benchmark runs.
- ๐ก **Insights** โ extracted lessons and memory.
- ๐ **MCP servers** โ external tool providers.
---
## ๐ ๏ธ The Forge system
Create core assets with AI:
- ๐ค **Agent Forge** โ agents from natural language
- ๐งฉ **Workflow Forge** โ complete workflow graphs
- ๐ ๏ธ **Tool Forge** โ custom tools
- ๐ **Widget Forge** โ HTML/CSS/JS dashboards
- ๐ **Plugin Forge** โ scaffolded `.agnt` plugins
- ๐งฌ **SkillForge** โ skills from execution traces
AGNT is not just where agents run. It is where the workspace helps build itself.
---
## โจ Feature map
- ๐ง **Memory and learning** โ facts, preferences, corrections, insights, SkillForge, datasets, and experiments.
- ๐งฉ **Automation** โ visual workflows, triggers, branches, nested workflows, timers, webhooks, and messaging.
- ๐ฏ **Autonomy** โ goals, planning, evaluation, rollback, AGI loop, and review states.
- ๐ **Extensibility** โ plugins, tools, widgets, MCP, custom APIs, and marketplace assets.
- ๐ **Observability** โ traces, tool calls, node events, per-turn cost, queues, and provider health.
- ๐ฅ๏ธ **Runtime** โ desktop, local API, Docker, headless mode, VPS, homelab, and Raspberry Pi.
- ๐ป **Workspace** โ files, code editor, browser automation, media, speech, and dashboards.
- ๐๏ธ **Voice** โ hands-free conversation with barge-in, carried across every chat surface.
- ๐ฑ **Access** โ phone pairing over QR, a PWA shell, and a desktop app that can point at a remote backend.
- ๐ช **Workspaces** โ per-workspace tabs, layouts, chat history, and AI provider, synced across devices.
---
## ๐ฆ Built-in tool library
AGNT ships with 60+ workflow nodes and tool actions before plugins.
### ๐ฌ Triggers
`google-sheets-new-row` ยท `receive-discord-message` ยท `receive-slack-message` ยท `zapier-trigger` ยท `receive-email` ยท `trigger-timer` ยท `webhook-listener`
### โ๏ธ Actions
**Communication:** Discord, Slack, Gmail, Send Email, Twitter/X, Zapier.
**Productivity:** Notion, Google Drive, Google Sheets, Google Slides, Dropbox, GitHub.
**Content and media:** Firecrawl, Unsplash, YouTube, Web Scrape, Web Search, Text-to-Speech.
**Commerce:** Stripe Invoice.
**AI and automation:** multi-provider LLM generation, browser automation, AGNT agent delegation, AGNT API calls, MCP client calls, custom HTTP APIs, Slop Connector, Unturf AI.
### ๐งฎ Utilities
`execute-javascript` ยท `execute-python` ยท `database-operation` ยท `data-transformer` ยท `file-system-operation` ยท `counter` ยท `random-number` ยท `label` ยท `hello-world`
### ๐๏ธ Control flow
`delay` ยท `for-loop` ยท `parallel-execution` ยท `run-workflow`
### ๐บ Display widgets
`audio-preview` ยท `chart-preview` ยท `code-preview` ยท `html-preview` ยท `image-preview` ยท `markdown-preview` ยท `media-preview` ยท `pdf-preview`
Everything installed from the marketplace or built as a plugin extends this library.
---
## ๐ค Supported AI providers
AGNT uses a pluggable provider layer.
| Provider | Example model families | Auth method |
| ----------------- | ------------------------------------------------ | -------------------------------------- |
| **OpenAI** | GPT-4o, GPT-4 Turbo, GPT-3.5, o1, o3 | API key |
| **Anthropic** | Claude 4, Claude 3.5 Sonnet, Claude 3 Opus/Haiku | API key |
| **Google Gemini** | Gemini 1.5/2.0 Pro, Flash, Ultra | API key |
| **Grok AI** | Grok-1, Grok-2 | API key |
| **Groq** | Llama, Mixtral, fast inference models | API key |
| **Cerebras** | Ultra-fast inference models | API key |
| **DeepSeek** | DeepSeek Coder, DeepSeek Chat | API key |
| **OpenRouter** | 100+ routed models | API key |
| **Together AI** | Open source model families | API key |
| **Kimi** | Kimi models, including Kimi Code | API key |
| **MiniMax** | MiniMax models | API key |
| **Z.AI** | Z.AI models | API key |
| **Claude Code** | Claude through local CLI auth | OAuth PKCE / token |
| **OpenAI Codex** | Codex through local CLI auth | Device auth |
| **Gemini CLI** | Gemini through local CLI auth | OAuth loopback / API key / GCP project |
| **Custom** | Any OpenAI-compatible endpoint | Configurable |
Connection health is monitored in real time with cached status and live checks for dashboards and alerts.
---
## ๐๏ธ Architecture
AGNT is a desktop shell, a Vue application, and a local Express runtime backed by SQLite and the filesystem.
```text
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Electron Shell: Windows / macOS / Linux โ
โ Native menus ยท auto-update ยท IPC bridge ยท deep links โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ IPC
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Vue 3 Frontend: Vite โ
โ Terminal UI ยท Workflow Canvas ยท Forges ยท Marketplace ยท Chat โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ HTTP / SSE / WebSocket
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Express Backend: port 3333 โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Agent Runtime โ Workflow Engine โ Goal Engine / AGI Loop โ
โ Orchestrator โ SkillForge โ Evolution Engine โ
โ Plugin Loader โ MCP Client โ Provider Auth Dispatcher โ
โ Async Tools โ Email Listener โ Webhook Dispatcher โ
โ Filesystem โ Speech Service โ Version Service โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ SQLite: agents ยท workflows ยท goals ยท memories ยท skills โ
โ insights ยท versions ยท executions ยท traces ยท providers โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
### ๐ Local API surface
The backend mounts a broad local API. Important route families include:
| Prefix | Responsibility |
| --------------------------------------------------------------------- | ----------------------------------------------------------- |
| `/api/agents` | Agent CRUD, chat, runtime surfaces. |
| `/api/orchestrator` | Universal chat/orchestration streams. |
| `/api/workflows` | Workflow CRUD, start/stop/status. |
| `/api/executions` | Workflow execution records. |
| `/api/goals` | Goals, autonomous execution, evaluation. |
| `/api/tools` and `/api/tool-schemas` | Tool discovery, schemas, execution metadata. |
| `/api/providers` and `/api/models` | Provider auth, connected apps, model metadata. |
| `/api/plugins` | Plugin install, uninstall, reload, local marketplace flows. |
| `/api/mcp` | MCP server management and capability discovery. |
| `/api/skills`, `/api/skillforge`, `/api/experiments`, `/api/insights` | Skill, evolution, evaluation, and learning systems. |
| `/api/filesystem`, `/api/images`, `/api/local-file`, `/api/speech` | Local media and system services. |
| `/api/webhooks`, `/api/email-listeners` | External triggers. |
| `/api/stream` | Stream engine endpoints. |
The result is simple: what the UI can do, other local tools can often script.
---
## ๐ฅ Who AGNT is for
AGNT is built for trusted local workspaces.
Good fits:
- โ
single users running AGNT on a personal machine
- โ
families sharing a backend across household devices
- โ
small teams of 2 to 10 people sharing one workspace
- โ
developers who want a local agent backend they can inspect and extend
- โ
automation builders who need visual workflows plus AI judgment
- โ
power users who want durable agents instead of throwaway chats
Bad fits:
- โ public multi-tenant SaaS
- โ hosting unrelated organizations on one shared instance
- โ large enterprises with 50+ concurrent users
- โ zero-trust tenant isolation requirements
AGNT uses SQLite and real-time broadcast sync. It is excellent for a trusted workspace. It is not designed to isolate thousands of unrelated organizations.
---
## ๐๏ธ Data directory structure
AGNT chooses a data directory based on how it is running.
| Run mode | Data directory |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| Electron desktop on Windows | `%APPDATA%\AGNT\Data\` |
| Electron desktop on macOS | `~/Library/Application Support/AGNT/Data/` |
| Electron desktop on Linux | `~/.config/AGNT/Data/` |
| Docker | `/app/data` inside the container, usually mounted from `${AGNT_HOME:-$HOME}/.agnt/data` |
| Direct clone with `npm start` | `~/.agnt/data/`, override with `AGNT_HOME` |
Important paths:
- `/agnt.db`: SQLite database.
- `/plugins/installed/`: installed plugins.
- `/_logs/`: logs for Electron and direct clone.
- `${AGNT_HOME:-$HOME}/.agnt/logs/`: Docker logs.
Electron keeps a few historical files one level up at `%APPDATA%\AGNT\`, including `mcp.json`, `code-settings.json`, `projects/`, and `_logs/`.
---
## ๐ Environment and secrets
Copy the example environment file before running Docker or production setups.
```bash
cp .env.example .env
```
Optional location overrides:
```env
# Override default data location
# AGNT_HOME=/home/youruser
# Docker only, normally set by docker-compose.yml
# APP_PATH=/app
```
Secrets are generated per install on first boot and stored under the data
directory; there is nothing to set. In particular, do **not** put a random
`JWT_SECRET` in `backend/.env` on a desktop or `npm start` install: that
install verifies session tokens locally against the issuer's key, so any
other value rejects every sign-in. A placeholder value such as
`CHANGE_ME_IN_PRODUCTION` stops the backend from starting at all.
Generate secure values with:
```bash
openssl rand -base64 32
```
See `.env.example` for provider keys, OAuth settings, and plugin configuration.
---
## ๐๏ธ Building for distribution
```bash
# Current platform
npm run build
# Platform-specific builds
npm run build:win
npm run build:mac
npm run build:linux
# All platforms
npm run build:all
```
---
## ๐ข Releasing a new version
AGNT uses tag-driven releases. Pushing a version tag triggers CI to build and publish multi-arch Docker images to `ghcr.io/agnt-gg/agnt`.
```bash
# Patch release, for example 0.6.1 to 0.6.2
npm run release:patch
# Minor release, for example 0.6.1 to 0.7.0
npm run release:minor
# Major release, for example 0.6.1 to 1.0.0
npm run release:major
```
Each command updates `package.json`, creates a commit, creates an annotated version tag, and pushes the commit plus tag.
Before releasing, commit all code changes. `npm version` requires a clean working tree.
Docker users update with:
```bash
docker compose pull
docker compose up -d
```
If you track mutable tags such as `latest`, pull before restarting so Docker checks GHCR for the newest image.
---
## ๐ Plugin development
AGNT plugins are `.agnt` packages: ZIP archives with a manifest, code, bundled dependencies, and optional assets. They can add tools, triggers, widgets, integrations, and workflow nodes.
Reference templates live in `backend/plugins/dev/`, including Discord, Slack, Gmail, GitHub, Notion, Stripe, Twitter/X, YouTube, Dropbox, Google Drive, Google Sheets, Google Slides, OpenWeatherMap, Plaid, Firecrawl, Unsplash, Calculator, Dice Roller, and more.
### ๐ Minimal plugin manifest
```json
{
"name": "my-awesome-plugin",
"version": "1.0.0",
"description": "Does something useful inside AGNT",
"author": "Your Name",
"tools": [
{
"type": "awesome-tool",
"entryPoint": "./awesome-tool.js",
"schema": {
"title": "Awesome Tool",
"category": "action",
"description": "Performs an operation",
"parameters": {
"input": {
"type": "string",
"description": "Input value"
}
}
}
}
]
}
```
### ๐งฉ Minimal tool implementation
```javascript
class AwesomeTool {
async execute(params, inputData, workflowEngine) {
return {
success: true,
result: `Processed: ${params.input}`,
error: null,
};
}
}
export default new AwesomeTool();
```
### ๐ ๏ธ Build and install
```bash
cd backend/plugins
node build-plugin.js my-awesome-plugin
```
The build produces `my-awesome-plugin.agnt`.
Install through the AGNT UI under Marketplace, or place the package in `/plugins/installed/`. Plugins hot reload without restarting the app.
๐ See [Plugin Development Guide](backend/plugins/README.md).
---
## ๐๏ธ Project structure
```text
agnt/
โโโ ๐ main.js # Electron main process
โโโ ๐ preload.js # IPC bridge
โโโ ๐ package.json # Root config
โ
โโโ ๐ backend/ # Express backend
โ โโโ ๐ server.js # Backend entry point
โ โโโ ๐ src/
โ โโโ ๐ routes/ # 30+ REST route modules
โ โโโ ๐ services/ # Business logic
โ โโโ ๐ orchestrator/ # Chat, tool orchestration, LLM adapters
โ โโโ ๐ workflow/ # Workflow engine and process bridge
โ โโโ ๐ evolution/ # Insights and SkillForge
โ โโโ ๐ tools/library/ # Built-in workflow/tool nodes
โ โโโ ๐ plugins/ # Plugin loader and dev templates
โ โโโ ๐ stream/ # SSE and Socket.IO support
โ โโโ ๐ models/ # SQLite schema and models
โ
โโโ ๐ frontend/ # Vue 3 frontend
โ โโโ ๐ src/
โ โโโ ๐ views/Terminal/ # Main terminal UI
โ โโโ ๐ store/ # Vuex state modules
โ โโโ ๐ services/ # API clients
โ โโโ ๐ canvas/ # Workflow and widget canvas code
โ โโโ ๐ components/ # Shared components
โ
โโโ ๐ build/ # Electron builder resources
โโโ ๐ docs/ # Documentation
โโโ ๐ tests/ # Playwright E2E suites
โโโ ๐ scripts/ # Build helpers
```
---
## ๐งช Testing
```bash
# Full E2E suite
npm run test:e2e
# Specific suites
npx playwright test tests/e2e/agents.spec.js
npx playwright test tests/e2e/workflows.spec.js
npx playwright test tests/e2e/plugins.spec.js
```
๐ See [Testing Instructions](docs/_TESTS_INSTRUCTIONS.md).
---
## ๐ Data and privacy
AGNT is local-first.
Your agents, workflows, goals, skills, traces, insights, executions, provider settings, plugin installs, and dashboard assets live under your AGNT data directory. API keys are stored locally in SQLite or the filesystem. They are sent only to the providers you configure.
Nothing is uploaded unless you explicitly publish a marketplace item, use a remote provider, call an external API, or configure a service that requires network access.
On startup, AGNT logs the resolved data path:
```text
๐ ๐ AGNT data: C:\Users\YourName\AppData\Roaming\AGNT\Data (source: electron)
```
---
## ๐ Documentation
| Document | Description |
| ------------------------------------------------------------- | ------------------------------------------ |
| [๐ API Documentation](docs/_API-DOCUMENTATION.md) | Local and remote REST API reference. |
| [๐จ Build Instructions](docs/_BUILD-INSTRUCTIONS.md) | Detailed build guide. |
| [๐ง GNU/Linux Build Guide](docs/_LINUX-BUILD-INSTRUCTIONS.md) | GNU/Linux-specific setup. |
| [๐ณ Self-Hosting Guide](docs/SELF_HOSTING.md) | Docker deployment and hosting. |
| [๐ Plugin Development](backend/plugins/README.md) | Creating custom plugins. |
| [๐ง Rebuild Guide](docs/_REBUILD-INSTRUCTIONS.md) | Native module rebuilding. |
| [๐ CI/CD Pipelines](docs/CI_CD.md) | GitHub Actions workflows. |
| [๐งช Testing Instructions](docs/_TESTS_INSTRUCTIONS.md) | E2E test setup. |
| [๐ค Contributing](CONTRIBUTING.md) | How to contribute, and what we cannot take. |
| [๐ Security Policy](SECURITY.md) | Reporting a vulnerability privately. |
---
## ๐ค Contributing
Contributions are welcome. Please read
**[CONTRIBUTING.md](./CONTRIBUTING.md)** first โ it will tell you, before you
spend an evening on something, whether it is likely to be merged.
Two things worth knowing up front:
- **Found a security vulnerability?**
[Report it privately.](https://github.com/agnt-gg/agnt/security/advisories/new)
Please do not open a public issue or pull request โ see
[SECURITY.md](./SECURITY.md).
- **We do not accept outside pull requests for authentication, sessions, or
credential handling.** A standing policy about the category, not a judgment
on any submission. The paths and the reasoning are in
[Restricted areas](./CONTRIBUTING.md#restricted-areas). Report the bug
instead and we will fix it, with credit to you.
Everything else:
1. Fork the repository.
2. Create a feature branch: `git checkout -b feature/amazing-feature`.
3. Commit your changes: `git commit -m 'feat: add amazing feature'`.
4. Push the branch: `git push origin feature/amazing-feature`.
5. Open a Pull Request.
Guidelines:
- Follow existing code style.
- Use ES modules and async/await on the backend.
- Use Vue Composition API patterns on the frontend where appropriate.
- Write tests for new behavior.
- Update docs when the surface changes.
- Keep commits atomic and descriptive.
If you are unsure whether an idea touches a restricted area, open an issue and
ask before you write the code.
---
## ๐ License
AGNT is source-available, not open source, under the [AGNT Community Core License](./LICENSE.md).
It is free for personal use, education, nonprofits, and businesses under US$1M revenue and 10 people.
Larger businesses need a paid license. Paid setup, services, and resale require a Certified Partner
license, and white-label, OEM, or hosting for others requires an Enterprise agreement. The table at
the top of the license shows what you can and can't do.
Contributions require the [AGNT Contributor Agreement](./CONTRIBUTOR_AGREEMENT.md).
---
## ๐ Acknowledgments
- Desktop shell by [Electron](https://www.electronjs.org/).
- Frontend powered by [Vue.js](https://vuejs.org/).
- Backend by [Express.js](https://expressjs.com/).
- Real-time transport via [Socket.IO](https://socket.io/).
- Audio transcription via [Whisper](https://openai.com/research/whisper).
- Plugin format inspired by VS Code and Figma extension models.
---
If AGNT makes your work easier, please consider giving it a โญ on GitHub!