KombatSync Documentation

Start here

System overview

KombatSync records exercise data into a mission timeline and produces evidence-preserving raw captures, normalized media, deterministic reports, optional local-AI analysis, offline maps, and a customer-ready browser review package.

Administration

Deployment and upgrade

Persistent storage

Set KOMBAT_DATA_HOST_PATH in the Compose environment to a host directory, USB volume, or host-mounted NFS/SMB share. The container stores everything under /data. Never place mission data inside the image.

$env:KOMBAT_DATA_HOST_PATH = "D:\KombatSyncData"
docker compose up -d

KOMBAT_DATA_HOST_PATH=/srv/kombatsync docker compose up -d

Offline Docker package

build-docker-package.bat creates separate AMD64 and ARM64 image tars, version-independent update helpers, Compose files, and SHA-256 checksums. Use ARM64 for DGX Spark. A successful build removes older local KombatSync package directories unless KOMBAT_KEEP_OLD_PACKAGES=1 is set. On the destination server, edit .env once, then use sh update-kombatsync.sh or .\update-kombatsync.ps1 for every release. The helper detects the architecture, chooses the newest matching tar, verifies its checksum, loads it as jointlvc-kombatsync:latest, recreates the container, and removes older KombatSync image tags.

Upgrade procedure

1. Stop new mission starts and allow processing jobs to finish.
2. Back up the entire configured storage root and current Compose environment.
3. Copy the new architecture-specific tar and supplied SHA256SUMS.txt into the existing helper directory.
4. Run the same update helper; no version edits are required. Use --keep-old-images or -KeepOldImages only when a rollback image must be retained.
5. Open Dashboard and confirm version, storage state, profiles, schedules, and prior missions.
6. Run a short synthetic or operational test mission before the next exercise.

Deployment boundary

Security and classification

• KombatSync makes no telemetry, analytics, CDN, map, or AI calls unless an administrator explicitly configures a destination.
• V2.2.0 does not provide application login or role-based access. Protect the host and network or place an approved authenticated reverse proxy in front of it.
• Classification banners are markings, not access controls.
• Use separate deployments and storage roots when classification policy requires physical or cryptographic separation.
• AI and map endpoints must be approved for the mission's classification. Do not move classified products to a lower-classification model server.
• Store secrets in environment variables. The settings API removes keys named token, password, authorization, headers, or API key rather than persisting them.

Operations

Missions and dashboard

Start a mission

1. Confirm Dashboard shows healthy storage and the correct classification.
2. Enter mission name, exercise/customer metadata, description, and classification.
3. Select the enabled sources required for the mission.
4. Select Start mission. The Live Missions page shows capture health immediately.

The dashboard summarizes active missions, storage, processing, AI queue depth, upcoming schedules, and recent recordings. Mission metadata is copied into the immutable mission manifest at start.

Stop and process

Select Stop & process. Capture workers close segments, video/audio normalization runs, deterministic products are generated, map tiles are collected, the review folder/ZIP is built, and—when enabled—the AI job is queued.

Operations

Input sources

Important fields

• Stream URL: the canonical media setting containing protocol, address, port, path, and query options. Address and Port are DIS-only settings. Standard URL credentials are supported when required, but the URL is stored with the profile and mission; use a dedicated low-privilege source account.
• Network interface: blank or 0.0.0.0 uses the OS-selected interface. Use a receiving NIC's IPv4 address when the host has multiple adapters or multicast routes.
• Segment length: media is split into recoverable source chunks from 30–3600 seconds. The recommended 300 seconds creates five-minute chunks and does not limit total mission duration.
• Review proxy: produces lower-resolution H.264/AAC media without replacing the source-quality capture.
• SDP: paste the complete session description for RTP payload mappings, clock rates, codecs, and multicast connection data.
• Exercise ID: enable Accept all DIS exercise IDs to store every exercise on the configured socket, or disable it and select one value from 0–255.

Discovery

SAP/SDP discovery listens for announced sessions. ONVIF WS-Discovery identifies devices but does not guess credentials or a final RTSP URI. Review every discovered source before saving it. KombatSync does not sweep arbitrary subnets.

Operations

Live monitoring and bookmarks

Live cards report source state, received bytes/packets, segment count, and error/recovery information. MPEG-TS continuity errors indicate dropped, reordered, or duplicated transport packets and usually point to network loss, NIC buffering, multicast routing, or an unstable encoder.

• Add bookmarks during the event to mark injects, safety issues, key decisions, or customer questions.
• If a negotiated source drops, KombatSync retries it. UDP sources remain bound and show stalled health until traffic returns.
• If the service restarts, active mission manifests are reopened and recovery count is incremented.
• Recovery protects collection continuity but cannot recreate packets that never reached the host.

Automation

Schedules and API-triggered missions

