Deployment Guide¶

Installation Tiers¶

The setup-sift.sh installer offers three tiers:

Tier	Packages	Use Case
Quick	forensic-mcp, case-mcp, report-mcp, sift-mcp, sift-gateway, sift-common, forensic-knowledge	Core investigation. Minimal install.
Recommended	Quick + forensic-rag, windows-triage	Adds RAG search and baseline validation.
Custom	Select individual packages	Fine-grained control.

OpenCTI-mcp is always optional (requires an OpenCTI instance).

SIFT Workstation Setup¶

Prerequisites¶

Ubuntu 22.04+ (SIFT Workstation recommended)
Python 3.10+
Git
sudo access (required — creates the ledger and signing-key folders under /var/lib/vhir/)

Install¶

git clone https://github.com/AppliedIR/sift-mcp.git && cd sift-mcp
./setup-sift.sh

The installer: 1. Creates a Python virtual environment 2. Installs MCP servers, gateway, and vhir CLI via pip 3. Creates /var/lib/vhir/ with ledger/, keys/, passwords/ and verification/ (the 0.6 records), owned by the examiner account, mode 700 (requires sudo) 4. Sets examiner identity 5. Generates gateway.yaml configuration 6. Creates a systemd service for the gateway (optional) 7. Starts the gateway 8. Runs vhir setup client to configure your LLM client

Windows Workstation Setup¶

Prerequisites¶

Windows 10/11 or Windows Server 2019+
Python 3.10+
Forensic tools (Zimmerman suite, Hayabusa) installed

Install¶

git clone https://github.com/AppliedIR/wintools-mcp.git
cd wintools-mcp
Set-ExecutionPolicy -Scope Process Bypass -Force
.\scripts\setup-windows.ps1

Set-ExecutionPolicy -Scope Process allows scripts for this PowerShell window only. Windows 10/11 refuses to run them by default.

The installer: 1. Requires typing security_hole to acknowledge the security implications 2. Creates a Python virtual environment 3. Installs the wintools-mcp package 4. Generates a bearer token (vhir_wt_ prefix) 5. Creates config.yaml with the token 6. Optionally creates a Windows service

Connecting to SIFT¶

Copy the bearer token from the installer output. On the SIFT workstation, add a wintools backend to gateway.yaml:

backends:
  wintools-mcp:
    type: http
    url: "http://WIN_IP:4624/mcp"
    bearer_token: "vhir_wt_..."

Or use vhir setup client with the --windows flag:

vhir setup client --sift=http://127.0.0.1:4508 --windows=WIN_IP:4624

SMB Configuration¶

wintools-mcp accesses the case directory on SIFT via an authenticated SMB share. This gives the Windows workstation read access to evidence files, write access to the extractions directory (parsed output), and write access to the audit directory. The Valhuntir installer configures this automatically during vhir join --wintools.

On the Windows workstation, set VHIR_SHARE_ROOT to the SMB mount point:

$env:VHIR_SHARE_ROOT = "E:\cases\SRL2\"

Network requirements: - SIFT gateway → wintools-mcp: HTTPS on port 4624 (Bearer token auth) - Windows → SIFT: SMB on port 445 (authenticated share) - Both connections must be on the isolated forensic network - No connections from outside the forensic environment

The SMB share should use authenticated connections with credentials restricted to Valhuntir components. See the wintools-mcp SETUP.md for share creation, user credentials, and firewall rules.

Remote Access (TLS + Auth)¶

For deployments where the LLM client runs on a different machine:

Enable Remote Access¶

./setup-sift.sh --remote

This generates: - Local CA certificate and gateway TLS certificate at ~/.vhir/tls/ - Bearer token (vhir_gw_ prefix) in gateway.yaml - Gateway binds to 0.0.0.0:4508 with TLS

A Claude Code running locally on the SIFT box is pointed at that CA automatically: vhir setup client and vhir update add env.NODE_EXTRA_CA_CERTS = ~/.vhir/tls/ca-cert.pem to the managed ~/.claude/settings.json so it trusts the self-signed gateway CA (unless you already set NODE_EXTRA_CA_CERTS, which is kept). A value you export in your shell afterwards is overridden by the one in settings.json; to use your own bundle, add the gateway CA to it and remove the settings.json entry.

The installer prints per-OS remote client setup commands with a join code.

Remote Client Setup¶

Run the appropriate setup script on the machine where your LLM client runs. Each script joins the gateway and creates a ~/vhir/ workspace with MCP config, forensic controls, and discipline docs.

Linux:

curl -sSL https://raw.githubusercontent.com/AppliedIR/Valhuntir/main/setup-client-linux.sh \
  | bash -s -- --sift=https://SIFT_IP:4508 --code=XXXX-XXXX

macOS:

curl -sSL https://raw.githubusercontent.com/AppliedIR/Valhuntir/main/setup-client-macos.sh \
  | bash -s -- --sift=https://SIFT_IP:4508 --code=XXXX-XXXX

Windows:

Invoke-WebRequest -Uri https://raw.githubusercontent.com/AppliedIR/Valhuntir/main/setup-client-windows.ps1 -OutFile setup-client-windows.ps1
.\setup-client-windows.ps1 -Sift https://SIFT_IP:4508 -Code XXXX-XXXX

