Ryker / Docs / Running Ryker

Running Ryker

Use the Compose helper in your Ryker checkout to manage the installation. It uses the same project, saved image versions, and data each time.

What runs on the host

The Compose project ryker contains PostgreSQL (database), the Ryker application (ryker), a co:op worker (ryker-coop), and the worker’s private Docker daemon (ryker-coop-docker). Data lives in named volumes. The owner-only .ryker/compose.env stores image versions, listening addresses, and generated keys.

Voice transcription and search by meaning use separate CPU model services. Together their images take about 4 GB and they use about 3.5 GB of memory; the first build downloads about 2.8 GB. If a model cannot start, Ryker reports it and continues with reduced functionality. See the model service reference for settings and alternatives.

PostgreSQL holds pending requests, replies, approvals, follow-ups, schedules, and memory. Restarting Ryker resumes pending work. Waiting for an approval, merge, or scheduled time holds no model or worker.

Start, stop, and inspect services

Check health and recover stopped work

scripts/compose.sh status
curl --fail http://127.0.0.1:4321/healthz
curl --fail --include http://127.0.0.1:4321/readyz

/healthz checks the PostgreSQL connection. /readyz checks that runtimes are alive and due work is progressing; its x-ryker-version header identifies the running code. /metrics exposes queue, delivery, worker, and retention measurements.

When readiness fails, read scripts/compose.sh logs. For an individual request, inspect its timeline and Failures in the console. Use the available retry controls instead of editing database rows.

After an upgrade, send a real request through the integration your team uses. A healthy process alone does not prove that a Slack reply or GitHub update was delivered.

Access a remote installation

Listeners bind to 127.0.0.1 by default. Keep them local and use a tunnel or HTTPS reverse proxy for remote access.

Slack uses outbound Socket Mode, so it needs no public port. PostgreSQL and the worker connection stay private. Anyone who can reach the listener can read health and readiness. Metrics allow anonymous access on loopback; a published address requires a signed-in user.

For an SSH tunnel, run this on your computer with your host name, then open http://127.0.0.1:4321:

ssh -N -L 4321:127.0.0.1:4321 user@your-ryker-host

For shared HTTPS access, point a tunnel at http://localhost:4321, set RYKER_CONTROL_PUBLIC_URL in .ryker/compose.env to the external address, and run scripts/compose.sh start. Follow the Cloudflare setup guide for optional Access integration. See console sign-in for links and invitations.

For direct webhook delivery, use the supplied Nginx configuration, which exposes signed ingress paths and returns 404 elsewhere. Set RYKER_GITHUB_PUBLIC_URL and RYKER_WEBHOOK_PUBLIC_URL, then run scripts/compose.sh start. The network reference covers Docker forwarding addresses.

Back up and restore

Create a backup before upgrading:

scripts/compose.sh backup

The owner-only archive in .ryker/backups/ includes the database, private state, worker sign-in and identity, and generated environment with the decryption keys. Keep a protected copy off the host.

To restore, name the backup you want:

scripts/compose.sh restore .ryker/backups/ryker-YYYYMMDDTHHMMSSZ.tar.gz

Restore checks the archive’s keys against an existing installation. On a new installation it restores the archived keys before the database. It starts and checks the version recorded in the backup; that image must already be available. Newly generated keys cannot decrypt the old database.

Upgrade the application

Move your clean checkout to the published commit you intend to run, back up, then upgrade:

git pull --ff-only
scripts/compose.sh backup
scripts/compose.sh upgrade

When an origin is configured, the commit must be on its main branch. The helper derives the image version from the commit or annotated release tag and updates the saved pins.

Upgrade builds the application, stops the old service, runs migrations, and starts the replacement. It checks health, readiness, and the exact version. If migration fails, Ryker stays stopped; restore the pre-upgrade backup.

Bundled and remote workers keep their current versions. To upgrade the bundled worker to the co:op revision specified by your checkout, run:

scripts/compose.sh worker-upgrade

This prepares the new worker before replacement, preserves model sign-in, and waits for active commands. See the upgrade reference for remote installs and automatic upgrades.

Deploy a local commit

For development on the installation host, use:

scripts/deploy.sh

The script requires a clean checkout at main’s commit, unless you deliberately pass --allow-not-main. It builds from the committed tree, pauses Ryker, creates a pre-deploy backup, runs migrations, and replaces only the application container. PostgreSQL and the worker keep running.

It pins the new version only after health, readiness, and version checks pass. It then updates voice and search model services whose image or settings changed. A model failure is reported without taking down Ryker.

If the application fails verification, the script prints logs, stops the replacement, and leaves the old version pinned. Check whether migrations ran before restarting the old image. If they did, restore the pre-deploy backup first.

Choose retention periods

Under Settings › Data retention, the defaults are 30 days for prompts, replies, tool activity, finished work, request history, and the audit trail; conversation memory defaults to 90 days.

The audit trail must last at least as long as request history, which must last at least as long as finished work, which must cover its prompts and tool activity. Ryker enforces this order and asks before shortening a period.

Open follow-ups, blocked work, pending approvals, live schedules, unpublished changes, and active incident rooms retain the history they still need. Working copies have separate cleanup rules; saved knowledge follows the memory expiry rules.

Send a weekly report

Under Settings › Weekly report, choose a Slack channel Ryker has joined and a weekly send time. Preview this week’s report lets you read it first. Enabling the report schedules its next send; Send to the channel posts a labelled preview immediately.

The report covers opened and merged pull requests, drafts waiting for review, questions for people, stopped work, feedback, learning, and model cost. It is built from recorded work without a model call. Estimated and unmeasured costs are labelled.

Connect another event source

Under Integrations › Webhooks, create a source with an address, signing credential, destination conversation, and environment. The payload cannot change the destination or environment.

Sources accept authenticated JSON, Grafana alerts, or a custom mapping of dotted paths. Authentication uses a bearer token or an HMAC-SHA256 signature over a timestamp and request. Bodies are limited to 1 MiB. You can preview a payload without saving or sending it.

A 202 response means the batch is queued. An exact retry returns its original receipt; reusing an event ID with different content returns 409. Grafana batches of up to 500 alerts are accepted all together or rejected. See the webhook reference for headers and signing.

Check workers

The bundled co:op worker is configured during installation. It fetches permitted repositories and runs model sessions in its private Docker daemon. It connects outbound to Ryker using mutual TLS; application deployments leave it and its daemon running.

If work is waiting for a worker, check Settings › Advanced, then Work › Working copies for available space. See worker credentials and sandbox boundaries.

Verify release downloads

Install and upgrade from main. A tagged release, when available for the code you need, includes a Linux amd64 archive, checksums.txt, and checksums.txt.bundle. Read its release notes before choosing it.

Place all three files in one directory. Replace the placeholders below with the downloaded version and filenames. The commands require Cosign and the GitHub CLI:

scripts/check-release.sh DIRECTORY vX.Y.Z
gh attestation verify DIRECTORY/ryker_X.Y.Z_elixir_linux_amd64.tar.gz --repo AndrewDryga/ryker

The first command authenticates the checksum signature before checking the archive. The second verifies its build provenance. Publishing a release does not upgrade an installation. For repository checks, model evaluations, and live acceptance, see the testing reference.

Remove the data

stop and uninstall keep your data. To delete the Compose volumes and generated environment, run the explicit destruction command:

RYKER_DESTROY_CONFIRM=delete-ryker-data scripts/compose.sh destroy

Without a backup, the credentials and history cannot be recovered.