CyberAg Documentation

CyberAg Local Setup Guide

This guide explains how to run CyberAg locally using Docker + LocalStack.

Prerequisites

Required Software

1. **Docker Desktop**

- Required for running LocalStack and Lambda execution

- Download from: https://www.docker.com/products/docker-desktop/

- Ensure Docker is running before starting CyberAg

2. **Node.js** (v20+)

- Required for the monorepo and all apps

- Download from: https://nodejs.org/

3. **Rust Toolchain** (for Tauri desktop app - optional)

- Required if you want to build the desktop app

- Install from: https://rustup.rs/

- On Windows: winget install Rustlang.Rustup

4. **GEMINI_API_KEY** (optional for read-only UI)

- Required for AI features (guardrail classification, red team, eval, ask, hardening)

- Get your key from: https://aistudio.google.com/app/apikey

- Set as environment variable:

- Windows PowerShell: $env:GEMINI_API_KEY="your_api_key_here"

- Linux/macOS: export GEMINI_API_KEY="your_api_key_here"

- Or copy scripts/local/gemini.key.example → scripts/local/gemini.key

- **Read-only mode:** $env:CYBERAG_LOCAL_SKIP_GEMINI="1" skips AI features but loads the full UI with seeded data

Optional Software

- Install: npm install -g awscli-local or download from AWS

Quick Start

Option 1: Start Console Only (Backend Already Running)

If you've already deployed the infrastructure:

cd apps/console
npm run dev

Then open http://localhost:3002 in your browser.

Option 2: Full Local Setup (One Command)

This will:

1. Start LocalStack

2. Deploy infrastructure to LocalStack

3. Seed sample data

4. Start the console

npm run start:local

After completion, open http://localhost:3002.

Manual Setup Steps

1. Start LocalStack

npm run local:up

Wait for LocalStack to be ready (approximately 10-15 seconds).

2. Deploy Infrastructure

This creates:

npm run local:deploy

3. Seed Initial Data

This populates the database with sample data (mirroring the mock.ts file):

npm run local:seed

4. Start the Console

cd apps/console
npm run dev

Open http://localhost:3002 in your browser.

Stopping LocalStack

npm run local:down

Reset Everything

This stops LocalStack, removes volumes, and starts fresh:

npm run local:reset

Then re-deploy:

npm run local:deploy
npm run local:seed

Desktop App (Tauri)

Prerequisites for Desktop App

1. Install Rust toolchain (see above)

2. Install Tauri CLI:

```bash

npm install -g @tauri-apps/cli

```

Development

npm run desktop:dev

Build

npm run desktop:build

The built desktop app will be in apps/desktop/src-tauri/target/release/bundle/.

Troubleshooting

LocalStack won't start

npm run start:local fails

1. npm run local:up

2. npm run local:deploy

3. npm run local:seed

4. cd apps/console && npm run dev

Console shows connection errors

Gemini API errors

Port conflicts

- apps/console/package.json (console port)

- apps/docs/package.json (docs port)

- docker-compose.yml (LocalStack port)

Architecture Overview

┌─────────────────┐
│  Tauri Desktop  │ (optional)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Console (Vite) │ :3002
└────────┬────────┘
         │ HTTP
         ▼
┌─────────────────────────────────┐
│  LocalStack :4566               │
│  ┌──────────────────────────┐  │
│  │  API Gateway             │  │
│  │  ├─ /api/v1/*           │  │
│  │  └─ /guardrail/check    │  │
│  └──────────┬───────────────┘  │
│             │                   │
│  ┌──────────▼──────────────┐  │
│  │  Lambda Functions       │  │
│  │  ├─ api                 │  │
│  │  ├─ eval                │  │
│  │  ├─ guardrail-gateway   │  │
│  │  ├─ connectors          │  │
│  │  └─ replay              │  │
│  └──────────┬──────────────┘  │
│             │                   │
│  ┌──────────▼──────────────┐  │
│  │  Data Layer             │  │
│  │  ├─ DynamoDB            │  │
│  │  ├─ S3 (audit vault)    │  │
│  │  ├─ EventBridge         │  │
│  │  └─ SQS (eval queue)    │  │
│  └──────────────────────────┘  │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────┐
│  Gemini API     │ (external)
└─────────────────┘

Environment Variables

Console (.env.local)

VITE_CYBERAG_API_URL=http://localhost:4566

Root / Services

GEMINI_API_KEY=your_api_key_here
TABLE_NAME=cyberag-main (auto-configured by CDK)
AUDIT_VAULT_BUCKET=cyberag-audit-vault (auto-configured by CDK)
EVENT_BUS_NAME=cyberag-events

Data Flow

1. **Console** makes HTTP requests to LocalStack API Gateway

2. **API Lambda** routes requests and emits events to EventBridge

3. **EventBridge** triggers:

- **Eval Lambda** (via SQS) for red team, ask, hardening

- **Guardrail Lambda** for runtime checks

- **Connector Lambda** for sync operations

- **Replay Lambda** for decision replay

4. **Lambdas** read/write to:

- **DynamoDB** for persistent data

- **S3** for audit vault (tamper-evident storage)

5. **Gemini API** is called by:

- **Eval Lambda** for AI-powered evaluation

- **Guardrail Lambda** for safety classification

Security Notes

Production vs Local

Getting Help