Sernixa Local Agent

Local MCP discovery agent for Sernixa. It scans only configured hosts, ports, and paths from the machine where it runs, then optionally syncs evidence-backed candidates to Sernixa.

Source release compatibility version: 1.6.7 (unpublished candidate). The current public discovery-agent release is 1.6.6.

Install

python -m pip install sernixa-agent

From a repo checkout during local development, prefer the shared target because it clears stale editable metadata, reinstalls the package, and prints the loaded cli.py path:

make agent-install-local
make agent-which

For internal rollout from a built wheel instead of PyPI:

python -m pip install --upgrade dist/sernixa_agent-1.6.7-py3-none-any.whl
pipx install --force dist/sernixa_agent-1.6.7-py3-none-any.whl
uv tool install --force dist/sernixa_agent-1.6.7-py3-none-any.whl

Build and verify release artifacts:

python packages/sernixa-agent/scripts/release.py --check
cd packages/sernixa-agent
python -m pip install build
python -m build
python scripts/release.py --build

pipx and uv tool are the preferred paths for operators who should not manage a Python virtual environment directly. Native single-file binaries are not published; use the PyPI wheel distribution for v1.6.

Initialize

Fast path for one machine:

python -m pip install --upgrade sernixa-agent
sernixa-agent init --machine-label "Security laptop"
printf '%s\n' "$APPROVED_SYNC_TOKEN" | sernixa-agent rotate-token --new-token-stdin --check-backend
sernixa-agent diagnose --check-backend
sernixa-agent enroll
sernixa-agent sync

The token is supplied through stdin and stored in ~/.sernixa/agent.token with 0600 permissions on Unix. It is never passed as a command-line argument or printed. Install is not verification; the first accepted sync is the evidence Sernixa can show. Install the user-level daemon only after this one-shot path is accepted.

The repository installer also supports --device-enroll for approved fleet rollouts. Keep the installer URL in organization-managed deployment tooling rather than copying a user-owned checkout path into customer instructions.

Device-code enrollment creates the enrollment inventory record after an authenticated admin approves the displayed code. Approval creates a revocable org-scoped sync token shown once to the admin, but does not install or deliver it to the device. The first accepted sync and auto-syncing state still require the token to be delivered through the tenant secret channel. Backend completion returns next_step_token_status=requires_manual_sync_token to make that second step explicit. Treat the current pilot path as four steps: enroll inventory, configure the sync token through the tenant secret channel, install it with sernixa-agent rotate-token --new-token-stdin, run sernixa-agent sync, then start daemon mode after accepted sync. See docs/mcp-local-agent-pilot-rollout.md before enabling a tenant pilot.

Create a non-secret config and private token file:

sernixa-agent init --machine-label "Security laptop"

Install an org-scoped Sernixa sync token through stdin:

printf '%s\n' "$APPROVED_SYNC_TOKEN" | sernixa-agent rotate-token --new-token-stdin --token-file ~/.sernixa/agent.token --check-backend

The token needs access to MCP registry read/discovery ingestion for the target organization. The agent sends it only as an HTTP bearer token and never includes it in scan JSON, logs, or evidence.

Check local readiness without scanning endpoints:

sernixa-agent status
sernixa-agent status --json
sernixa-agent diagnose --check-backend
sernixa-agent enroll
sernixa-agent enroll-device --open-browser
sernixa-agent sync
sernixa-agent daemon

enroll registers stable machine identity, non-secret label, and current agent version in Sernixa inventory. It does not scan endpoints or claim the machine is continuously online.

Auto-Discovery

Auto-discovery v2 means the helper is installed and enrolled once, usually by the standard installer or fleet deployment, then kept running as a daemon. After the first accepted sync appears in the MCP Control Plane, normal admins use Auto Discover now in the web UI. The daemon pulls scoped jobs and reports observations; Sernixa treats only accepted sync events as discovery evidence, and enrollment alone remains inventory evidence.

After the scan, an admin selects exact config-file candidates and chooses Approve & activate. The daemon receives only those device-bound targets, uses the same private token file as the enrolled agent, and invokes the Sernixa CLI to install each governed route. A transient task-result retry reuses the exact already-installed connection. Network and process sightings cannot be auto-activated, and installation alone is not reported as active; the dashboard waits for an API-authorized governed call.

Automatic activation requires the normal private token-file setup (mode 0600 on Unix) and Sernixa CLI 0.6.9 or newer. Environment-only agent credentials continue to support discovery but fail activation closed because a restarted MCP host would not have a durable private credential reference.

