GuardianAgent

Security-first AI agent platform for local LLMs, governed tool use, coding workflows, automations, and personal assistant work.

GuardianAgent is a self-hosted AI assistant and agent orchestration runtime for local AI, managed-cloud, and frontier LLMs. It combines a daily-use Second Brain with guarded power-user surfaces for coding, workstation operations, workflow automation, security, network, and cloud operations. The same assistant is available in web, CLI, and Telegram, with tool approvals, sandboxing, prompt-injection defenses, audit trails, and policy boundaries enforced by the runtime.

Table of Contents

• Product Overview
• Core Capabilities
• Repository Status
• Project Layout
• Documentation
• Security at a Glance
• Getting Started
• LLM Providers
• Configuration
• Development and Verification
• Contributing
• Troubleshooting
• License

Product Overview

GuardianAgent is built for people who want a local AI agent that can do real work without handing unchecked tool access to an LLM. It supports local LLM assistants through Ollama, hosted models through providers such as OpenAI, Anthropic, OpenRouter, NVIDIA Cloud, and Google Gemini, and a governed tool layer for search, coding, automation, integrations, shell-adjacent workflows, and operator tasks.

Unlike a simple chatbot wrapper, GuardianAgent treats tool use as a controlled security boundary. The runtime routes intent through a shared gateway, gates non-read-only actions with approvals, applies sandbox and allowed-path policies, scans for prompt injection and secret leakage, and keeps MCP tools, package installs, browser actions, workspace access, and automations behind explicit guardrails.

Second Brain

