← All docs

VPC / On-Prem Collector

Run Cisora inside your own VPC. Agent events never leave your network until you choose to relay them.

What is the VPC Collector?

The Cisora VPC Collector is a lightweight Docker container that runs inside your network. It exposes the same event ingest API as Cisora SaaS, so your agents can report locally without any data leaving your environment. The collector buffers events and either:

  • Relay modeBuffers events locally and ships them to Cisora every 10 seconds. Full dashboard, alerting, and compliance reporting.
  • Air-Gapped modeEvents are written to a local NDJSON file and never sent anywhere. For environments with zero external connectivity.

Why use a VPC Collector?

  • —Data sovereignty — agent inputs/outputs stay inside your perimeter until explicitly relayed.
  • —Air-gapped compliance — meet FEDRAMP, IL-4/IL-5, or internal policies requiring zero external egress.
  • —Latency — local ingest is faster; no added round-trip to Cisora SaaS for every event.
  • —Resilience — collector buffers up to 10,000 events if the upstream is temporarily unreachable.

Setup in 3 steps

1

Register a collector in the dashboard

Go to Settings → VPC Collectors and click Register Collector. Choose a name, description, and mode. You will receive a COLLECTOR_TOKEN and COLLECTOR_ID — save both, they are shown only once.

2

Run the collector in your VPC

Use docker-compose (recommended):

version: '3.8'
services:
  cisora-collector:
    image: cisora/collector:latest
    environment:
      COLLECTOR_TOKEN: ${COLLECTOR_TOKEN}
      COLLECTOR_ID: ${COLLECTOR_ID}
      CISORA_API_URL: https://cisora.io
      MODE: relay          # relay | air_gapped
    ports:
      - "4001:4001"
    volumes:
      - ./events:/app/events   # only needed for air_gapped mode
    restart: unless-stopped

Or with docker run:

docker run -d \
  -e COLLECTOR_TOKEN=csc_<your-token> \
  -e COLLECTOR_ID=<your-collector-uuid> \
  -e CISORA_API_URL=https://cisora.io \
  -e MODE=relay \
  -p 4001:4001 \
  cisora/collector:latest
3

Point your agent SDK at the collector

# Python SDK
import os
os.environ["CISORA_BASE_URL"] = "http://your-collector:4001"

# or pass directly
from cisora import Cisora
cisora = Cisora(api_key="...", base_url="http://your-collector:4001")

The collector exposes the same POST /api/agent/events endpoint as Cisora SaaS, so no other SDK changes are needed.

Health check endpoint

The collector exposes a health endpoint for Kubernetes liveness/readiness probes and load balancers:

GET http://your-collector:4001/health

# Response:
{ "ok": true, "buffered": 42, "mode": "relay" }
  • buffered — events waiting to be flushed to Cisora
  • mode — relay or air_gapped

Air-gapped mode

Set MODE=air_gapped to disable all outbound network calls. Events are appended as NDJSON to /app/events/events.ndjson inside the container (mount a volume to persist them). No heartbeats are sent. The collector never phones home.

The NDJSON file can be imported into Cisora SaaS manually or reviewed offline with any standard log tooling.