Installation

Secronyx is distributed as standalone binaries, a macOS package, a Windows MSI, a Dockerfile with a Compose file, and a Helm chart. The binaries and the two installers are produced from the same repository by the release workflow, so a release version means the same thing whichever of those you install; the Dockerfile, the Compose file and the Helm chart ship in the repository and are versioned separately (the chart is at 0.1.0). This page covers getting the software onto a host; Getting started covers the first run and Connect an AI client the client side.

Release assets

Release tags are vX.Y.Z and are created by semantic-release from conventional commits (see Releases and versioning). Every asset below is attached to the GitHub release; `https://github.com/levantar-ai/secronyx/releases/latest` mirrors only the five `secronyx` binaries, which the CI workflow syncs there on each push to main. <version> is the tag without its v prefix:

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

The Linux binaries are built by the slsa-framework/slsa-github-generator Go builder, which also uploads a provenance file next to each binary named <asset>.intoto.jsonl (for example secronyx-linux-amd64.intoto.jsonl). The macOS and Windows binaries are built natively because they need CGO, which the SLSA builder cannot cross-compile. The attestation job waits on three smoke tests, which run --version and one query per tool family against secronyx-linux-amd64, secronyx-darwin-arm64 and secronyx-windows-amd64.exe on their own platforms. It then attaches a GitHub build-provenance attestation to every asset in the table, including the .pkg and .msi.

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 take binaries from the GitHub release rather than from a CI artefact: artefacts are built without those flags, so --version reports nothing useful and they carry no provenance attestation.

Verifying a download

The workflow publishes no separate checksum file; the attestation binds the file digest to the workflow run that produced it. Verify with the GitHub CLI:

gh attestation verify secronyx-linux-amd64 --repo levantar-ai/secronyx

For the Linux binaries you can additionally verify the SLSA provenance against the source tag:

slsa-verifier verify-artifact secronyx-linux-amd64 \
  --provenance-path secronyx-linux-amd64.intoto.jsonl \
  --source-uri github.com/levantar-ai/secronyx \
  --source-tag v<version>

Both commands are the standard tools for the formats the workflow produces; neither is part of the repository.

Linux

curl -LO https://github.com/levantar-ai/secronyx/releases/latest/download/secronyx-linux-amd64
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

curl -LO https://github.com/levantar-ai/secronyx/releases/latest/download/secronyx-darwin-arm64
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

Download secronyx-windows-amd64.exe and run it from wherever you keep tools. It is a console application; for a local client such as Claude Code point the client at the .exe path.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-WebRequest -Uri "https://github.com/levantar-ai/secronyx/releases/latest/download/secronyx-windows-amd64.exe" -OutFile "secronyx.exe"
.\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

The repository ships 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.

git clone https://github.com/levantar-ai/secronyx
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.

Building from source

go.mod declares go 1.23.0 with toolchain go1.24.4; the release and CI workflows run Go 1.22 and let that toolchain line pull go1.24.4 in. There are no C dependencies for the Linux target.

git clone https://github.com/levantar-ai/secronyx
cd secronyx
go build -o secronyx ./cmd/secronyx
go build -o secronyx-token-server ./cmd/secronyx-token-server   # optional
./secronyx --version

To reproduce the release layout, stamp the version and use the same flags as the workflow:

CGO_ENABLED=0 go build -trimpath -tags=netgo \
  -ldflags="-s -w -X main.version=$(git describe --tags --always) -X main.commit=$(git rev-parse HEAD) -X main.date=$(date -u +%Y%m%dT%H%M%SZ)" \
  -o secronyx ./cmd/secronyx

Cross-compile with GOOS and GOARCH; the Linux target cross-compiles from anywhere. The macOS and Windows release binaries are built with CGO_ENABLED=1 on their own platforms, so build those natively if you need parity with the release.

GOOS=linux  GOARCH=arm64 go build -o secronyx-linux-arm64 ./cmd/secronyx
GOOS=darwin GOARCH=arm64 go build -o secronyx-darwin-arm64 ./cmd/secronyx
GOOS=windows GOARCH=amd64 go build -o secronyx-windows-amd64.exe ./cmd/secronyx

Run the unit tests with go test -race ./...; Contributing covers lint, gosec and the integration suite.

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 Releases and versioning for anything marked as a breaking change.