The Problem

Teams building AI‑driven agents need a self‑hosted runtime that can orchestrate LLM calls, manage plugins, and expose a UI without pulling in external SaaS. Maintaining such a stack locally is error‑prone: dozens of plugins, a mixed Vue/React front‑end, and a Node backend that talks to databases, files, and external APIs.

What This Does

The AGNT repo delivers a full‑stack “AI Agent Operating System”.

  • The backend (backend/) is a Node/Express service that loads plugins from backend/plugins/. Core services live under backend/src/ – e.g. backend/src/services/ai/LlmService.js (LLM orchestration) and backend/src/tools/library/BaseAction.js (common action base).
  • The frontend (frontend/) is a Vue 3 SPA compiled into frontend/index.html. UI components such as frontend/src/views/Terminal/CenterPanel/screens/Agents/Agents.vue render agents, workflows, and plugin marketplaces.
  • Plugins are plain Node modules (backend/plugins/dev/*) each exposing a manifest (manifest.json) and entry point (e.g. backend/plugins/dev/ethereum-price-checker/index.js). The marketplace bundles pre‑built .agnt files under backend/plugins/marketplace-default/.

How It Is Wired

Execution starts in backend/server.js (line 269 → deferredInit). The server:

  1. Calls deferredInit → bootstrapBuiltinSkills → creates plugin directories (fs.mkdir).
  2. Registers routes from backend/src/routes/Middleware.js (29 inbound modules).
  3. Instantiates BaseAction (backend/src/tools/library/BaseAction.js), the most‑connected hub (48 importers, instability 0.02).
  4. Plugin loading walks backend/plugins/build-all-plugins.js, which uses PluginManager (backend/src/plugins/PluginManager.js) – part of a circular import with backend/src/models/database/index.js and backend/src/models/WebhookModel.js. Breaking this cycle would reduce build‑time coupling.
  5. When a plugin like Ethereum‑price‑checker runs, its execute function (entry backend/plugins/dev/ethereum-price-checker/index.js:14) calls getValidAccessToken → axios.get (network). The shortest outbound path is execute → getValidAccessToken → axios.get.

The internal call graph shows a few high‑fan‑out functions: fetch (268 callers), getItem (173), dispatch (122). These are defined in utility libraries and are called from many places, so changes ripple widely.

Large files (backend/src/models/database/index.js, backend/src/services/ai/providerConfigs.js, backend/src/services/auth/AuthManager.js) exceed 900 lines, making them hard to review.

The front‑end’s Vue components (Agents.vue, Connectors.vue) contain deep nesting (indentation depth 6) and high branching density (≈ 0.33 branches per line), which hampers readability.

How To Use It

# Clone (preserve the exact URL)
git clone https://github.com/moses-y/agnt.git
cd agnt

# Install Node deps (lockfile present)
npm ci        # respects package-lock.json

# Prepare environment – copy the example and fill secrets
cp backend/.env.example backend/.env
# edit backend/.env with real JWT_SECRET, SESSION_SECRET, etc.

# Run the server locally
npm run dev   # defined in backend/package.json (starts backend/server.js)

# Build and run the UI (Vue)
cd frontend
npm ci
npm run serve   # serves index.html on localhost:8080

# Or spin up the full stack with Docker (Dockerfile provided)
docker build -t agnt:latest -f Dockerfile .
docker run -p 3000:3000 -p 8080:8080 --env-file backend/.env agnt:latest

If Docker is preferred, the Makefile offers make docker-build and make docker-run targets (verify in the file). No test step is present in the CI workflow; add npm test after installing dev dependencies.

Real‑World Use

A SaaS provider can embed AGNT to let customers run custom data‑extraction agents on‑premises. A CI pipeline would docker build, mount a customer‑specific .env, and expose the UI at /agents. The provider can ship new plugins as .agnt files placed in backend/plugins/marketplace-default/ without touching core code.

Code Health & Issues

Measured static findings (258 total)

  • Import cycles (12 modules) – e.g. backend/src/models/database/index.js ↔ PluginManager.js.
  • Oversized files (9 > 900 LOC) – BaseAction.js, AuthManager.js.
  • Hub modules (10) – BaseAction.js, AuthManager.js have > 40 dependents.
  • High branching density (21 files) – Middleware.js, LlmService.js.
  • Deep nesting (7 files) – Agents.vue, Connectors.vue.
  • Duplicated code blocks (≈ 16 k lines across 410 files) – Discord/Dropbox API helpers.

Code‑Health audit

  • Critical – Rotate and remove committed credentials in backend/.env.
  • High – Untrack .env (already in .gitignore); pin GitHub Actions to commit SHAs; remove the .env from history and replace with an example; add a test step to CI.
  • Medium – Enable Dependabot/Renovate; use npm ci in CI; pin Docker base image by digest; add a dependency‑vulnerability scan gate; install a pre‑commit secret scanner.

No license violations, but the repository ships a custom license file; verify compatibility for downstream use.

The Bottom Line

AGNT provides a complete, extensible AI‑agent runtime with a ready‑made UI and plugin ecosystem, but the codebase suffers from large, tightly coupled modules, committed secrets, and incomplete CI testing. It is suitable for teams that need a self‑hosted platform and are prepared to invest in refactoring, secret management, and CI hardening.