Repository navigation
Open
Labels
enhancementNew feature or requestNew feature or requestquestionFurther information is requestedFurther information is requested
Description
Why
To see nodkey work today, a person needs a second Linux host that is always on, a Telegram bot, a Bitwarden account, and the steps of docs/setup.md sections 3 to 11. Many people stop before the first tap. They need a way to see the flow first, in a few minutes, with nothing to set up.
What
Decided by the owner (2026-10-29): a one-machine trial with fake secrets.
nodkey try, run as a normal user: no root, no systemd, no store account, no config file.- It makes a temporary directory (mode 0700) with a broker key, a client key, both configs and an audit log. It runs the real broker parts on
127.0.0.1with a random port: mutual TLS with pins, the approval core and the audit log. It skips only what needs systemd or root. - A test store with 3 fake secrets, such as
demo-token. Their values are random, made at start, and start withTRY-. - Approval in the terminal by default: the
nodkey tryterminal shows the message and asks Approve once, Approve N min, or Deny. - Telegram, guided (
--telegram, stage 2: a second pull request after the terminal trial works): the person makes a new bot in BotFather and pastes its token (hidden input, kept only in memory). nodkey prints the linkhttps://t.me/BOT?start=CODE. It takes the approver's user ID only from the/start CODEmessage, shows the name, and asks to confirm. Nocurl getUpdatesstep. feat: guided broker setup (nodkey setup broker) #98 step 5 can reuse this. - It prints commands for a second terminal, such as
nodkey try run --secret DEMO_TOKEN=demo-token -- sh -c 'echo "got ${#DEMO_TOKEN} characters"'.nodkey try runisnodkey runwith the trial's client config; it never reads~/.config/nodkey/client.toml. - Every message and every client line says TRY MODE.
- On Ctrl-C it stops, removes the directory, and says what a real setup adds: a separate broker host, a store, the rules (with links to docs/setup.md).
Security points.
- Approval in the terminal exists only in try mode.
nodkey brokermust have no way to turn it on: a terminal on the agent machine is a place where the agent can type. - The trial reads no config file and has only the test store. So it can never hand out a real secret.
- The bot token is typed on this machine, which may be an agent machine (docs/setup.md, "Where you do the setup"). So the guide says: use a new bot for the trial, never the broker's bot. With the broker's bot, both would poll, and the real broker stops with exit code 76 (T6). On a conflict from Telegram,
nodkey trystops and says this.
Must change: DESIGN.md sections 4 and 15 (the command); THREAT-MODEL.md (what try mode is, and why it cannot reach a real secret); README.md (a "Try it" part before the setup guide).
Open questions
- macOS: the broker parts may run without systemd, but
nodkey runis Linux only today (Clients for macOS and Windows #35). Proposed: Linux first. - One terminal:
nodkey trycould also send the demo request itself, after a key press. Is that clearer than two terminals? - SSH logins in the trial (a throwaway key and a local
sshd)? Proposed: later.
Done when
- As a new Linux user with no root and no config,
nodkey tryandnodkey try run ...work end to end with approval in the terminal: Approve once, Approve N min, Deny, and an expiry. - Stage 2:
--telegramworks with a new bot: a manual test, with the results in the docs. - Nothing is written outside the temporary directory, and the directory is removed on exit, also on SIGINT and SIGTERM. Tests.
- Tests show that try mode reads no config file and no real store, and that
nodkey brokerhas no terminal approval. - README.md and the sections above are updated. It gets the security review, as every change does.
Related: #98 (guided broker setup), #30 (pairing), #35 (macOS client), #124.
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or requestquestionFurther information is requestedFurther information is requested
Activity
feat: nodkey try with a terminal approver and a test store (#125)
test: nodkey try end to end: approve once, N min, deny, expiry, signa…
test: nodkey broker has no terminal approval; the trial has only its …
docs: nodkey try in DESIGN.md, THREAT-MODEL.md T38 and README.md "Try…
feat: nodkey try turns off core dumps, as nodkey broker does (#125)
fix: review findings for nodkey try (#125)
fix: lock the trial's lock file before it gets its name (#125)
fix: nodkey try tries an early answer again (#125)
fix: the early-answer tries of nodkey try stop when the broker stops (#…
feat: nodkey try, a trial on one machine (stage 1 of #125) (#143)
feat: telegram pairing from /start, a token in memory, and a message …
feat: nodkey try --telegram: a new bot, a /start link, approval on th…
test: nodkey try --telegram with the fake Telegram: approve, not conf…
docs: nodkey try --telegram in DESIGN.md, THREAT-MODEL.md T38, README…
docs: the results of check 16 go to #125
fix: review findings for nodkey try --telegram (#125)
groupsky commentedon Oct 31, 2026
Stage 1 (
nodkey try, approval in the terminal) is merged in #143.Stage 2 (
nodkey try --telegram) is ready in #144, with green CI. Its tests use a fake Telegram. The last box of "Done when" needs a manual test with a real new bot on your phone.@groupsky, could you run check 16 of
docs/manual-telegram-test.mdon the branchfeat/125-try-telegram? In short:nodkey try --telegram, paste the token (it should not show), open the link on the phone, tap Start, typeyes.nodkey try runcommand it prints: tap Approve once, then run it again and tap Deny.Please post the 4 rows of check 16 of the results table here (no token, no user ID, no bot name), then remove the label
question. A later session adds the results to the docs, merges #144 and closes this issue.chore: start nodkey try --telegram (#125)
feat: telegram pairing from /start, a token in memory, and a message …
feat: nodkey try --telegram: a new bot, a /start link, approval on th…
test: nodkey try --telegram with the fake Telegram: approve, not conf…
docs: nodkey try --telegram in DESIGN.md, THREAT-MODEL.md T38, README…
docs: the results of check 16 go to #125
fix: review findings for nodkey try --telegram (#125)
docs: the trial with Telegram is check 18 after the rebase (#125)
fix: review findings after the rebase of nodkey try --telegram (#125)
fix: the network hint only for a failed Bot API call in nodkey try --…
groupsky commentedon Nov 18, 2026
hq-jobs
nodkey-166-144-1118(runr-20261118-072516-15ff)Stage 2 (#144) is rebased onto main at 0b97ca2 (after #166), and CI is green.
nodkey try) is as on main.Options.Prefixhas a cap and every message keeps room for it; T38 says what a pasted broker token gives the agent. Details are in the PR description.docs/manual-telegram-test.md. It is the same test as the "check 16" of my comment of 2026-10-31.Ready for the manual check 18 with a new bot. Please post its 4 rows here (no token, no user ID, no bot name), then remove the label
question. #144 stays a draft until then.