Sotero Runtime Ubuntu Installation and Developer Setup Guide

Before you begin

What the installer adds

The package installs a self-contained Sotero daemon, shared developer resources, and a systemd service registration. Unlike macOS, the service runs under a dedicated, unprivileged sotero-daemon system account — not root, and not your own login user. This means the background service's configuration and state live in a different location from the one you create when trying the daemon interactively as yourself.

Requirements

• Ubuntu x86_64. This guide was verified end to end on Ubuntu 26.04 LTS; other current LTS releases are expected to work the same way.
• A user account with sudo rights for package installation and service management.
• Terminal access for initial configuration, health checks, and developer operations.
• The official .deb 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 Linux x86_64 and download sotero-runtime-0.0.2-linux-x86_64.deb.

cd ~/Downloads
sha256sum -c sotero-runtime-0.0.2-linux-x86_64.deb.sha256

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

Install with apt

sudo apt install ./sotero-runtime-0.0.2-linux-x86_64.deb

What happens automatically. The package creates a dedicated sotero-daemon system account, installs /etc/systemd/system/sotero-daemon.service, and enables it (systemctl enable) — but does not start it yet, the same "register, don't start" posture as macOS and Windows. It also installs /etc/sotero-daemon/environment.example as a template for the one required secret.

Installing over an existing 0.0.2 installation refreshes the installed files while preserving both ~/.sotero/ and /var/lib/sotero-daemon/.sotero/.

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.

Run the setup wizard

1. Open a 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 Ctrl+C to stop this temporary foreground process.
5. Run sotero-daemon config validate. Continue only when it reports that configuration is complete.

This foreground copy is fine for a quick look, but it stops the moment you close the terminal or log out — it does not survive a reboot. For anything longer-lived, continue below.

Start and verify the background service

The package already registered sotero-daemon as a systemd service. It runs as the dedicated sotero-daemon account, so it uses its own configuration, separate from the one you just created as yourself: /var/lib/sotero-daemon/.sotero/sotero.toml.

1. Give it the one required secret via the environment file (never generated on the machine itself — reuse the same value across every machine that needs to trust each other's credentials).
2. Start the service and confirm it is active.

sudo cp /etc/sotero-daemon/environment.example /etc/sotero-daemon/environment
sudo nano /etc/sotero-daemon/environment

Fill in a real value for SOTERO_CONTROL_KEY_SECRET, save, and exit. Generate one with openssl rand -hex 32 if you don't already have one to reuse:

openssl rand -hex 32

sudo systemctl start sotero-daemon
systemctl status sotero-daemon

cd /tmp
sudo -H -u sotero-daemon sotero-daemon service status
sudo curl --unix-socket /var/lib/sotero-daemon/.sotero/daemon.sock http://localhost/healthz
sudo curl --unix-socket /var/lib/sotero-daemon/.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, uninstall, start, stop, and restart via the sotero-daemon service ... wrapper all require sudo on Linux. Plain systemctl start|stop|restart|status sotero-daemon work identically and are equally valid.

View live logs any time with:

sudo journalctl -u sotero-daemon -f

Use Sotero Runtime as a developer

Use the Unix socket from an application

Ubuntu defaults to a Unix domain socket, not a browser-addressable TCP port. Copy the packaged thin client into your Python project under an importable filename.

cp /usr/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

Interactive (~), your own account, vs. service, /var/lib/sotero-daemon/.sotero — same filenames, different parent directory:

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 systemd-managed instance, put required secrets in /etc/sotero-daemon/environment — a shell export in your own session never reaches a systemd-started process.

Logs and troubleshooting

Detailed diagnostics

sudo systemctl status sotero-daemon
sudo journalctl -u sotero-daemon -n 100 --no-pager
ls -la ~/.sotero
sudo ls -la /var/lib/sotero-daemon/.sotero
sotero-daemon config validate

Upgrade Sotero Runtime

1. Back up ~/.sotero/ and /var/lib/sotero-daemon/.sotero/ before a major upgrade, especially sotero.toml, keys.db, registry.db, security.db, and audit.jsonl.
2. Download and verify the newer official .deb.
3. Install it over the existing version with apt install. The package preserves both state directories and re-registers the systemd unit.
4. Run sotero-daemon config validate, restart the service, and confirm active and healthy.

sudo apt install ./sotero-runtime-<new-version>-linux-x86_64.deb
sudo systemctl restart sotero-daemon
sudo -H -u sotero-daemon sotero-daemon service status # run from /tmp

Uninstall Sotero Runtime

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

Remove the application and service

sudo apt remove sotero-runtime

Verify the binary and unit are gone:

test ! -e /usr/bin/sotero-daemon && echo "binary removed"
systemctl status sotero-daemon # expect: "could not be found"

This does not remove the dedicated sotero-daemon system account, ~/.sotero/, or /var/lib/sotero-daemon/.sotero/.

Optionally remove all user data

cp -a ~/.sotero ~/Desktop/sotero-backup
sudo cp -a /var/lib/sotero-daemon/.sotero /root/sotero-service-backup
rm -rf ~/.sotero
sudo rm -rf /var/lib/sotero-daemon/.sotero
sudo userdel sotero-daemon
sudo groupdel sotero-daemon
sudo rm -rf /etc/sotero-daemon

Quick reference

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