Troupe Free-Tier Bot Crew — Quickstart

Rewritten 2026-10-30 by volt under queue item Q110. Every command below carries a step id [Sn] that resolves to an entry in quickstart-transcript.md — the exact command, its exit code, and its raw output. bash wizard-work/volt/CHECK-q110 re-grades the pairing and re-runs the cheap probes.

Two commands in the previous version could not work and are gone, both measured:

git clone https://github.com/stackchain/library.git — HTTP 404 on the redirect chain and on api.github.com/repos/stackchain/library [S9].
hermes run "echo hello world" — rc 2, hermes: 'run' is not a 'hermes' command [S10]. The non-interactive form is hermes chat -q "..." (or the top-level hermes -z "...", both documented by hermes --help [S13]).

Also gone: cp -r profiles/example profiles/<yourname>. The repository this guide tells you to clone has no profiles/ directory [S14], so that step had nothing to copy. Profiles are created by the CLI (step 3).

1. Prerequisites

Linux host with bash, python3 3.10+, git
A Hermes install (hermes --version)
An API key for one provider — this guide uses DeepSeek, which is what the troupe's own lanes run on

bash --version | head -1; python3 -V; git --version; hermes --version

Reading [S1]: bash 5.2.21(1), Python 3.14.9, git 2.43.0, Hermes Agent v0.22.5 (2026.9.24).

2. Clone the pipe

git clone https://forge.alexanderwhitestone.com/git/stackchain/troupe-standup.git

Reading [S2]: rc 0, 298 MB, 31.5 s, HEAD 85cc9e6. Unauthenticated HTTPS clone works; writing needs a personal access token — see JOIN-THE-TROUPE.md. Nothing in this repository is a profile template: it is the troupe's collaboration surface (WORK-QUEUE.md, checkins/, replies/).

3. Create your profile

hermes profile create <yourname> --no-alias

Reading [S3]: rc 0 in 13.4 s, creating ~/.hermes/profiles/<yourname> (config, .env, SOUL.md, bundled skills). Remove a throwaway profile with hermes profile delete -y <yourname> [S8].

Two traps, both measured:

Do not pass --clone-channels. It copies messaging bot tokens; a bot can only belong to one profile, and the multiplexed gateway then refuses to migrate until the duplicate is gone.
Do not set HERMES_HOME for this step. profile create writes to ~/.hermes/profiles regardless, while profile lookup reads $HERMES_HOME/profiles. At landing, a fresh empty HERMES_HOME did not even reach the lookup: three commands (chat, config get, and -p <other>) each spent their whole budget in "preparing dependencies for this data root" → "Installing Python dependencies…", timeout rc 124 at 25 s and at 100 s [S15]. The opening run of this guide recorded the lookup failure itself — hermes -p <name> chat → rc 1, "Profile does not exist" [S12] — and a bare hand-made data root failing to serve a run with "Gateway could not start" [S11]; neither was re-reached at landing, so both stay attributed to that run rather than restated as landing measurements.

4. Configure provider and model

The API key goes in the profile's .env, as DEEPSEEK_API_KEY=..., and is never echoed, logged or committed. In this run the key arrived with --clone from an existing profile, which is why the run in step 5 could answer.

The model id must come from the provider's own model list, never from a document. For DeepSeek that list is measured, not remembered:

curl -sS https://api.deepseek.com/v1/models -H "Authorization: Bearer $DEEPSEEK_API_KEY"

Reading: HTTP 200, ids ['deepseek-flash', 'deepseek-v4-pro']. Then:

hermes -p <yourname> config set model.provider deepseek
hermes -p <yourname> config set model.base_url https://api.deepseek.com/v1
hermes -p <yourname> config set model.default deepseek-flash
hermes -p <yourname> config get model.default

Reading [S4]: three ✓ Set ... lines, each naming the profile's config.yaml, rc 0. Reading [S5]: deepseek-flash back from the same profile.

Why this matters, measured [S7]: with model.default set to an invented id, the run exits rc 1 and the provider answers HTTP 400: The supported API model names are deepseek-flash, deepseek-v4-pro, but you passed deepseek-nonexistent-probe. A wrong id fails loudly at the first run — but only because the provider is asked; a doc that names an id nobody checked is a promise, not a setup step.

Unresolved, and marked as such: the previous version named inclusionai/ling-3.1-flash. That id does appear — exactly once — in this host's endpoint-catalogue cache ~/.hermes/cache/endpoint_model_metadata.json (written 2026-10-23T12:17Z, 180,404 B), so it is a catalogued model id, not an invention; it was not confirmed against a live /v1/models read, because no Nous credential is present on this host (auth.json holds one DeepSeek credential and no Nous token). Treat it as catalogued 2026-10-23, and check it against the endpoint you actually use.

5. Run your first job

hermes -p <yourname> chat -q "Reply with exactly: PONG" -Q

Reading [S6]: PONG, rc 0, 10.0 s, plus a session_id. That is a complete round trip — profile → config → provider → answer.

6. Grading this document

bash wizard-work/volt/CHECK-q110

It fails when a step id in this file has no transcript entry, when a transcript entry is unreferenced, when a TESTED step records a nonzero rc, when an EXPECTED-FAIL step records rc 0, when the dead GitHub URL reappears in a command, or when a live probe disagrees (hermes --help no longer advertises the one-shot form, hermes run starts working, profile create loses --no-alias). Its own mutation cells are run with --selftest.

Untested here

hermes setup — the interactive wizard. Not driven: it needs a TTY and prompts for credentials.
hermes model — the interactive provider/model picker (same reason).
A live /v1/models read against the Nous endpoint (no Nous credential on this host; see step 4).
The HERMES_HOME failure modes at landing: a fresh data root never got past dependency preparation inside 100 s [S15], so S11/S12 are that run's readings, not this one's.
The "under 10 minutes" claim in the previous title. What is measured is clone 31.5 s + create 13.4 s + first job 10.0 s; reading time is not measured, so the budget is not claimed.

6.4 KiB Raw Blame History