Second Brain (#/) is the default web home.

• Today centers the day around agenda, quick capture, priority tasks, briefs, notes, and routines
• Calendar combines synced and local events with assistant-aware planning and follow-up
• Tasks provides a lightweight board for priorities, due dates, and status tracking
• Notes keeps searchable, pinnable, and archivable notes in one place
• Contacts, Library, Briefs, and Routines round out the daily-use memory and upkeep workflow
• Keep daily context separate from the operator and workstation consoles
• Further reading: Second Brain As-Built Design

Today is the default Second Brain landing view for agenda, capture, tasks, briefs, notes, and routines.

Calendar	Tasks
Notes	Routines

Power User Capabilities

• Performance (#/performance) for workstation health, editable profiles, live processes, and reviewed cleanup. See Performance Management Spec.
• Code (#/code) for repo-scoped coding sessions with chat, Monaco editor, diffing, approvals, trust review, session-bound terminals, and workspace-scoped execution. See Coding Workspace Spec.
• Automations (#/automations) for saved and scheduled Guardian workflows and assistant tasks. See Automation Framework Spec.
• Security, Network, and Cloud for alerts, posture, diagnostics, and infrastructure oversight. Start with WebUI Design and SECURITY.md.
• Configuration and Reference Guide for setup, integrations, policy, and operator guidance.

Shared Assistant

• Web, CLI, and Telegram all use the same guarded assistant model
• Local, managed-cloud, and frontier LLM providers are supported, including Ollama, Ollama Cloud, OpenRouter, NVIDIA Cloud, Anthropic, OpenAI, and other OpenAI-compatible providers
• Built-in tools, integrations, memory, and automations stay behind approval and policy controls
• More detail: WebUI Design, Tools Control Plane Design

Screenshots

Second Brain screenshots are shown above in Product Overview. The gallery below covers the remaining major Guardian surfaces.

Security, Network, Cloud, Automations, Configuration, Coding Workspace, and Reference Guide.

Security	Network
Cloud	Automations
Configuration / Providers	Coding Workspace
Reference Guide

Core Capabilities

• Security-first AI agent platform for local, self-hosted, and hybrid LLM workflows
• Local AI and Ollama support alongside OpenAI, Anthropic, OpenRouter, NVIDIA Cloud, Gemini, and other hosted providers
• Governed tool use with approvals, sandboxing, allowed paths, command policy, and audit trails
• Prompt-injection defenses, output scanning, secret redaction, trust-aware memory, and quarantined tool-result reinjection
• AI coding assistant and repo-scoped Coding Workspace with editor, diffs, session-bound terminals, trust review, and verification surfaces
• Daily-use Second Brain for planning, capture, retrieval, calendar-aware context, tasks, notes, people, routines, and briefs
• Workflow automation and scheduled agent runs with bounded authority, run history, and approval-aware execution
• MCP tool security, native integrations, search, browser/workspace tooling, and provider connectors behind the same runtime guardrails
• Shared assistant across Web, CLI, and Telegram
• Specs and architecture docs for deeper implementation detail when you need it

Repository Status

GuardianAgent is a security-focused local-first assistant runtime with several mature product surfaces and several actively evolving control-plane areas.

Historical proposals that have shipped live in docs/implemented/. Completed one-time plans live in docs/archive/. Active specifications live primarily in docs/design/ and docs/architecture/.

Project Layout

GuardianAgent/
├─ src/                    TypeScript runtime, channels, tools, prompts, memory, and orchestration
│  ├─ channels/            Web, CLI, Telegram, and runtime route adapters
│  ├─ runtime/             Intent gateway, orchestration, code sessions, memory, security, automations
│  ├─ tools/               Built-in tools, executor, registry, MCP client, and tool policy surfaces
│  ├─ llm/                 Provider clients, routing, failover, and guarded LLM access
│  ├─ guardian/            Admission, policy, output, and audit security controls
│  └─ search/              Local and provider-backed search integration
├─ web/public/             Browser UI, page modules, chat panel, styles, assets, and vendored UI code
├─ scripts/                Setup scripts, smoke tests, integration harnesses, and packaging helpers
├─ docs/
│  ├─ architecture/        Current architecture and module-boundary guidance
│  ├─ design/              Current product and runtime specifications
│  ├─ guides/              Operator and contributor guides
│  ├─ plans/               Active implementation plans
│  ├─ proposals/           Unshipped or partially scoped future proposals
│  ├─ implemented/         Historical proposals whose core scope has shipped
│  └─ archive/             Retired designs and completed plans
├─ policies/               Security and runtime policy files
├─ skills/                 Bundled skill instructions and workflows
├─ native/windows-helper/  Rust helper for Windows-native host integration and isolation support
└─ build/                  Generated packaging artifacts

Documentation

Start with these documents instead of browsing every file under docs/:

Security at a Glance

GuardianAgent enforces security at the Runtime level — agents cannot bypass it. Every message, LLM call, tool action, and response passes through mandatory chokepoints.

The built-in chat/planner loop runs in a brokered worker process with no network access. Tools, approvals, trust metadata, and LLM API calls are mediated through broker RPC.

Install-like public package-manager actions are also routed through a dedicated managed path. Guardian uses package_install to stage the requested top-level package artifacts, review them before execution, resolve the install working directory through the active workspace or configured allowed paths, and surface caution or blocked findings in the unified security workflow instead of treating package installs as ordinary shell commands.

For the full security architecture, threat model, and configuration details, see SECURITY.md.

Getting Started

Requirements

• Node.js 20 or newer
• A local, managed-cloud, or frontier LLM provider (Ollama, Ollama Cloud, OpenRouter, NVIDIA Cloud, Anthropic, OpenAI, etc.)

SQLite-backed persistence and monitoring are enabled when the Node build includes node:sqlite. Otherwise, assistant memory and analytics run in-memory automatically.

Quick Start

Clone the repository and use the platform start script:

Windows:

.\scripts\start-dev-windows.ps1

Linux / macOS:

bash scripts/start-dev-unix.sh

These scripts handle dependency installation, build, startup, and the initial configuration bootstrap.

For a manual development loop:

npm install
npm run check
npm test
npm run dev

First Run

After startup:

1. Open the web UI and go to the Configuration Center (#/config, usually http://localhost:3000)
2. Add your LLM provider — select Ollama for local models, or add an API key for Ollama Cloud, OpenRouter, NVIDIA Cloud, Anthropic, OpenAI, or another supported external provider.
3. Open Second Brain at #/ to confirm the default daily-home surface is live and the assistant is ready for task, note, calendar, and people workflows.
4. Connect Google Workspace or Microsoft 365 if needed — use Cloud > Connections when you want provider-backed calendar and contacts synced into Second Brain.
5. Review tool policy — defaults to on-request / approve_each for the main assistant, with a read-only shell allowlist. Mutating tools still require approval, and public package-manager installs should go through the managed package_install path instead of shell_safe.
6. Enable optional channels — Telegram bot setup is in Configuration > Integration System > Telegram Channel
7. Set web auth — web access defaults to bearer-protected mode; configure it in Configuration > Integration System > Web Authentication or with CLI /auth ...
8. Open the Coding Workspace if needed — go to #/code for a project-scoped coding workspace with its own session history, trust review, terminals, approvals, and verification surfaces

Most configuration is done through the web UI or CLI commands (/config, /providers, /auth, /tools). Manual config.yaml editing is optional and intended for advanced use.

Using GuardianAgent

GuardianAgent is accessible through three channels:

What you can do:

• Chat with the built-in AI assistant
• Use Second Brain as the default daily home for tasks, notes, people, routines, and calendar-aware planning
• Use Performance, Security, Network, Cloud, and Automations as dedicated operator surfaces instead of burying everything in chat
• Use the Coding Workspace for repository-scoped work with editor, diffing, approvals, checks, trust review, and session-bound terminals
• Run guarded tools, integrations, search, and automation workflows across the same assistant

Approvals and safety: Actions may run automatically, wait for approval, or be denied depending on policy, trust level, and tool risk. For the detailed behavior, see SECURITY.md and Tools Control Plane Design.

Coding Workspace

The web Code page is a dedicated repo-scoped workspace backed by server-owned code sessions. It has its own session context, editor, diffing, approvals, checks, trust review, and session-bound terminals.

Implementation detail and current limitations are documented in docs/design/CODING-WORKSPACE-DESIGN.md.

Telegram Setup

1. Open Telegram, search for @BotFather, press Start, run /newbot
2. Follow prompts for bot name and username (must end with bot), copy the bot token
3. Add the token in Configuration > Integration System > Telegram Channel or through the CLI configuration flow
4. Restrict access with allowed chat IDs
5. Save the channel settings; Telegram changes hot-reload when the token or credential ref and allowlist are valid

Windows Portable Build (Optional)

For additional native subprocess isolation on Windows:

npm run portable:windows     # Portable zip with sandbox helper
npm run installer:windows    # Traditional installer

See INSTALLATION.md for the full list of Windows packaging options.

LLM Providers

GuardianAgent supports 12 built-in provider families across local, managed-cloud, and frontier tiers:

Smart Routing

When both local and external providers are configured, tools automatically route by category:

Single-provider setups work without configuration. Smart routing can be toggled off in Configuration > Tools. Per-tool and per-category overrides are available via the LLM column dropdowns.

Inside the external tier, Configuration > AI Providers controls whether Guardian prefers managed-cloud profiles such as Ollama Cloud, OpenRouter, or NVIDIA Cloud, or frontier-hosted profiles. The Model Auto Selection Policy can bind named managed-cloud profiles to general, direct, tool-loop, and coding roles.

Quality-based fallback: When the local model produces a degraded response (empty, refusal, or boilerplate), the system automatically retries through the fallback chain.

Configuration

Most users configure GuardianAgent through the web Configuration Center (#/config) or CLI commands. The config.yaml file at ~/.guardianagent/config.yaml is created and updated automatically by those flows.

Three simplified top-level config aliases cover the most common settings:

sandbox_mode: workspace-write  # off | workspace-write | strict
approval_policy: on-request    # on-request | auto-approve | autonomous
writable_roots:                # merged into allowedPaths + sandbox writePaths
  - /home/user/projects

The default runtime stays brokered with a workspace-write sandbox profile and permissive enforcement. Set sandbox_mode: strict when you want risky subprocess-backed tools to fail closed unless a strong sandbox backend is available.

For detailed configuration documentation:

• Configuration Center Spec
• WebUI Design Spec

Development and Verification

npm test                              # Run all tests (vitest)
npm run test:verbose                  # Verbose test output
npm run test:coverage                 # Run with v8 coverage
npx vitest run src/path/to.test.ts   # Run a single test file

npm run check         # Type-check only (tsc --noEmit)
npm run build         # TypeScript compilation → dist/
npm run dev           # Run with tsx (starts CLI channel)

Focused harnesses for common regression surfaces:

node scripts/test-coding-assistant.mjs
node scripts/test-code-ui-smoke.mjs
node scripts/test-contextual-security-uplifts.mjs
node scripts/test-security-verification.mjs

Use focused Vitest runs during iteration, then run the broader relevant harness before handing off changes that touch routing, approvals, coding, security, web UI, providers, or startup behavior. The integration testing guide has the full matrix: docs/guides/INTEGRATION-TEST-HARNESS.md.

Contributing

This repository is structured for architecture-sensitive changes. Before changing a subsystem, read the owning design document and keep implementation, tests, and docs in sync.

• Keep code in the existing TypeScript style: strict ESM, 2-space indentation, semicolons, single quotes, and explicit .js extensions in relative imports.
• Add or update colocated *.test.ts coverage for behavior changes.
• Run npm run check and the relevant Vitest or harness commands before opening a PR.
• Update src/reference-guide.ts for user/operator-facing workflow changes.
• Update the relevant docs/design/, docs/architecture/, or guide document when changing architecture, routes, tool behavior, security boundaries, or web surfaces.
• Do not commit secrets, local credentials, generated runtime state from ~/.guardianagent/, or scratch output from tmp/.

Troubleshooting

Reporting Intent Routing Problems

If GuardianAgent chooses the wrong route, uses the wrong tool, asks for the wrong clarification, or gives a result that does not match the requested surface, open a GitHub issue with:

• the exact user request and the response you saw
• the channel or surface used, such as Web, CLI, Telegram, or Code
• the model/provider profile shown in the response header, if available
• the relevant intent routing trace from ~/.guardianagent/routing/intent-routing.jsonl

On Windows, the trace is usually at C:\Users\<your-user>\.guardianagent\routing\intent-routing.jsonl. Attach only the lines around the failed request if possible. The trace can include prompts, local file paths, provider names, and tool arguments, so review and redact sensitive data before sharing.

GitHub issue comments support drag-and-drop file attachments for logs and JSON data. If GitHub rejects a .jsonl file extension, rename the excerpt to .log or place it in a .zip before attaching. See GitHub's attachment guide: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/attaching-files.

Disclaimer

This software is provided as-is, without warranty of any kind. GuardianAgent implements security controls designed to reduce risk in AI agent systems, but no software can guarantee complete security. The developers and contributors accept no liability for any damages, data loss, credential exposure, financial loss, or other harm arising from the use of this software.

By using GuardianAgent, you acknowledge that:

• AI systems are inherently unpredictable and may produce unexpected outputs
• Security patterns (secret scanning, prompt injection detection) rely on known signatures and heuristics, and may not catch novel or obfuscated attack vectors
• You are solely responsible for the configuration, deployment, and operation of this software in your environment
• You should independently evaluate whether the security controls are sufficient for your use case
• This software should not be used as a sole security control for systems handling sensitive data without additional safeguards

This project is not affiliated with any security certification body and makes no compliance claims.

License

Apache 2.0