INSTALLATION GUIDE

Install Guardian Agent locally from source (Node.js 24.14+). Context Cypher standalone steps remain available in their own tab.

Guardian Agent

Open-source local security workspace for Windows, macOS and Linux. It merges Guardian security operations with Context Cypher diagram and GRC workflows. Core diagrams, GRC and security observations do not require an AI account.

Steps below match the Guardian Agent README, INSTALLATION.md and docs/guides/SECURITY-WORKSPACE.md.

github.com/Threat-Vector-Security/guardian-agent

Prerequisites

Node.js: 24.14 or later, with npm and built-in SQLite available
Writable private data directory: default ~/.guardianagent/security-v2
Git: to clone the repository, or download the source archive
Modern browser: open the exact loopback address printed by the service

Important: Guardian Agent requires Node.js 24.14 or later. The security service does not fall back to temporary in-memory storage if SQLite is unavailable.

Step 1: Clone the repository

Clone or download the source, then work from the project directory.

$git clone https://github.com/Threat-Vector-Security/guardian-agent.git

$cd guardian-agent

Step 2: Build, initialise and start

From the repository root:

$npm ci npm run build npm run init npm start

Open http://127.0.0.1:3000 using the exact address printed by the service. The listener binds to loopback on that IP. Do not substitute a different hostname or expose it through a public reverse proxy.

Initialization creates a private administrator credential and prints its file path, not its contents.
Local browser access opens without an access code by default.
Enable Settings â†’ Require an access token to open Guardian if you want browser sign-in.
Configured Entra SSO always requires sign-in.
External assistants always use separately enrolled scoped credentials. Never give the root token to an assistant.
Default data directory: ~/.guardianagent/security-v2. Set GUARDIAN_SECURITY_HOME before init and startup to use another directory.
Ctrl+C stops the foreground service.

Alternate port

To use another port after building:

$node dist/security-main.js serve --port 3007

You can also set GUARDIAN_PORT.

Development launchers

Install dependencies first with npm ci. The launchers run security tests, type checks and a build, initialize credentials when needed, then start Guardian. They do not stop another running Guardian process.

Windows PowerShell

$.\scripts\start-security-windows.ps1

After an existing build, use -StartOnly. For another port use -Port 3007.

macOS, Linux or WSL

$bash scripts/start-security-unix.sh

After an existing build, use --start-only. For another port setGUARDIAN_PORT=3007.

Try this first

Open Protection and run a check to review your workstation's available security observations.
Open Systems, create a system and choose a built-in example from Examples to explore the editor. You can also import an existing Context Cypher JSON file.
Switch to GRC to explore the example's assets, risks, controls and assessments. Use Sync from Diagram when you want to bring diagram elements into the asset register.
Use Save system to retain the workspace, or File â†’ Save As for a portable copy.
To model your own environment, use Environments â†’ Collect now â†’ Preview latest snapshot â†’ Create editable system.

Workspace pages

Page	Use it to
Protection	Check workstation posture, native antivirus status and available passive network observations. Review coverage and request supported scans.
Environments	Collect local or enrolled AWS observations, preview the recorded inventory, and create an editable system diagram.
Findings	Review evidence, record decisions and link findings to architecture assets.
Systems	Open examples or import a workspace; edit diagrams, node/connection details, threats, controls and GRC data.
Activity	Inspect jobs and review pending supported scan proposals.
Integrations	Inspect integration capabilities and explicitly collect supported AWS observations.
Settings	Manage browser access and enroll, scope, expire or revoke assistant credentials.

A finding marked resolved records an operator decision; it does not prove remediation. A requested antivirus scan is not a completed or clean scan.

Admin recovery note

Root recovery/rotation is an explicit local command:

$node dist/security-main.js init --rotate-admin

Rotation retains a previous token file for failure recovery and revokes prior administrators in the local database.

Need Context Cypher alone?

Context Cypher remains available as a standalone open-source threat modeling and diagram tool. Use the Context Cypher Standalone tab for global package install steps, or import existing Context Cypher files into Guardian Agent.