AGNT: a local-first agent OS that keeps its data in SQLite on your machine

Who AGNT is for, and the problem it addresses

Most agent tooling lives in a hosted control plane. Your prompts, traces and intermediate state sit on someone else's server, and when the vendor changes a model or a pricing tier your workflow changes with it. AGNT takes the opposite position: the README describes it as a local-first agent operating system, and the storage layer is SQLite plus filesystem data. The stated goal is that AI work becomes durable, inspectable, repeatable and improvable.

The audience is specific. It is for engineers who already run agents and have hit the point where a chat transcript is no longer enough: they want a workflow that executes the same way twice, a goal that can be paused and resumed, and a record of which tool an agent chose and why. The README lists agents, workflows, goals, subagents, memory, plugins, evals, traces and a local API as one workspace. That is a broad surface, and it is the main thing to weigh. A team that only needs a single agent with three tools will find most of it unused.

The runtime model: Electron shell, Express backend, SQLite, port 3333

The architecture is visible in the repository layout and the README badges. The desktop app is Electron with a Vue frontend, main.js and preload.js sit at the top level, and the backend is Express. The local API is documented as listening on port 3333, covering agents, workflows, goals, tools, files, plugins, MCP, skills, insights and executions. Real-time updates reach the UI over SSE streams and Socket.IO.

Data flow follows from that. A workflow is a graph of nodes (the README says 60+ nodes, with triggers, branches, checkpoints and nesting). Execution state and traces land in SQLite and on the filesystem, which is what makes the inspectability claim concrete rather than marketing. SkillForge is the part that turns execution traces into reusable skills, so the trace store is not just an audit log; it feeds back into what the agent does next.

The Dockerfile shows one real constraint of this split. The frontend build imports a shared provider descriptor from backend/src/services/ai/descriptor through a Vite alias, so the Docker build stage copies that directory into the image explicitly. The Dockerfile comment states that a spec file fails the build when an alias target is not copied. That is a sensible guard, and it also means the frontend and backend are coupled at build time, not just at runtime.

Installing AGNT from source and running the backend

The README gives a quick start for running from source. Node 18 or newer is required according to the badge. The clone, install and start sequence is:

git clone https://github.com/agnt-gg/agnt.git
cd agnt

npm install
cd frontend && npm install && cd ..

npm start

npm start runs electron ., which opens the desktop app. The postinstall script does real work: it installs Electron app dependencies, patches onnxruntime, rebuilds native modules for Electron and installs git hooks. Expect that step to take a while on the first run.

If you want the backend without the Electron window, the package.json dev script runs node backend/server.js, and the README states the local backend is available at http://localhost:3333. To develop the UI with hot reload, the README suggests two terminals:

# Terminal 1
cd frontend
npm run dev

# Terminal 2
npm start

Before starting anything you intend to reach from another device, copy .env.example to .env. It documents BIND_HOST, which defaults to 127.0.0.1 so a fresh install is not reachable from the network, and AGNT_REMOTE_URL, which points the desktop app at a backend running elsewhere.

Docker install and the security defaults you must change

For a VPS, homelab or Raspberry Pi, the repository ships a Dockerfile and docker-compose.yml. The compose file publishes 3333:3333 and names the image ghcr.io/agnt-gg/agnt:latest. The Dockerfile is a multi-stage Node 20 Alpine build that the file header describes as roughly 1.5GB because it includes Chromium for Puppeteer browser automation.

docker compose up -d

The compose file is unusually candid about its own defaults. It ships JWT_SECRET, SESSION_SECRET and ENCRYPTION_KEY set to CHANGE_ME_IN_PRODUCTION and tells you to generate real values with openssl rand -base64 32. It also documents a trust-remote-authentication switch that, when enabled, makes routes/Middleware.js call jwt.decode() instead of jwt.verify(), so the token signature is never checked. The comment states plainly that combined with BIND_HOST=0.0.0.0 and a published port this is an unauthenticated remote takeover. The switch is off by default. Treat those three secrets as mandatory before the container is reachable from anywhere.

