Headless Agent API and CLI

PacketSafari on-prem can run Agent analysis from the web UI, an HTTP streaming API, or a terminal client.

The headless API and CLI use the same backend Agent runtime as the browser experience. They do not bypass capture access, indexing readiness, deployment license limits, AI policy, anonymization policy, or egress controls.

When to use headless Agent

Use the headless path when you want to:

• run repeatable analysis from an operator terminal
• integrate PacketSafari Agent with SOC workflows or internal automation
• save streamed Agent events as JSON lines
• constrain an investigation to the command-line/TShark analysis lane
• reproduce an investigation without driving the browser UI

Use the web UI when an analyst needs the full packet list, decode pane, graphs, report view, and visual pivots.

Prerequisites

Before starting a headless run:

1. Upload or capture the PCAP in PacketSafari.
2. Wait for indexing/readiness to complete.
3. Confirm the user or token has access to the capture.
4. Confirm Agent is enabled by the installed license.
5. Confirm the on-prem AI policy allows the capture. By default, Agent and Copilot can be blocked for captures that are not marked anoncap-anonymized.
6. If using a local or external model endpoint, confirm the destination is configured and approved.

For AI policy details, see On-Prem AI anonymization policy and Local models and external AI approval.

HTTP streaming API

Endpoint:

POST /api/v2/ai/agent/run
Accept: text/event-stream
Content-Type: application/json
Authorization: Bearer <token>

Minimal payload:

{
  "pcapid": "capture-id",
  "initial_prompt": "Find suspicious DNS activity",
  "mode": "cli",
  "source": "agent",
  "stream_tokens": true,
  "skip_question_framing": true,
  "include_artifacts": true
}

Supported modes:

The response is Server-Sent Events. Each event contains an event: type and a JSON data: payload. API clients should tolerate progress, tool, transcript, token, final, and error events.

Example:

curl -N \
  -H "Authorization: Bearer $PACKETSAFARI_TOKEN" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "pcapid": "capture-id",
    "initial_prompt": "Summarize top protocols and suspicious endpoints",
    "mode": "cli",
    "source": "agent",
    "stream_tokens": true,
    "skip_question_framing": true,
    "include_artifacts": true
  }' \
  "$PACKETSAFARI_BASE_URL/api/v2/ai/agent/run"

CLI client

The native PacketSafari binary includes a CLI client for login, upload, status checks, and Agent runs.

Log in once:

packetsafari auth login \
  --server "$PACKETSAFARI_BASE_URL" \
  --username analyst@example.com

The login command stores a local cookie session under ~/.packetsafari/. Use PACKETSAFARI_TOKEN or --token instead when your automation already has a bearer token.

Upload a PCAP:

packetsafari upload ./trace.pcapng

The upload command prints the new capture id. Use that id for later status or Agent runs:

packetsafari status <pcapid>

Analyze an existing capture:

packetsafari analyze <pcapid> "Summarize the trace" \
  --mode cli \
  --format ndjson

Upload and analyze in one command:

packetsafari run ./trace.pcapng \
  "Find likely exfiltration paths and list evidence frames" \
  --mode cli \
  --format ndjson

Environment defaults:

Output formats:

Example bearer-token automation run:

packetsafari analyze capture-id \
  "Find likely exfiltration paths and list evidence frames" \
  --token "$PACKETSAFARI_TOKEN" \
  --mode cli \
  --format ndjson > analysis-events.ndjson

Operational notes

• The CLI does not inspect packets locally. It sends the request to PacketSafari and renders the streamed response.
• cli and tshark modes use the deployment's configured Agent command-line execution controls.
• If the restricted command-line lane is disabled by deployment policy, use standard mode or ask an administrator to enable the appropriate Agent execution setting.
• External model calls, local model endpoints, and custom AI hosts remain subject to on-prem egress approval.
• Long-running runs consume the same Agent quota/license allowance as browser-launched runs.

Troubleshooting