CLI commands below are support, debugging, and rollout tools. They are not the recurring customer workflow after the helper is installed and syncing. The web/API Auto Discover job path is generally available. Operators may set MCP_AUTO_DISCOVER_ENABLED=false as an environment-wide incident kill switch; it is not a beta or customer allowlist.

sernixa-agent daemon --interval 300
sernixa-agent daemon --once
sernixa-agent run
sernixa-agent install-service --platform auto
sernixa-agent uninstall-service --platform auto --stop
sernixa-agent status --json

Defaults:

• successful runs sleep for 300 seconds
• intervals are bounded from 30 seconds to 24 hours
• transient failures use exponential backoff with jitter, capped at 900 seconds
• scans never overlap inside a process, and a lock file prevents two daemon processes from running the same agent loop
• non-secret daemon state is written to ~/.sernixa/agent-state.json
• the default daemon lock file is ~/.sernixa/agent.lock

Fail-closed errors such as missing auth, rejected tokens, disabled or revoked machines, unsupported payload versions, invalid signatures, and clock skew stop the daemon instead of silently degrading to partial success. Network and 429/5xx failures are retried with backoff and recorded in local state.

status --json reports daemon.health, daemon.status, last_successful_scan_at, last_successful_sync_at, backoff_seconds, next_run_at, last_error_category, configured_lock_file, and user-service installation state. It never prints the token value.

Linux and macOS service helpers write user-level templates only; they do not mint tokens or enable services without operator action:

sernixa-agent install-service --platform linux
systemctl --user daemon-reload
systemctl --user enable --now sernixa-agent.service
journalctl --user -u sernixa-agent.service -f

sernixa-agent install-service --platform macos
launchctl load ~/Library/LaunchAgents/com.sernixa.agent.plist
tail -f ~/Library/Logs/sernixa-agent.err.log

Windows uses a native automatic SernixaAgent service. Run from an elevated PowerShell session after the config and protected token source exist:

sernixa-agent install-service --platform windows --config "$env:USERPROFILE\.sernixa\agent.json"
sernixa-agent status --json
sernixa-agent uninstall-service --platform windows --stop

The Windows service stores only the config path under HKLM, runs through Service Control Manager, and does not put credentials in its command line. The package installs pywin32 only on Windows.

Generated services and the Windows host run sernixa-agent daemon --service-mode. In service mode, a deliberate fail-closed condition writes state and exits successfully so the service manager does not restart forever on a revoked or invalid key. Unexpected process crashes still restart.

Upgrade

Print the supported public-package upgrade commands and compatibility expectations:

sernixa-agent upgrade
sernixa-agent upgrade --json

For existing pipx installs, upgrade from PyPI and run:

pipx install --force sernixa-agent==1.6.6
sernixa-agent diagnose --check-backend
sernixa-agent enroll
sernixa-agent sync

For uv tool installs:

uv tool install --force sernixa-agent==1.6.6
sernixa-agent diagnose --check-backend
sernixa-agent sync

Saved scans with unsupported schemas are not migrated automatically. After an upgrade, rerun sernixa-agent scan or sernixa-agent sync so the backend receives a current payload.

Scan

sernixa-agent scan
sernixa-agent scan --ports 3000,8000,8080
sernixa-agent scan --hosts 127.0.0.1 --paths /mcp,/sse --output /tmp/sernixa-mcp-scan.json

scan prints a safe count/source summary. Pass --output to explicitly write a sernixa.mcp.local_agent.discovery.v1 payload to a local file. It does not inspect arbitrary networks unless you explicitly pass hosts. Default candidate paths include /mcp, /sse, /messages, /rpc, /jsonrpc, /api/mcp, and well-known MCP metadata paths.

To force execution from this checkout and verify the loaded module:

make agent-install-local
make agent-version-check
make agent-which
make agent-cli ARGS="sync"
./scripts/run_dev_cli.sh --version-check
./scripts/run_dev_cli.sh sync

The version check is part of the packaged sernixa-agent CLI and prints the executing cli.py path plus active sync candidate whitelist. which sernixa-agent normally points at a Python bin shim; sernixa-agent --version-check is the authoritative check for the source file loaded by that shim. It never prints discovery results or environment values.

Sync

Preferred local setup uses the token file created by init:

sernixa-agent sync

For CI or ephemeral sessions, environment variables are also supported:

export SERNIXA_API_KEY=srnx_live_...
sernixa-agent sync --api-base-url https://api.sernixa.com

Use the API origin for sync. The CLI canonicalizes https://sernixa.com and https://www.sernixa.com to https://api.sernixa.com to avoid routing local agent sync through the web app.

You may also set SERNIXA_AGENT_TOKEN; it takes precedence over SERNIXA_API_KEY. --token-file and --token-env can override the configured auth source.

