Sotero Runtime macOS Installation and Developer Setup Guide

Before you begin

What the installer adds

The macOS package installs a self-contained Sotero daemon, shared developer resources, a system-wide LaunchAgent definition, and native log-rotation settings. On macOS, runtime configuration and state remain in your own home directory and are not overwritten during upgrades. (This differs from Linux and Windows, where the background service runs under a separate system account, not a human user's home directory.)

Requirements

• An Apple silicon Mac. Run uname -m and confirm arm64. This package is not intended for Intel x86_64 Macs.
• A macOS account with administrator rights for package installation.
• Terminal access for initial configuration, health checks, and developer operations.
• The official .pkg and, when supplied, its matching .sha256 checksum file.

Download Sotero Runtime

1. Open the Download link from the site navigation and sign in with Google, Microsoft, or your Sotero email and password. Create an account if you don't already have one.
2. Review and accept the End User License Agreement. Marketing or product-contact consent, when presented separately, is optional.
3. Choose macOS Apple silicon arm64 and download sotero-runtime-0.0.2-macos-arm64.pkg.

Install with the macOS Installer

Use this GUI path for normal workstation installation. The package may ask for an administrator password or Touch ID. Installing over an existing 0.0.2 installation refreshes the installed files while preserving ~/.sotero.

cd ~/Downloads
shasum -a 256 -c sotero-runtime-0.0.2-macos-arm64.pkg.sha256
pkgutil --check-signature sotero-runtime-0.0.2-macos-arm64.pkg

If no checksum sidecar is supplied, your release administrator should provide the expected SHA-256 value through a trusted channel.

1. In Finder, open Downloads and double-click sotero-runtime-0.0.2-macos-arm64.pkg.
2. On the Introduction screen, click Continue.
3. Review the destination and installation type. The package installs on the system volume; click Install.
4. Authenticate with an administrator account when macOS requests approval.
5. Wait for the successful installation message, then click Close.

Install from Terminal

Use this equivalent method for scripted workstation setup or when you want Installer output in the terminal.

cd ~/Downloads
sudo installer -pkg ./sotero-runtime-0.0.2-macos-arm64.pkg -target /

A successful run ends with installer: The install was successful. The package post-install output also identifies the daemon, shared files, service, logs, and user configuration locations.

Configure the first run

Choose how to provide the required secret

The required [control].signing_key_secret performs two security jobs: it encrypts the persisted JWT signing key and authenticates Control API operations. It must contain at least 32 bytes.

For the multiple-machines case, macOS ships openssl in Terminal, so you can generate a portable high-entropy secret the same way as on Linux:

openssl rand -hex 32

Run the setup wizard

1. Open Terminal and run sotero-daemon without sudo.
2. At the hidden Signing key secret prompt, enter an approved shared secret or press Enter to generate one for local use.
3. Wait until the daemon reports that it is ready on ~/.sotero/daemon.sock.
4. Press Control+C to stop this temporary foreground process.
5. Run sotero-daemon config validate. Continue only when it reports that configuration is complete.

Start and verify the background service

1. Restart the registered LaunchAgent so it reads the new configuration.
2. Check supervisor state and application health.
3. Query the liveness endpoint over the local Unix socket.

sotero-daemon service restart
sotero-daemon service status
curl --unix-socket ~/.sotero/daemon.sock http://localhost/healthz
curl --unix-socket ~/.sotero/daemon.sock http://localhost/readyz

Use the ready endpoint for deployment checks because it verifies the registry, policy catalog, signing and replay store, and Control authentication — not only whether the process exists.

Service lifecycle commands

Install and uninstall require sudo because they write under /Library/LaunchAgents. Start, stop, restart, and status operate in your user login session and do not require sudo.

Use Sotero Runtime as a developer

Use the Unix socket from an application

macOS defaults to a Unix domain socket, not a browser-addressable TCP port. This keeps the service local to the user account. Copy the packaged thin client into your Python project under an importable filename.

cp /usr/local/share/sotero-runtime/thin-client.py ./sotero_thin_client.py
python -m pip install "httpx>=0.27" "PyJWT[crypto]>=2.8" "cryptography>=42"

from pathlib import Path
from sotero_thin_client import ThinClientRuntime

runtime = ThinClientRuntime()
runtime.onboard(
    daemon_url="http://daemon",
    socket_path=Path.home() / ".sotero" / "daemon.sock",
)

When Control API authentication is required, supply the secret through SOTERO_CONTROL_KEY_SECRET or the api_key argument using your application's secret-management mechanism. Do not hard-code it.

Install the bundled Claude Code skills

sotero-daemon install-skills
# Default destination: ~/.claude/skills

Run this command without sudo. It updates bundled Sotero skill directories but does not touch unrelated skills. Restart Claude Code if it was already running and does not detect the newly installed skills.

Useful operator commands

Configuration and file reference

When changes take effect

• Changes to sotero.toml and SOTERO environment variables require a service restart.
• A configured agents.json file and a configured Rego policy file are watched and hot-reloaded.
• When both sotero.toml and a matching environment variable contain a value, sotero.toml wins.
• For the LaunchAgent, put required secrets in sotero.toml or use a purpose-built service environment mechanism; exports in your interactive shell are not inherited.

Logs and troubleshooting

Detailed diagnostics

launchctl print gui/$(id -u)/ai.sotero.runtime | head -40
tail -100 /usr/local/var/log/sotero-daemon/daemon-error.log
ls -la ~/.sotero
sotero-daemon config validate
sotero-daemon service status

Upgrade Sotero Runtime

1. Back up ~/.sotero before a major upgrade, especially sotero.toml, keys.db, registry.db, security.db, and audit.jsonl.
2. Download and verify the newer official .pkg.
3. Install it over the existing version using Installer or sudo installer. The package unloads the previous LaunchAgent, replaces product files, re-registers it, and preserves per-user state.
4. Run sotero-daemon config validate, restart the service, and confirm running and healthy.

sotero-daemon config validate
sotero-daemon service restart
sotero-daemon service status

Uninstall Sotero Runtime

Preserve or remove user data deliberately. The standard removal below deletes installed product files and service registration but leaves ~/.sotero in place, so a reinstall can resume with the same configuration, keys, registry, and audit history.

Remove the application and service

sudo sotero-daemon service uninstall
sudo rm -f /usr/local/bin/sotero-daemon
sudo rm -rf /usr/local/share/sotero-runtime
sudo rm -rf /usr/local/var/log/sotero-daemon
sudo rm -f /etc/newsyslog.d/sotero-daemon.conf
sudo pkgutil --forget ai.sotero.runtime

These commands do not remove ~/.sotero. Verify that the command and LaunchAgent are gone with:

test ! -e /usr/local/bin/sotero-daemon && echo "binary removed"
test ! -e /Library/LaunchAgents/ai.sotero.runtime.plist && echo "service removed"

Optionally remove all user data

cp -a ~/.sotero ~/Desktop/sotero-backup
rm -rf ~/.sotero

Quick reference

Expected steady state: configuration complete, supervisor running, health healthy, and both health endpoints returning success.