Installation

Secronyx is supplied to customers as standalone binaries, a macOS package, a Windows MSI, a Dockerfile with a Compose file, and a Helm chart. Your Secronyx account team provides the files for your platform; contact hello@secronyx.com if you need them.

Release assets

Releases are versioned vX.Y.Z. Each release contains the assets below.

secronyx-token-server is the optional OAuth token issuer used with --auth-server; most installations do not need it. See Authentication.

Every release file carries a signed build-provenance attestation that records the commit and the build that produced it. The macOS and Windows binaries are built natively on their own platforms.

Every binary the release workflow builds embeds its version, commit and build date via -ldflags "-X main.version=... -X main.commit=... -X main.date=...", so secronyx --version on a release asset tells you exactly which release you are running. Always install the binaries supplied for a release: secronyx --version then tells you exactly which release you are running.

Linux

chmod +x secronyx-linux-amd64
sudo install -m 0755 secronyx-linux-amd64 /usr/local/bin/secronyx
secronyx --version
secronyx --query get_cpu_info --json

Use secronyx-linux-arm64 on arm64. The binary is static and has no library or package dependencies. Some collectors call system tools when they exist (journalctl, ss, lsof, package managers and so on) and return empty results when they do not; nothing needs to be installed for the server to start.

Audit logging defaults to /var/log/secronyx/audit.jsonl. Create that directory for the account that will run the server, or pass --audit-output with a writable path; otherwise events go to stderr, which is deliberate but noisy. See Audit logging.

macOS

Two options: the bare binary, or the installer package.

Binary

chmod +x secronyx-darwin-arm64
sudo install -m 0755 secronyx-darwin-arm64 /usr/local/bin/secronyx
secronyx --version

Use secronyx-darwin-amd64 on Intel. This is the right choice for a local MCP client such as Claude Desktop or Claude Code.

Installer package

secronyx-<version>-macos-universal.pkg contains a universal binary and is intended for managed fleets running in hybrid mode against the Secronyx service, not for a local stdio client. It installs:

The post-install script creates /etc/secronyx, sets ownership on the plist and loads the daemon with launchctl load. The daemon is KeepAlive on unsuccessful exit, throttled to one restart per 10 seconds, and runs at nice level 10.

Interactive installation (open the package or double-click it) walks through welcome, licence, a login pane and a conclusion screen. For unattended installation supply an API key in one of two ways; the script reads and then deletes install.conf, and records the key in the daemon's environment and in /etc/secronyx/agent.env (mode 0600):

# Option 1: a configuration file the installer consumes
sudo mkdir -p /etc/secronyx
echo "API_KEY=sk_your_api_key_here" | sudo tee /etc/secronyx/install.conf
sudo installer -pkg secronyx-<version>-macos-universal.pkg -target /

# Option 2: an environment variable passed through sudo
export SECRONYX_API_KEY="sk_your_api_key_here"
sudo -E installer -pkg secronyx-<version>-macos-universal.pkg -target /

The build script signs the package only when INSTALLER_SIGNING_IDENTITY is set, and the release workflow does not set it, so treat the published package as unsigned and install it from the command line or through your MDM rather than relying on Gatekeeper's double-click path.

To remove it:

sudo launchctl unload /Library/LaunchDaemons/com.secronyx.agent.plist
sudo rm -f /usr/local/bin/secronyx
sudo rm -f /Library/LaunchDaemons/com.secronyx.agent.plist
sudo rm -rf /etc/secronyx
sudo rm -f /var/log/secronyx.log

Fleet deployment covers MDM and Jamf rollout.

Windows

Binary

Copy secronyx-windows-amd64.exe to wherever you keep tools, renamed secronyx.exe. It is a console application; for a local client such as Claude Code point the client at the .exe path.

.\secronyx.exe --version
.\secronyx.exe --query get_event_log --json

MSI installer

secronyx-<version>-windows-amd64.msi installs the agent as a Windows service for hybrid mode. Run it without arguments for the interactive wizard (welcome, licence, then an email and password login, then a confirmation page), or silently with an API key for unattended enterprise rollout:

msiexec /i secronyx-<version>-windows-amd64.msi /qn API_KEY=sk_your_api_key_here
msiexec /i secronyx-<version>-windows-amd64.msi /qn API_KEY=sk_xxx AGENT_NAME="Production-Server-01" /l*v install.log

The installer registers a service named Secronyx (display name "Secronyx Agent"), start type automatic, running as LocalSystem, with the binary at C:\Program Files\Secronyx\secronyx.exe. The MSI properties documented for deployment are API_KEY, SAAS_URL, WS_URL, WAKEUP_URL, AGENT_NAME, POLL_TIMEOUT, IDLE_TIMEOUT and INSTALLFOLDER; INSTANCE_ID, DEVICE_TOKEN and DEBUG are defined too. Uninstall with msiexec /x secronyx-<version>-windows-amd64.msi /qn. Windows service documents each property, the credential store and Group Policy deployment.