The compose file also warns against updating with docker-compose down followed by up -d, because Compose will not pick up new images. It points to make update instead. Permission errors on the mounted ~/.agnt directories are handled by creating the directories and chowning them to 1000:1000, as the file shows.

Where AGNT is the wrong tool

The local-first design is the selling point and also the sharpest limitation. Everything the agent knows lives on one machine's SQLite database and filesystem. There is no documented multi-user story, no shared workspace, and no conflict resolution for two people editing the same workflow. If your team needs a shared agent that several people operate at once, this is the wrong shape.

The release cadence is another consideration. The last push to the default branch was on 2026-09-09, and the most recent release listed is v0.6.6 on 2026-08-08, following v0.6.5 and v0.6.4 in July. That is a pre-1.0 project moving quickly. Plugins are distributed as .agnt packages with hot reload and a marketplace, so anything you build against the plugin interface is exposed to that pace.

The Electron packaging is a third cost. The full Docker image is about 1.5GB because Chromium ships inside it. On a Raspberry Pi or a small VPS that is a real constraint, and the README does not document a slim variant without browser automation. Finally, the README describes the model surface as provider freedom across OpenAI, Anthropic, Gemini, Grok, Groq, Cerebras, DeepSeek, OpenRouter, Together, Kimi, MiniMax, Z.AI, local CLI auth and custom endpoints. Fifteen providers is a lot of surface to keep working, and the README does not state which ones are covered by tests.

How AGNT differs from a code-first agent framework

The natural comparison is with code-first frameworks such as LangGraph, where you define an agent graph in Python and run it as a library inside your own service. The difference is where the runtime lives. In LangGraph the orchestration is your program; persistence, retries and observability are things you wire up with external stores. In AGNT the orchestration is the product: a visual workflow canvas, a goal loop that plans, executes, evaluates and re-plans, and a local API on port 3333 that other programs can call.

That trade is worth stating plainly. You get a working UI, a trace store and a plugin marketplace without writing them. You give up the ability to embed the runtime as a library in a service you already operate, because the documented entry points are the Electron app and the Express backend. If your deployment target is a serverless function or a Python codebase, AGNT is not a drop-in.

The other comparison worth making is against hosted agent platforms. Those remove the install and the secret management, and they also remove the SQLite file. AGNT's answer is that you can run it on a homelab or Raspberry Pi and keep the data. That answer only holds if you do the secret setup from the compose file, which is where the platform's convenience advantage actually shows up.

Licence and upgrade cost

package.json declares the license as "Custom - See LICENSE.MD", and the repository's license field is reported as NOASSERTION. That is not an OSI identifier, so you cannot assume the permissions that MIT or Apache-2.0 would grant. Read LICENSE.md before you build a product on top of AGNT or redistribute the .agnt plugin packages. This is a description of what the repository states, not legal advice.

Upgrade cost splits by install path. Desktop users download prebuilt binaries from agnt.gg/downloads, so the cost is the usual Electron app update. Docker users have a documented procedure: the compose file says to use make update rather than down followed by up -d, because Compose will not pull a new image that way. The Makefile is present at the repository root, and docs/SELF_HOSTING.md is referenced for the updating section.

Source users carry the heaviest cost. The postinstall script rebuilds native modules for Electron and patches onnxruntime, so a Node or Electron version bump can break the build in ways that have nothing to do with AGNT's own code. Budget for that on every upgrade, not just major ones.

Editorial conclusion

Adopt AGNT if you want agent runs, workflows and goals stored in SQLite and files on a machine you control, and if you are willing to read the Docker and self-hosting notes before exposing port 3333. Do not adopt it if you need a hosted service with a support contract, or if you expect a stable plugin API across releases. Before installing, read .env.example for BIND_HOST and the JWT_SECRET, SESSION_SECRET and ENCRYPTION_KEY placeholders, and check LICENSE.md, since package.json declares the license as Custom rather than an SPDX identifier.

Frequently asked questions

Official sources

1. agnt-gg/agnt on GitHub
2. Issues
3. Project website
4. README
5. Releases