Sync retries transient network and 429/5xx failures, sends a stable Idempotency-Key, and keeps deterministic endpoint ordering and stable candidate result_id values for repeated runs. Retry diagnostics are written to stderr so JSON responses on stdout stay parseable.

The agent never captures environment variables, files, request bodies, or secrets from discovered endpoints.

Discovery-Only and Shadow AI Candidates

Use discover-only when you want reviewable candidates without enrolling the machine in fleet inventory:

sernixa-agent discover-only --ports 3000,8000 --paths /mcp,/sse
sernixa-agent discover-only --shadow-scope . --sync
sernixa-agent discover-only --include-default-configs --include-processes --sync
sernixa-agent discover-only --no-endpoint-scan --shadow-scope /repo --output shadow-candidates.json

Discovery-only mode labels every candidate as discovered_not_enrolled and adds guardrail evidence explaining that it is not enrollment, accepted sync proof, or verification. --shadow-scope is explicit and bounded: the agent inspects only supplied files/directories, skips common dependency/cache folders, looks for MCP and AI-agent markers in config/code/container files, and records markers plus file location metadata without copying secret values.

--sync sends candidates to the existing Sernixa discovery review queue through POST /api/mcp/discovery/sync. It does not import or register anything; an admin still has to approve for enrollment, ignore, mark out of scope, defer, or import candidates separately. Each review action records actor, timestamp, reason, evidence source, and evidence codes. Process discovery is opt-in and reads process names only; command arguments and environment variables are not captured.

Config

By default the agent reads ./sernixa-agent.json first and then ~/.sernixa/agent.json.

Precedence is:

1. CLI flags
2. Config file
3. Environment variables such as SERNIXA_API_BASE_URL, SERNIXA_AGENT_ID, and SERNIXA_MACHINE_LABEL
4. Built-in defaults

{
  "agent_id": "sernixa-agent-workstation",
  "api_base_url": "https://api.sernixa.com",
  "daemon_interval_seconds": 300,
  "daemon_lock_file": "~/.sernixa/agent.lock",
  "daemon_max_backoff_seconds": 900,
  "daemon_stale_after_seconds": 900,
  "daemon_state_file": "~/.sernixa/agent-state.json",
  "hosts": ["127.0.0.1"],
  "machine_label": "Security laptop",
  "paths": ["/mcp", "/sse", "/api/mcp"],
  "ports": [3000, 8000, 8080],
  "sync_retries": 2,
  "sync_timeout_seconds": 10.0,
  "timeout_seconds": 1.5,
  "token_file": "~/.sernixa/agent.token"
}

Unknown config keys and wrong JSON types fail fast with exit code 3. Missing auth exits with code 4. Sync failures exit with code 5.

Machine Inventory

Each scan includes a stable, non-secret machine_id, the optional machine_label, agent_version, scan_fingerprint, and payload_schema. The raw hostname is not emitted. Recent syncs in Sernixa use these fields to show which enrolled machine produced each scan.

Change a label by editing machine_label in ~/.sernixa/agent.json or by running commands with --machine-label. The stable machine_id does not change, so history remains tied to the same enrolled machine.

Rotate a token with the admin dashboard and local handoff loop:

1. Security admin marks token rotation requested for the machine.
2. Operator receives the replacement token through the approved secret channel.
3. Operator replaces the local token without echoing it:

sernixa-agent rotate-token --new-token-stdin --check-backend

For non-interactive shells, use --new-token-env SERNIXA_REPLACEMENT_TOKEN. The command writes only the configured token file, sets mode 0600, and never prints the old or new token. It does not mint tokens or prove the token has synced.

4. Admin marks the dashboard rotation as local install complete after the local file is replaced. This is an audit marker, not backend verification.
5. Operator runs sernixa-agent sync. The dashboard changes to verified_after_rotation only after Sernixa receives a successful sync from that machine after the install marker.

sernixa-agent diagnose --check-backend proves backend reachability, not token verification. The rotate-token command prints the expected verification step as sernixa-agent sync so support can distinguish local replacement from dashboard verification. If sync fails, share CLI stderr with support; support can log reminder, backend recheck, owner-contact, or revoke/re-enroll escalation actions in the dashboard. Those actions are audit records only; they do not deliver tokens, re-enable machines, or verify rotation. Do not place tokens in scan output, config commits, shell history, or rollout scripts.

Compatibility

The backend accepts sernixa.mcp.local_agent.discovery.v1 payloads from sernixa-agent >=1.0,<2.0. Saved scans with another payload schema or missing required fields are rejected before sync.