Nagient

A self-hosted AI agent runtime with controlled tools, pluggable transports, and predictable operations.

Русская версия · User guide · Developer guide · Plugin Hub

Nagient runs an AI agent as an observable service instead of tying it to one terminal session. It keeps configuration, secrets, approvals, logs, updates, and extension lifecycle in one runtime that works on a personal computer or a server.

Capability	What it gives you
Provider freedom	Built-in OpenAI-compatible providers and a stable contract for external providers.
Controlled tools	Bounded filesystem, shell, Git, jobs, configuration, and explicit approval for sensitive actions.
Multiple entry points	CLI chat, console, webhook, and separately installed transports such as Telegram.
Plugin Hub	Reviewed plugins by short ID, arbitrary Git repositories by URL, isolated dependencies, and visible install status.
Operational runtime	Preflight checks, reconciliation, health state, structured logs, Docker Compose, and tag-driven updates.
Portable core	Python 3.11+, Linux, macOS, Windows, Docker, and process plugins written in any language.

---

Quick Install

Linux and macOS

curl -fsSL https://ngnt-in.ruka.me/install.sh | bash
nagient setup

Windows PowerShell

irm https://ngnt-in.ruka.me/install.ps1 | iex
powershell -ExecutionPolicy Bypass -File "$HOME/.nagient/bin/nagient.ps1" setup

Docker Compose on a server

git clone https://github.com/KOSFin/nagient.git
cd nagient
cp .env.example .env
${EDITOR:-vi} .env
docker compose up -d
docker compose exec nagient nagient status

Docker is optional for a source checkout on a personal computer:

bash scripts/install-local.sh --source .
export PATH="$HOME/.nagient/bin:$PATH"
nagient setup

Read the installation guide for supported layouts or the server deployment guide for the complete Compose flow.

---

Getting Started

nagient setup       # choose a provider and configure the runtime
nagient chat        # start a direct CLI conversation
nagient preflight   # validate configuration and plugins
nagient up           # start the managed runtime
nagient status       # inspect health and activation state
nagient logs         # inspect recent runtime logs

Use nagient paths to resolve runtime aliases such as @config, @secrets, @plugins, and @workspace.

---

Plugin Hub

Telegram and GitHub API integrations are independent plugins, not copies embedded in the core package. Run the installer without arguments to browse verified plugins and see what is already installed:

nagient plugin install

Install a verified plugin by short ID:

nagient plugin install nagient.telegram
nagient plugin install nagient.github_api

Or install any compatible Git repository directly:

nagient plugin install https://github.com/owner/nagient-plugin.git

Verified plugin	Type	Repository	Install command
Telegram Transport	Transport	Source and configuration	nagient plugin install nagient.telegram
GitHub API Tool	Tool	Source and configuration	nagient plugin install nagient.github_api
Plugin Template	Starter	Create a new plugin	Use the repository template

The Plugin Hub guide covers discovery, installation, configuration, updates, trust, and Docker deployment.

---

How It Fits Together

flowchart LR
    U[CLI or transport] --> R[Nagient runtime]
    R --> P[Model provider]
    R --> A[Approval policy]
    A --> T[Built-in tools]
    A --> X[External plugins]
    R --> S[State and logs]

Loading

The runtime discovers providers, transports, and tools from manifests. External plugins remain under ~/.nagient, so their release cycle and dependencies stay separate from the core.

---

Documentation

Everything is available in English and Russian. Start with the path that matches what you are trying to do.

Section	Article	What it covers
Start here	User guide	The shortest path from installation to a working agent.
Start here	Installation and updates	Hosted installer, local runtime, upgrade, and removal.
Start here	Server deployment	Complete env-only Docker Compose setup.
Use Nagient	Commands and daily operations	CLI commands, chat, status, diagnostics, and lifecycle.
Use Nagient	Configuration and secrets	Runtime files, profiles, aliases, tools, and secret handling.
Use Nagient	Environment variable reference	Installer, Compose, provider, transport, and plugin variables.
Use Nagient	Troubleshooting	Startup, provider, plugin, Docker, and update failures.
Plugins	Plugin Hub and verified catalog	Find, install, configure, update, and remove plugins.
Plugins	Plugin guide for operators	Personal computer and Docker installation workflows.
Build plugins	Developer guide	Entry point for contributors and plugin authors.
Build plugins	Build your first plugin	Template, manifests, packaging, validation, and publishing.
Build plugins	Plugin contracts	Python and process runtime protocols.
Build Nagient	Architecture	Boundaries, dependency policy, runtime flow, and security.
Build Nagient	Testing and CI	Local checks and test layers.
Project	Contributing	Development workflow and contribution rules.
Project	Changelog	Release history and notable changes.

Russian readers can use the complete Russian documentation index.

---

License

Nagient is released under the MIT License.