Skip to content

Quick Start

Overview

This guide covers deploying the GHOSTS API stack and connecting clients to it. No compilation required — all server-side components are available as pre-built Docker images.

New to GHOSTS? Start with the API stack first, then connect one or more clients.

GHOSTS API Stack

The GHOSTS API stack runs as five Docker containers:

Container Image Port Purpose
ghosts-frontend dustinupdyke/ghosts-frontend 4200 Angular 20 management UI
ghosts-api dustinupdyke/ghosts 5000 REST API + SignalR WebSocket
ghosts-postgres postgres:16.8 5432 PostgreSQL database
ghosts-n8n docker.n8n.io/n8nio/n8n 5678 Workflow automation
ghosts-grafana grafana/grafana 3000 Activity dashboards

Prerequisites

  • Docker and Docker Compose (v2+)
  • Minimum 4 GB RAM (8 GB+ recommended for larger deployments)
  • 20 GB disk space
  • Ports 3000, 4200, 5000, 5432, and 5678 available on the host

Installation

1. Download the Docker Compose file

mkdir ghosts && cd ghosts
curl -O https://raw.githubusercontent.com/cmu-sei/GHOSTS/master/src/Ghosts.Api/docker-compose.yml

2. Start all containers

docker compose up -d

3. Verify the installation

docker ps -a

You should see all five containers in a running state.

Component URL Expected result
Frontend http://localhost:4200 Angular management UI
API http://localhost:5000 API home page
API Swagger http://localhost:5000/swagger Interactive API docs
Grafana http://localhost:3000 Monitoring dashboard (default login: admin/admin)
n8n http://localhost:5678 Workflow automation UI

If the API shows a database error, wait 15–30 seconds for PostgreSQL to finish initializing, then refresh.

Environment Variables

The compose file uses these defaults, which can be overridden with a .env file in the same directory:

Variable Default Description
WEB_API_URL http://host.docker.internal:5000/api API URL used by the frontend container
WEB_N8N_API_URL http://host.docker.internal:5678 n8n URL used by the frontend container
N8N_API_URL http://host.docker.internal:5678/api/v1/workflows n8n REST API URL used by the API container
N8N_API_KEY replace-me n8n API key — set this before using workflow scheduling

Managing the Stack

# Stop all containers
docker compose down

# Pull latest images and restart
docker compose pull && docker compose up -d

# View logs for the API
docker compose logs -f ghosts-api

# Restart a single service
docker compose restart ghosts-api

Data Persistence

Data is stored in local directories alongside docker-compose.yml:

  • ./_db — PostgreSQL data
  • ./_g — Grafana configuration and dashboards
  • ./n8n_data — n8n workflow definitions and credentials

These persist across docker compose down / up cycles. To reset the database:

docker compose down
rm -rf ./_db
docker compose up -d

GHOSTS Clients

GHOSTS clients simulate realistic user activity on target machines. Install one client per machine you want to simulate.

Prerequisites

Run clients as a regular user account, not as administrator or root, to produce realistic behavior and avoid permission issues with browser drivers.

For browser automation, place the appropriate WebDriver binary in the same directory as the GHOSTS client binary:

Windows Client

Requirements: .NET Framework 4.6.1 runtime or later (runtime only, SDK not required).

  1. Download the latest Windows client
  2. Extract to a directory (e.g., C:\ghosts)
  3. Edit config/application.json: 
    {
  "ApiRootUrl": "http://YOUR-API-HOST:5000/api"
}
  4. Run ghosts.exe

Linux / Universal Client

Requirements: .NET 9 runtime (runtime only, SDK not required).

For Ubuntu 24.04, use the snap installation.

  1. Download the latest Universal client
  2. Extract to a directory (e.g., ~/ghosts)
  3. Edit config/application.yaml: 
    ApiRootUrl: http://YOUR-API-HOST:5000/api
  4. Run: 
    dotnet ghosts.client.universal.dll

Note: Do not run as root — browser drivers may fail to launch in headless mode under root.

To run as a Linux systemd service, see the client documentation.

GHOSTS Lite (Lightweight Client)

GHOSTS Lite generates network and file activity without launching real applications. Use it for resource-constrained machines or when participants will not directly interact with the machine.

Requirements: .NET 8 runtime.

  1. Download the latest Lite client
  2. Edit config/application.yaml with your API URL
  3. Run: 
    dotnet ghosts.client.lite.dll

See the GHOSTS Lite documentation for configuration details.

Next Steps