Always launch your LLM client from ~/vhir/ or a subdirectory. Forensic controls only apply when started from within the workspace.

cd ~/vhir && claude                          # start from workspace root
mkdir ~/vhir/cases/INC-2026-001              # organize by case
cd ~/vhir/cases/INC-2026-001 && claude       # case-specific session

To uninstall, re-run the setup script with --uninstall (Linux/macOS) or -Uninstall (Windows). On SIFT, use vhir setup client --uninstall.

Your LLM client must run locally on your machine to reach the SIFT gateway. Cloud-hosted LLM services cannot connect to internal network addresses.

Join Codes¶

Generate a join code on the SIFT workstation:

vhir setup join-code --expires 2    # 2-hour expiry

Multi-Examiner Deployment¶

Each examiner runs their own full stack on their own SIFT workstation with a local case directory.

Setup¶

Each examiner installs independently:

git clone https://github.com/AppliedIR/sift-mcp.git && cd sift-mcp
./setup-sift.sh

Collaboration¶

Examiners share findings via JSON export/import:

# Alice exports her findings
vhir export --file findings-alice.json

# Bob imports Alice's findings
vhir merge --file findings-alice.json

IDs include the examiner name (F-alice-001, F-bob-003) so they never collide. Merge uses last-write-wins by modified_at timestamp. APPROVED findings are protected from overwrite.

Gateway Configuration¶

The gateway is configured via gateway.yaml (typically at ~/.vhir/gateway.yaml).

Backend Configuration¶

backends:
  forensic-mcp:
    type: stdio
    command: ["python", "-m", "forensic_mcp"]
  case-mcp:
    type: stdio
    command: ["python", "-m", "case_mcp"]
  report-mcp:
    type: stdio
    command: ["python", "-m", "report_mcp"]
  sift-mcp:
    type: stdio
    command: ["python", "-m", "sift_mcp"]
  forensic-rag-mcp:
    type: stdio
    command: ["python", "-m", "rag_mcp"]
  windows-triage-mcp:
    type: stdio
    command: ["python", "-m", "windows_triage"]
  threatintel-mcp:                # opencti-mcp in configurations from before
    type: stdio
    command: ["python", "-m", "opencti_mcp"]
  wintools-mcp:
    type: http
    url: "http://WIN_IP:4624/mcp"
    bearer_token: "vhir_wt_..."

Authentication¶

api_keys:
  vhir_gw_a1b2c3d4e5f6a1b2c3d4e5f6:
    examiner: "alice"
    role: "examiner"

Environment Variables¶

Variable	Default	Description
`SIFT_TIMEOUT`	`600`	Default command timeout (seconds)
`SIFT_TOOL_PATHS`	(none)	Extra binary search paths (colon-separated)
`SIFT_HAYABUSA_DIR`	`/opt/hayabusa`	Hayabusa install location
`VHIR_CASE_DIR`	(none)	Active case directory (falls back to `~/.vhir/active_case`)
`VHIR_CASES_DIR`	(none)	Root directory containing all cases
`VHIR_EXAMINER`	(none)	Examiner identity

wintools-mcp Environment Variables¶

Variable	Default	Description
`WINTOOLS_TIMEOUT`	`600`	Default command timeout (seconds)
`WINTOOLS_HOST`	`127.0.0.1`	HTTP bind address
`WINTOOLS_PORT`	`4624`	HTTP port
`WINTOOLS_TOOL_PATHS`	(none)	Additional binary search directories
`VHIR_SHARE_ROOT`	(none)	SMB mount root for evidence and extractions
`VHIR_EXAMINER`	OS user	Examiner identity

Client Configuration¶

Claude Code¶

vhir setup client --client=claude-code deploys:

.mcp.json with Streamable HTTP endpoint
.claude/settings.json with kernel-level sandbox, case data deny rules, PreToolUse guard hook, and PostToolUse audit hook
FORENSIC_DISCIPLINE.md and TOOL_REFERENCE.md for LLM context
CLAUDE.md referencing AGENTS.md

Codex¶

vhir setup client --client=codex (on SIFT, or with --remote on another machine) writes ~/.codex/valhuntir.config.toml (0600), which codex -p valhuntir reads: every backend with its bearer token, sandbox_mode = "workspace-write", approval_policy = "on-request", project_doc_max_bytes = 0, and the instructions. The user's ~/.codex/config.toml is never written. The skills go to ~/.agents/skills/ and the finding skeptic's agent to ~/.codex/agents/.

Claude Desktop is no longer supported: the commands it runs aren't audited, so vhir setup client refuses it.

External MCPs¶

Two external MCPs are configured during client setup:

Zeltser IR Writing MCP (https://website-mcp.zeltser.com/mcp) — Required for report generation
MS Learn MCP (https://learn.microsoft.com/api/mcp) — Optional, Microsoft documentation search

Systemd Service¶

The installer can create a systemd service for the gateway:

sudo systemctl enable vhir-gateway
sudo systemctl start vhir-gateway
sudo systemctl status vhir-gateway

Logs:

journalctl -u vhir-gateway -f

Testing Connectivity¶

vhir setup test    # Test all configured MCP endpoints

This verifies connectivity to the gateway and all backend MCPs.