Schedules can run once, daily, weekly, or from a five-field cron expression. Start time is interpreted in the selected IANA time zone. Duration must be between one minute and eight hours.

# Five-field cron: minute hour day-of-month month day-of-week
0 8 * * 1-5     # 08:00 Monday through Friday

Disable a schedule to retain it without launching future missions. A missed run is not backfilled indefinitely. The five-mission concurrency limit or storage start-block threshold can prevent a scheduled start and will be logged.

External exercise-control systems can call POST /api/recordings and later POST /api/recordings/:id/stop. API authentication must be supplied by the deployment boundary because KombatSync itself has no API key.

After action review

Library and synchronized review

• Search or filter completed, active, and failed missions.
• Open a mission to review media, deterministic AAR findings, AI recap, capture health, metadata, and products.
• The portable review package synchronizes videos to mission-relative time and lets events/transcript entries seek the media.
• Offline maps use tiles already packaged with the mission; the customer browser does not contact a map server.
• Reviewer annotations are stored in that browser's local storage and can be exported to JSON or CSV.
• Deletion is manual and permanent. Active captures and generating products cannot be deleted.

Delivery

Products and exports

Download All produces the standard customer package and names the downloaded ZIP after the mission. Export with raw also includes raw material and is larger. ZIP64 avoids the classic 4 GiB archive limit. USB/shared-storage delivery can copy the review folder directly.

Complete reference

All application settings

Storage and capture

Map settings

AI settings

Offline maps

Map server setup

KombatSync does not ship a world basemap and does not bulk-download public map providers. Point it at an approved internal HTTP(S) service. During mission processing it calculates the entity-track bounds, adds the configured buffer, downloads tiles, and packages them with the review.

Simple internal XYZ tile host

Prepare an XYZ directory tree such as tiles/10/301/384.png. Serve it from an internal web server. One containerized example:

# Linux
docker run -d --name kombat-map-tiles --restart unless-stopped \
  -p 8090:80 \
  -v /srv/maps:/usr/share/nginx/html:ro \
  nginx:alpine

# KombatSync URL
http://MAP_SERVER_IP:8090/tiles/{z}/{x}/{y}.png

# Windows PowerShell
docker run -d --name kombat-map-tiles --restart unless-stopped `
  -p 8090:80 `
  --mount "type=bind,src=D:\Maps,dst=/usr/share/nginx/html,readonly" `
  nginx:alpine

Verify a known tile from the KombatSync host before enabling the setting:

curl http://MAP_SERVER_IP:8090/tiles/0/0/0.png --output test-tile.png

Credential and internal CA setup

Set KOMBAT_MAP_CREDENTIAL in Compose. A plain value becomes Authorization: Bearer VALUE. A JSON object supplies exact headers:

KOMBAT_MAP_CREDENTIAL={"Authorization":"Bearer replace-me","X-API-Key":"replace-me"}

For a private CA, set KOMBAT_CUSTOM_CA_PATH to the host PEM file. Compose mounts it at /run/secrets/site-ca.pem; enter that container path in Map Custom CA.

Verification mission

1. Enable maps and use zoom 6–10 for the first test.
2. Record DIS Entity State traffic containing valid ECEF positions.
3. Stop the mission and wait for product generation.
4. Open Offline Map Manifest.json.
5. Confirm requested/downloaded counts match and incomplete is false.
6. Open the review package with the network disconnected and inspect tracks/tiles.

Offline maps

Map protocol examples

Local AI

How KombatSync uses AI

1. Audio products are converted to 15-minute MP3 chunks and sent sequentially to POST /v1/audio/transcriptions.
2. Frames near important DIS/fire/detonation/timeline events are extracted from review video and sent as base64 image URLs to POST /v1/chat/completions.
3. Deterministic mission facts, transcript segments, vision observations, and source identifiers are sent to the recap model.
4. The JSON recap is validated and written with citations, then the review package is regenerated to include AI products.

AI is post-processing, one mission at a time. It never controls collection. A failed job remains persistent and retries. Deterministic products are available even if the model server is offline.

Local AI

Recommended model set

The following set is optimized for one NVIDIA GPU with approximately 40 GB or more VRAM and a LocalAI V4.4.3 OpenAI-compatible endpoint. Pin exact image/model revisions after acceptance testing.

LocalAI model files

Place these YAML files and downloaded weights in the mounted models directory.

# kombat-vision.yaml
name: kombat-vision
backend: llama-cpp
parameters:
  model: Qwen3VL-32B-Instruct-Q4_K_M.gguf
mmproj: mmproj-Qwen3VL-32B-Instruct-Q8_0.gguf
context_size: 32768
gpu_layers: 999
threads: 1

# kombat-recap.yaml
# Alias avoids loading a second copy of the vision-language model.
name: kombat-recap
alias: kombat-vision

# kombat-transcription.yaml
name: kombat-transcription
backend: whisper
parameters:
  model: ggml-large-v3.bin

# Optional kombat-asr-qwen.yaml
name: kombat-asr-qwen
backend: llama-cpp
parameters:
  model: Qwen3-ASR-1.7B-Q8_0.gguf
mmproj: mmproj-Qwen3-ASR-1.7B-Q8_0.gguf
gpu_layers: 999
threads: 1

Local AI setup

Windows 10/11 AI server

1. Prepare Windows

1. Install the current NVIDIA Windows driver with WSL2 CUDA support.
2. Enable virtualization in BIOS/UEFI.
3. From elevated PowerShell run the following, restart if requested, then install Docker Desktop using the WSL2/Linux-container backend.

wsl --install
wsl --update
wsl --version

2. Verify GPU pass-through

docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi

Stop if the container cannot see the GPU. Fix the driver, WSL2, and Docker Desktop backend before installing models.

3. Create persistent directories

$root = "D:\LocalAI"
New-Item -ItemType Directory -Force "$root\models","$root\data"

4. Start LocalAI

$root = "D:\LocalAI"
$apiKey = "replace-with-a-long-random-local-key"
docker run -d --name local-ai --restart unless-stopped `
  --gpus all `
  -p 0.0.0.0:8081:8080 `
  -e "LOCALAI_API_KEY=$apiKey" `
  -e "MODELS_PATH=/models" `
  -e "DEBUG=false" `
  --mount "type=bind,src=$root\models,dst=/models" `
  --mount "type=bind,src=$root\data,dst=/data" `
  localai/localai:v4.4.3-gpu-nvidia-cuda-12

5. Restrict Windows Firewall

# Replace the remote subnet with the KombatSync network.
New-NetFirewallRule -DisplayName "LocalAI from KombatSync" `
  -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8081 `
  -RemoteAddress 10.20.30.0/24

6. Install model files

py -m pip install -U huggingface_hub

hf download Qwen/Qwen3-VL-32B-Instruct-GGUF `
  Qwen3VL-32B-Instruct-Q4_K_M.gguf `
  mmproj-Qwen3VL-32B-Instruct-Q8_0.gguf `
  --local-dir D:\LocalAI\models

