Skip to main content
This is tested only to work on Linux.

Step 1: Set Up Keyhouse

  1. Create your organization’s Keyhouse repository:
Create your organization’s Keyhouse repository

Step 2: Set Up Watchdog for Access Syncing and Logging

Watchdog talks to Keyhouse directly (via the watchdog_utils_II crate) to keep your server’s users and groups in sync. There’s no separate webhook server to run.
  1. Create a Slack app (api.slack.com/quickstart)
Give the following scopes: Slack app OAuth scopes Now, add the Slack app to your notification channel, say #watchdog.
  1. Clone Watchdog and build:
Whether you need the --features auto-update flag here depends on which sync method you pick below. See Keeping Watchdog in Sync with Keyhouse.
  1. Update the config.toml according to the provided sample.config.toml.
The fields to pay attention to:
  • hostname: this server’s name as it appears in Keyhouse access lines. A member with ratchet|study in their hosts file gets access to the server whose hostname is ratchet.
  • [keyhouse]: the API URL of your Keyhouse repository and a GitHub token that can read it.
  • [notifiers]: the Slack bot token and the ID of the channel to post to.
  • create_user_dir: when true, Watchdog also creates a home directory for each user under /opt/watchdog/users/<user>, and archives it when the user is removed. Linux accounts are created and deleted either way. Defaults to false.
  1. Run the install script:
The install script sets PasswordAuthentication no and makes sshd authenticate keys through Watchdog. Keep a root session open while you install, and make sure your own key is in Keyhouse with access to this server, or you can lock yourself out.
This will:
  • Copy the binary to /opt/watchdog/bin/watchdog and your config to /opt/watchdog/config.toml
  • Point sshd’s AuthorizedKeysCommand at Watchdog, so SSH keys are checked against Keyhouse
  • Add PAM hooks for ssh, sudo, and su, which report activity to Slack
install.sh (without manual-) only does the sshd and PAM steps. It’s meant for the .deb package, which puts the binary and sample config in place itself.
Then put watchdog on your PATH:
  1. Run an initial full sync, so the server has users and groups provisioned before you pick an ongoing sync method:
Watchdog adds users to groups but doesn’t create the groups themselves. Create a group on the server for every project that appears in Keyhouse (see the Server Admin Guide). The one exception is sudo, which maps to the server’s sudo or wheel group.

Keeping Watchdog in Sync with Keyhouse

Once Keyhouse has your initial access rules, something needs to keep telling Watchdog when those rules change. There are three ways to do that. Pick one (or combine them: for example, CI for near-instant sync plus a daily cron watchdog update --all as a safety net). This is the closest thing to instant sync: a GitHub Actions workflow, running on a self-hosted runner on the server itself, executes sudo watchdog update the moment your Keyhouse repository finishes building. No polling delay, no login required to trigger it.
You do not need the auto-update build feature for this option. Build Watchdog normally (cargo build --release).
  1. Register this server as a self-hosted runner for your Keyhouse repository:
    • In your Keyhouse repo on GitHub, go to Settings → Actions → Runners → New self-hosted runner.
    • Pick Linux, and copy the download and config commands GitHub shows you. They look like this (use the exact ones GitHub gives you, since the version and token are unique to your repo):
    • Install and start it as a service, so it survives reboots and keeps listening for jobs:
  2. Add a workflow to your Keyhouse repository that runs on this runner whenever a build completes. Create .github/workflows/scout.yml in your Keyhouse repo:
    "Build and Deploy" here must match the name of the workflow in your Keyhouse repo that builds and pushes to the build branch (Keyhouse’s own template ships one by this name; check your repo’s .github/workflows/main.yaml if you’ve renamed it). The runner’s user must be able to run this command with sudo without a password. For example, if the runner runs as runner, add this with sudo visudo -f /etc/sudoers.d/watchdog-runner:
  3. Commit and push this workflow file to your Keyhouse repo’s default branch. From now on, every successful Keyhouse build will trigger watchdog update on this server automatically.
A self-hosted runner executes whatever a workflow in that repository tells it to, with the permissions of the user it runs as (here, enough to run sudo watchdog update). Only register runners against repositories you trust and control access to. This is safe for a private, admin-gated Keyhouse repo, but is not something you’d want on a repo that accepts contributions from untrusted forks.

Option B: auto-update build feature

Build Watchdog with the feature flag:
With this build, every time sshd needs to check an SSH key during a login attempt, Watchdog runs a full Keyhouse sync first, then validates the key. There’s no separate service or schedule to configure, but note that the sync only happens when triggered by an SSH login attempt, so a Keyhouse change won’t take effect on this server until the next time someone tries to connect. If your servers see infrequent SSH traffic, this could mean a stale access list for a while.

Option C: Manual / cron watchdog update

Run this whenever you want to pull the latest Keyhouse state:
Or force a full resync instead of an incremental diff:
To automate it, add a cron entry, for example to sync every 5 minutes, by creating /etc/cron.d/watchdog with:
This is the simplest option to reason about, but access changes won’t apply until the next scheduled run, so your sync lag is exactly however often you’ve scheduled it.