AEGIS helps you see what local AI agents are doing, review agent files before use, and check policies for selected actions. Monitoring records processes, file activity, TCP endpoints and attribution evidence without requiring an agent plugin.

Current source also includes opt-in policy-controlled execution and MCP tools for operator-selected actions. These routes require explicit setup; ordinary agent monitoring does not automatically intercept or block commands.

Open-source, monitor-first, no usage telemetry or cloud sync. Monitoring data is stored locally. Endpoint naming uses DNS queries. Optional AI analysis sends activity metadata to Anthropic on request; update checks contact GitHub. See privacy and key handling.

Download · Start with a task · Documentation · Local demo · Known limits · Report a bug

Current source version: 0.17.0-alpha

The published release is built from its tag; later source changes require a new release.

_{Observatory preview with simulated data, captured from current source on 27 September 2026.}

Start with a task

The guided interface keeps results above setup, uses distinct icons for each workspace and reveals technical details on request. File and action checks do not execute commands or establish safety. This describes current source; the published installer can contain an earlier UI.

What AEGIS observes

The Observatory workspace provides a live instance radar, separate agent instances, file and network views, rules, custom agent catalog, AI analysis, reports, audit, statistics and settings. Activity can be filtered and grouped, inspected by stamped instance identity, and exported to JSON, CSV, HTML or ZIP. The agent database and contributor guide describe how to extend detection.

Monitor-first

Default monitoring observes and logs; it does not automatically block or contain agents. Kill, suspend and resume are manual actions. Monitoring presets and endpoint allowlists do not establish that an agent is safe. The opt-in routes below control only selected launches. The Windows Job route bounds the lifetime of its participating descendants. The separate AppContainer CLI route adds Windows access restrictions for one reviewed offline action in a new workspace; other execution routes retain caller privileges.

The sensitive-activity review list is scoped to the current desktop window; marking an alert reviewed does not quarantine its file or grant access.

AEGIS is alpha software. This README describes current source; installed builds contain the features available at their release tag.

Opt-in action control

An operator can select an exact executable, working directory, arguments and environment, then route that action through AEGIS:

These routes do not cover other agent tools, arbitrary MCP traffic or activity outside the selected actions. Allowed programs retain the caller's account privileges. Terminal previews can expose secrets in local scrollback; terminal automation does not establish human identity. Client settings are not changed automatically. The linked contracts explain configuration, limits and verification.

After creating a catalog, generate a client configuration from the source checkout (PowerShell 7 example):

node src/main/main.js --action-mcp-config-json catalog "X:/private/actions/catalog.json" > aegis-mcp.json

The configuration generator prints an mcpServers.aegis entry using the current Node executable and absolute source entry path. Load the generated file explicitly in a client that accepts this configuration format; client setup requirements vary. The output intentionally contains local paths, so keep it private. Generation does not read or validate the catalog, start a server or install settings; run the appropriate route/catalog check separately.

Download

Windows installer

Get the current prerelease from GitHub Releases. A Windows release is ready to install when its .exe, manifest.json and manifest.json.sig are all available. Download them from the same release and follow offline installer verification. Check that release's notes for the features it contains; this README describes current source, which may be ahead of the installer.

When upgrading from 0.14.1-alpha or older, install 0.15.0-alpha or newer manually before using signed in-app updates.

From source

Requires Node.js 24.x. Windows 10/11 is the primary platform; macOS/Linux support is experimental.

git clone https://github.com/antropos17/Aegis.git
cd Aegis
npm ci
npm start

Try without AI agents

After installing dependencies, build and preview the browser demo:

npm run dev
# open http://127.0.0.1:8770

The preview uses simulated data and an isolated host. It shares the desktop components, never calls the real preload, and disables native exports and provider requests. npm run frontend:build:preview creates a static preview; npm run build:renderer creates the desktop artifact without fixtures.

The evidence graph

The Local security workspace reviews selected project/profile files, commands, scripts and instruction patterns, compares content snapshots, and imports offline Cisco results. It keeps incomplete coverage and unverified claims visible. See the workspace guide for inputs, evidence and limitations.

• Instance identity: Windows uses PID and OS birth time; Linux uses boot identity and kernel process start ticks. Missing witnesses and synthetic discoveries provide weaker identity.
• Attribution: Records distinguish confirmed, inferred and unattributed ownership. Identity or attribution can be null when unknown or not applicable.
• Audit trail: Hash-chained JSONL records rotate daily and have 30-day retention. Chain verification detects edits relative to a trusted chain state; it does not guarantee that no events were lost.

See the architecture, correctness audit and dated measurements for implementation details and evidence.

Known limits

• Incomplete coverage: Unknown signatures and processes that start and exit between polling ticks can be missed. Default monitoring does not parse MCP traffic or individual tool calls; the explicitly configured MCP routes handle only their published AEGIS tools.
• Platform gaps: macOS lacks a process-generation witness. Linux generation identity depends on accessible /proc data; its fallback has no start-time witness. Missing identity limits process-control guarantees. Measured Claude Code usage requires a process start-time witness and a readable matching session registry/transcript. Windows is the verified primary path; native Linux token collection remains unverified.
• Bounded UI history: Retained event windows can differ from aggregate totals; Statistics shows renderer eviction counters; Audit provides persisted history.
• Sensor and audit gaps: Health status does not prove complete capture. A fully lost file-watch plan gets up to three retry attempts per confirmed outage; the budget resets after a healthy plan is observed. Exited watch workers count as lost roots. Partially degraded roots need separate repair. Audit loss markers require a successful flush; process-scan overruns lack a dedicated counter.
• Sensitive metadata: Logs and exports contain paths, agent names and endpoints. Configuration and diagnostic exports omit the configured API key. Local key encryption depends on safeStorage availability. See SECURITY.md.
• Unmeasured claims: No general detection rate, false-positive rate, startup-time guarantee or whole-app overhead figure has been established.

Development and roadmap

Inspect a project's AI component files without starting agents or MCP servers:

node src/main/main.js --inventory-json "X:/path/to/project"
node src/main/main.js --inventory-profile-json codex-user "X:/copied-codex-profile"

This produces a bounded local inventory with fingerprints, not a security verdict. See scope, privacy and exit codes and the AI agent protection plan.

The monitoring engine uses CommonJS JavaScript; the Svelte renderer and shared types use TypeScript. See development setup, the development reference and package.json for the stack and commands.

CI runs build, lint, type checks, tests and dependency auditing. npm run counts:check verifies selected inventory declarations. npm run verify:gate checks identity-witness behavior with fault injection (4 mutants); npm run verify:seq-gate checks sequence behavior. Run npm test for current suite results.

The roadmap tracks Windows ETW experiments and remaining discovery/platform work. Source changes and isolated experiments are not automatically available in released installers.

Contributors

Antropos7	travisbreaks	MsfPablo	raye-deng	pablo
Steven Melendez	anupamme	mig-builds	frobel0520	KJyang-0114

CONTRIBUTING.md · SECURITY.md · CODE_OF_CONDUCT.md

Support and license

Feature requests · Private vulnerability reports · MIT license

Local monitoring requires no account or subscription. Optional Anthropic analysis uses your own API key and is subject to that service's charges.

Navigation icons use a curated Tabler Icons subset under the MIT notice. Pinned source URLs and hashes are recorded in the icon provenance.

Star history