hf download ggerganov/whisper.cpp ggml-large-v3.bin `
  --local-dir D:\LocalAI\models

# Optional alternate ASR
hf download ggml-org/Qwen3-ASR-1.7B-GGUF `
  Qwen3-ASR-1.7B-Q8_0.gguf `
  mmproj-Qwen3-ASR-1.7B-Q8_0.gguf `
  --local-dir D:\LocalAI\models

Create the YAML files from Recommended model set, restart LocalAI, and watch first-load logs:

docker restart local-ai
docker logs -f local-ai

Local AI setup

Linux NVIDIA AI server

1. Install Docker and the NVIDIA driver

Install the supported NVIDIA driver for the host distribution. Install Docker Engine from Docker's repository; on Ubuntu the final package step is:

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

2. Install NVIDIA Container Toolkit

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

3. Verify and start LocalAI

docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi

sudo mkdir -p /srv/localai/models /srv/localai/data
sudo chown -R "$USER":"$USER" /srv/localai

docker run -d --name local-ai --restart unless-stopped \
  --gpus all \
  -p 0.0.0.0:8081:8080 \
  -e LOCALAI_API_KEY='replace-with-a-long-random-local-key' \
  -e MODELS_PATH=/models \
  -e DEBUG=false \
  -v /srv/localai/models:/models \
  -v /srv/localai/data:/data \
  localai/localai:v4.4.3-gpu-nvidia-cuda-12

DGX Spark / NVIDIA ARM64

Use the CUDA 13 L4T ARM64 image supplied for DGX Spark:

docker run -d --name local-ai --restart unless-stopped \
  --runtime nvidia --gpus all \
  -p 0.0.0.0:8081:8080 \
  -e LOCALAI_API_KEY='replace-with-a-long-random-local-key' \
  -e MODELS_PATH=/models \
  -v /srv/localai/models:/models \
  -v /srv/localai/data:/data \
  localai/localai:v4.4.3-nvidia-l4t-arm64-cuda-13

4. Download models and restrict the port

python3 -m pip install -U huggingface_hub
hf download Qwen/Qwen3-VL-32B-Instruct-GGUF \
  Qwen3VL-32B-Instruct-Q4_K_M.gguf \
  mmproj-Qwen3VL-32B-Instruct-Q8_0.gguf \
  --local-dir /srv/localai/models
hf download ggerganov/whisper.cpp ggml-large-v3.bin \
  --local-dir /srv/localai/models

