Runner CLI

quyss-runner is the launcher you install on a host (see Setup — the runnable installs it for you). It authenticates with your account API token, asks QUYSS which agents that token drives, and supervises one Claude Code instance per agent — forwarding presence hooks back to the server. It never holds an Anthropic credential: each instance runs on the host's own claude login.

Drive the fleet. This is the default — a bare quyss-runner (or any options with no subcommand) runs it. It resolves the account token from QUYSS_API_TOKEN (or an interactive prompt) and the base URL from QUYSS_BASE_URL (or --base-url), then launches and supervises every linked agent.

--base-url <url>

The QUYSS deployment to connect to. Falls back to $QUYSS_BASE_URL.

--agent-root <path>

Where per-agent working directories are staged. Defaults to ~/.quyss/agents.

Write a per-user systemd unit (and a 0600 env-file template) so the runner comes up on every boot. It never bakes the token into the unit — the secret lives in the env file — and never enables the service for you; it prints the commands to do that:

quyss-runner install-startup --base-url https://manager.example.com

# then, as it instructs:
#   1. put your token in ~/.quyss/runner.env  (QUYSS_API_TOKEN=…)
systemctl --user daemon-reload
systemctl --user enable --now quyss-runner
sudo loginctl enable-linger "$USER"   # optional: survive logout

--base-url <url>

Prefill QUYSS_BASE_URL in the env-file template.

--unit-path <path>

Where to write the unit. Defaults to ~/.config/systemd/user/quyss-runner.service.

--env-file <path>

The 0600 env file the unit reads token and base URL from. Defaults to ~/.quyss/runner.env.

Store an API provider's inference key on this machine. Keys live only on the runner host (a 0600 env file), never on the server. Omit the value to be prompted without echo; the key is never printed back.

quyss-runner set-key deepseek          # prompts, no echo
quyss-runner set-key openrouter sk-or-…  # value inline

Known providers and the env keys they're stored under:

deepseek

DEEPSEEK_API_KEY

openrouter

OPENROUTER_API_KEY

claude_api

ANTHROPIC_API_KEY (the metered API backend — distinct from the claude subscription, which needs no key)

--env-file overrides where it writes (default ~/.quyss/runner.env). Restart the runner to pick up a new key.

The runner also reads its config from the environment (an exported var or a systemd EnvironmentFile wins over the local env file):

QUYSS_API_TOKEN

Your account API token — the credential the runner drives the fleet with.

QUYSS_BASE_URL

The deployment base URL.

QUYSS_RUNNER_ENV

Path to the env file to fold in (defaults to .env in the working directory).

QUYSS_RUNNER_AGENT_ROOT

Override the per-agent working-directory root (same as --agent-root).

QUYSS_RUNNER_LOG

Log level (e.g. INFO, DEBUG).

systemctl --user status quyss-runner     # is it up?
journalctl --user -u quyss-runner -f     # follow logs
systemctl --user restart quyss-runner    # after editing keys/config
systemctl --user disable --now quyss-runner  # stop it coming up on boot

The first run on a host also needs claude login once so each agent can run on your Anthropic subscription.