Docker and Compose

Secronyx ships with a Dockerfile (multi-stage: golang:1.22-alpine builder, alpine:3.19 runtime with ca-certificates, procps, lsof, iproute2, util-linux and coreutils, non-root user mcp with uid 1000, entrypoint /usr/local/bin/secronyx) and a docker-compose.yml. No image is published by the release workflow; Compose builds secronyx:latest locally.

cd secronyx
export SECRONYX_TOKEN="$(openssl rand -base64 32)"
docker compose up secronyx-http

Compose refuses to start without SECRONYX_TOKEN, publishes the port on 127.0.0.1:8080 only, mounts /proc and /sys read-only, and runs the container read-only with all capabilities dropped. The secronyx-stdio service is for stdio clients, the privileged profile adds pid: host and root for collectors that need them, and the auth profile adds the token server. See Docker and Compose.

Kubernetes

The Helm chart is at charts/secronyx (chart version 0.1.0). Its default image reference is ghcr.io/levantar-ai/secronyx; because the workflow does not publish an image you must build and push one and set image.repository and image.tag accordingly. The chart refuses to render without an authentication method, and refuses authentication without TLS unless mcp.allowInsecure=true, mirroring the binary's own start-up check:

kubectl create secret generic secronyx-token \
  --from-literal=token="$(openssl rand -base64 32)"
kubectl create secret tls secronyx-tls --cert=cert.pem --key=key.pem

helm install secronyx ./charts/secronyx \
  --set image.repository=registry.example.com/secronyx \
  --set image.tag=<version> \
  --set mcp.auth.token.secretRef.name=secronyx-token \
  --set mcp.tls.enabled=true \
  --set mcp.tls.secretName=secronyx-tls

See Kubernetes and Helm for scope values, OIDC and the ServiceMonitor.

Running as a service

Which service mechanism fits depends on the mode you run.

Hybrid mode: the service subcommand

secronyx service install registers the binary with the platform's service manager and is designed for hybrid mode. Everything after -- is passed to the service at start:

sudo secronyx service install -- --mode hybrid --api-key sk_xxx
sudo secronyx service start
sudo secronyx service status

• Linux writes /etc/systemd/system/<name>.service (default name secronyx) with ExecStart=<binary> service run <args>, Restart=on-failure, journal logging and hardening (NoNewPrivileges, ProtectSystem=strict, ProtectHome=read-only, PrivateTmp, ProtectKernelTunables, ProtectKernelModules, ProtectControlGroups), then runs systemctl daemon-reload and systemctl enable. Root is required.
• macOS writes /Library/LaunchDaemons/com.levantar.<name>.plist. Root is required.
• Windows creates a service through the Service Control Manager with automatic start and restart-on-failure recovery at 5, 30 and 60 seconds. Administrator is required.

The service runner accepts only the hybrid-mode flags (--mode, --api-key, --saas-url, --config-dir, --ws-url, --wakeup-url, --instance-id, --device-token, --poll-timeout, --idle-timeout, --token, and --transport). Passing --transport http to service install does not start an HTTP listener: the runner logs HTTP transport mode not yet implemented for Linux service (or ... Windows service) and idles until stopped. --name chooses a different unit or service name; names must match ^[a-zA-Z][a-zA-Z0-9_-]{0,62}$. service uninstall removes the registration.

HTTP mode: a unit you write

For a long-running HTTP listener invoke the binary directly from your own unit. A systemd example that serves loopback behind a TLS-terminating reverse proxy:

# /etc/systemd/system/secronyx.service
[Unit]
Description=Secronyx HTTP transport
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=secronyx
Group=secronyx
EnvironmentFile=/etc/secronyx/token.env
ExecStart=/usr/local/bin/secronyx --transport http --listen 127.0.0.1:8080 --audit-output /var/log/secronyx/audit.jsonl
Restart=always
RestartSec=5
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/var/log/secronyx

[Install]
WantedBy=multi-user.target

/etc/secronyx/token.env holds SECRONYX_TOKEN=<at least 32 random characters>, which the binary reads when --token is absent. ReadWritePaths matters: under ProtectSystem=strict the default audit directory is read-only and audit events would fall back to the journal. Create the directory and user, then:

sudo useradd --system --no-create-home --shell /usr/sbin/nologin secronyx
sudo install -d -o secronyx -g secronyx -m 0750 /var/log/secronyx
sudo systemctl daemon-reload
sudo systemctl enable --now secronyx

Serving TLS directly (--tls-cert, --tls-key) and binding a routable address, OIDC, API keys and mutual TLS are covered in Remote access over HTTP.

Upgrading

Replace the binary and restart whatever supervises it; there is no on-disk state to migrate for stdio or HTTP mode. Hybrid-mode agents keep certificates and credentials in the config directory (~/.secronyx by default, or the directory given by --config-dir), which survives an upgrade. Check secronyx --version afterwards and read for anything marked as a breaking change.