# UFW example—replace with the exact KombatSync host/subnet.
sudo ufw allow from 10.20.30.0/24 to any port 8081 proto tcp

Local AI setup

Disconnected / air-gapped AI deployment

Perform all downloads on a connected staging machine with the same CPU architecture as the destination when possible.

1. Pull the pinned LocalAI image for the destination architecture.
2. Download all model weights and create YAML files.
3. Start LocalAI while connected and successfully exercise models, chat, vision, and transcription. This forces backend initialization.
4. Stop LocalAI. Package the image tar, models directory, and LocalAI data directory.
5. Create SHA-256 hashes, transfer on approved media, verify hashes on the isolated side, and load the image.

# AMD64 staging
docker pull --platform linux/amd64 localai/localai:v4.4.3-gpu-nvidia-cuda-12
docker save -o localai-v4.4.3-linux-amd64.tar \
  localai/localai:v4.4.3-gpu-nvidia-cuda-12

# DGX Spark ARM64 staging
docker pull --platform linux/arm64 \
  localai/localai:v4.4.3-nvidia-l4t-arm64-cuda-13
docker save -o localai-v4.4.3-linux-arm64-dgx-spark.tar \
  localai/localai:v4.4.3-nvidia-l4t-arm64-cuda-13

# Linux checksums
sha256sum localai-*.tar /srv/localai/models/* > SHA256SUMS.txt

# Destination
sha256sum -c SHA256SUMS.txt
docker load -i localai-v4.4.3-linux-amd64.tar

# Windows checksums
Get-ChildItem D:\LocalAI-Transfer -File -Recurse |
  Get-FileHash -Algorithm SHA256 |
  Export-Csv D:\LocalAI-Transfer\SHA256SUMS.csv -NoTypeInformation

Local AI setup

Connect KombatSync and verify every modality

1. Set matching credentials

LocalAI uses LOCALAI_API_KEY. KombatSync Compose uses KOMBAT_AI_API_KEY. Set both to the same value, then recreate both containers. In KombatSync Settings use:

• Base URL: http://AI_SERVER_PRIVATE_IP:8081/v1
• Recap model: kombat-recap
• Transcription model: kombat-transcription
• Vision model: kombat-vision
• API key environment variable: KOMBAT_AI_API_KEY

2. Verify model inventory and chat

curl http://AI_SERVER_PRIVATE_IP:8081/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

curl http://AI_SERVER_PRIVATE_IP:8081/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"kombat-recap","messages":[{"role":"user","content":"Return JSON with a status field set to ready."}]}'

3. Verify transcription

curl http://AI_SERVER_PRIVATE_IP:8081/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "model=kombat-transcription" \
  -F "file=@radio-sample.wav"

4. Verify vision

Use the LocalAI web interface or send a chat-completions request containing a base64 image_url. Confirm the response identifies visible objects and text without attempting an internet URL.

5. Run a KombatSync acceptance mission

1. Enable AI, record short video/audio and representative DIS traffic, then stop.
2. Confirm the AI queue advances from queued to processing to completed.
3. Inspect transcript timestamps, vision observations, recap citations, LocalAI logs, and GPU utilization.
4. Disconnect the AI server from any external route and repeat.

docker logs -f local-ai
nvidia-smi --loop=1

Administration

Storage, backup, and recovery

• Plan capacity from source bitrates, not proxy bitrates. Eight hours × eight high-bitrate streams can consume terabytes.
• Keep at least one mission's worst-case capacity above the 15% warning threshold.
• New mission directories begin with the filesystem-safe mission name and include the recording suffix so duplicate mission names remain unique. Existing mission directories are not renamed during upgrade.
• Back up recordings-index.sqlite, its WAL/SHM files when present, and all mission directories as one consistent set while the service is stopped.
• Host-mounted network storage must be mounted before starting Compose. Do not mount NFS/SMB from inside the container.
• Deletion is intentionally manual. The deletion log records the mission, reclaimed bytes, time, and operator marker.
• On startup the catalog reconciles missing mission folders rather than crashing.

Support

Troubleshooting

Integration

Primary API reference

Primary sources

AI installation and model references

These links are references for administrators on a connected staging network. The documentation page does not request them automatically.

• LocalAI quickstart and OpenAI-compatible API
• LocalAI container image matrix, including NVIDIA and DGX Spark ARM64
• LocalAI audio transcription endpoint and backends
• LocalAI image-understanding chat API
• Docker Desktop GPU support on Windows/WSL2
• NVIDIA Container Toolkit installation
• Qwen3-VL-32B-Instruct official GGUF model card
• Qwen3.5-35B-A3B official model card
• Qwen3-ASR-1.7B official model card
• Whisper large-v3 model card

Model/provider guidance reviewed for V2.2.0 on 2026-06-21. Pin versions and re-run acceptance tests before changing a production model stack.