AgentSOC Syslog Beacon CLI

Lightweight, background-running log forwarder (beacon) for AgentSOC.

Overview

The Syslog Beacon CLI allows you to configure, install, and run a lightweight log forwarding daemon that sends system logs to an AgentSOC ingest endpoint.

Requirements

• Node.js v16 or higher

Installation

Installers are hosted on the marketing site (not duplicated in this repo):

| Method | URL / command | |--------|----------------| | macOS / Linux (curl) | curl -fsSL https://agentsoc.com/connectors/beacon.sh \| bash | | Windows PowerShell | irm https://agentsoc.com/connectors/beacon-install.ps1 \| iex | | Windows (batch) | Download and run beacon-install.bat | | npm | npm install -g @agentsoc/beacon |

Published package: @agentsoc/beacon (npm scope is lowercase agentsoc).

The syslog-beacon command is also installed as an alias for the same CLI.

Run from source (this monorepo)

If you have the repository cloned and Bun installed:

cd apps/connectors/syslog-beacon-cli
bun install
bun run build:simple
npm install -g .

Then use beacon / syslog-beacon like a normal global install:

beacon config --key <key> [--env production|development]
beacon run

Usage

The CLI provides the following commands:

Configure

Configure the AgentSOC connection (saves to a local configuration file):

beacon config --key <key> [--env production|development]

Parameters:

• --key, -k <key>: AgentSOC API Key (required; e.g., sk_1234567890abcdef)
• --env, -e <env>: production (default) or development — selects default URLs for log ingest and for beacon status (platform API). Production: ingest https://ingest.agentsoc.com/api/v1/webhooks/syslog, platform https://api.agentsoc.com. Development: ingest http://localhost:8110/api/v1/webhooks/syslog, platform http://localhost:8100.

Examples:

beacon config --key sk_1234567890abcdef
beacon config --key sk_1234567890abcdef --env development

Note: If you run bun run src/cli.ts config without --key, you'll receive usage help. URLs are not set in config.json (use --env or AGENTSOC_ENV). At runtime you can override ingest with AGENTSOC_INGEST_URL and the platform API (for beacon status only) with AGENTSOC_PLATFORM_URL or AGENTSOC_PLATFORM_API_BASE_URL.

Run Foreground Daemon

Run the forwarder daemon in the foreground:

beacon run [options]

Options:

• --batch-size <n>: Set the batch size for log forwarding (default: 25)
• --flush-ms <n>: Set the flush interval in milliseconds (default: 2000)

Example:

beacon run --batch-size 50 --flush-ms 5000

Note: You can use AGENTSOC_API_KEY instead of saving a key in config. Use AGENTSOC_ENV (production / development) to override the saved environment for a single run. AGENTSOC_INGEST_URL overrides log shipping only. For beacon status, the CLI calls GET {platform}/api/v1/siem/beacon/validate/key (default platform from env above); override the platform origin with AGENTSOC_PLATFORM_URL or AGENTSOC_PLATFORM_API_BASE_URL if ingest and API live on different hosts.

Install Service

Install the background service daemon (systemd on Linux, launchd on macOS):

sudo "$(command -v beacon)" install

On macOS the plist is written under /Library/LaunchDaemons/, and on Linux the unit file goes under /etc/systemd/system/—both require root. The service runs as your login user (via SUDO_USER when you use sudo), so it uses the same config directory as beacon config—not root’s home.

sudo beacon says “command not found”: sudo resets PATH, so it often cannot see npm/nvm global bins. Use sudo "$(command -v beacon)" install (as above), or sudo env "PATH=$PATH" beacon install, or the full path from which beacon.

Beacon is not configured under sudo: the install command reads config.json from the user who invoked sudo (SUDO_USER, e.g. /home/ubuntu/.config/...), not from /root, so it matches beacon config run as your normal account.

systemd shows inactive: the unit must use the full path to node (or bun). A bare node in ExecStart fails under systemd when Node is installed via nvm/fnm, because the service does not load your shell PATH. Re-run sudo "$(command -v beacon)" install after upgrading the CLI so the unit is rewritten; then systemctl status syslog-beacon or journalctl -u syslog-beacon -n 20 if it still fails.

Status and stats

Show whether the systemd/launchd service is present, resolve organization name and API key label via the platform API (GET /api/v1/siem/beacon/validate/key using your ingest key), and print forwarding counters from the local stats file:

beacon status

Use beacon status --json for machine-readable output (includes validateKeyUrl on errors).

After successful batches, the CLI updates stats.json next to your config (same config directory as config.json—for example ~/Library/Application Support/agentsoc-beacon/ on macOS). The file tracks logsForwarded, batchesSucceeded, batchesFailed, optional lastError, and updatedAt. The background service runs as the installing user (see Install Service above), so stats stay alongside your user config.

The marketing site’s product demo terminal runs through beacon status so visitors can see a sample of this output.

Development

• Start the daemon using npm script: npm start or bun run start
• Install service using npm script: npm run install-service or bun run install-service
• Build the distributable: npm run build:simple (compiles TypeScript to dist/)

Building & distribution

Build the package

npm run build:simple

Publish to npm

From this directory, after bumping version in package.json:

npm publish --access public

Public install entrypoints live under https://agentsoc.com/connectors/ (beacon.sh, beacon-install.ps1, beacon-install.bat).