Skip to content

feat: token broker mode for agents in the nono sandbox - #15

Merged
JWhitleyWork merged 1 commit into
mainfrom
feat/nono-token-broker
Nov 10, 2026
Merged

JWhitleyWork merged 1 commit into
mainfrom
feat/nono-token-broker

Conversation

@JWhitleyWork

Copy link
Copy Markdown
Member

Why

Hermes agents can now run in a sandbox (PickNikRoboticsInfra/hermes-home-config#30). There, the agent never holds real credentials:

  • a separate nono proxy container keeps the GitHub App private key;
  • it mints installation tokens per owner, and an app JWT for GET /app only;
  • it injects them into requests to api.github.com, uploads.github.com and git smart-HTTP on github.com.

Today the plugin requires the private key and mints tokens itself, so its github_app_* tools and the gh-app/git-app wrappers fail in the sandbox.

What

Token broker mode, enabled by GITHUB_APP_TOKEN_BROKER=nono or github_app.token_broker: nono:

  • No private key is read or required. client_id and the installation IDs are still read; they are non-secret and used for owner selection and metadata.
  • get_installation_token returns the placeholder nono-phantom-github-app without any network call. It uses the per-owner installation ID and a 1-hour expiry, and create_jwt returns the same placeholder. Requests send the placeholder, and the proxy replaces it.
  • auth_metadata reports token_broker.
  • CLI:
    • token prints the placeholder, with a note on stderr.
    • doctor replaces the key checks with a broker check and an HTTPS_PROXY check.
    • setup --token-broker nono writes the setting without private_key_path.
  • Any other broker value is a ConfigurationError.
  • Docs: a README and skill section on running inside nono. Version bumped to 0.3.0.

Also isolates tests from a developer's real ~/.hermes/config.yaml, through an autouse fixture for HERMES_HOME/GITHUB_APP_*. test_load_config_from_environment was reading it on main.

Testing

  • ruff, mypy and pytest (36 tests on Python 3.10 and 3.12) pass.
  • Broker mode is covered via env and config, with no key file. Tests confirm no HTTP call is made when getting a token, check the placeholder Authorization header on requests, the invalid-value error, the doctor branch, and setup --token-broker.
  • The CLI was exercised by hand without a key.
  • End to end in the sandbox: plain gh/git through the proxy authenticate as the app in two orgs. This branch is what makes the plugin's own tools work there too. hermes-home-config bumps HERMES_GITHUB_APP_PLUGIN_REF to it once this merges.

Agents running inside the nono sandbox must not hold the GitHub App private
key. With GITHUB_APP_TOKEN_BROKER=nono or github_app.token_broker: nono, the
plugin skips key loading and sends the placeholder token
"nono-phantom-github-app"; nono's supervisor and proxy inject the real
credentials outside the sandbox.

- config: add token_broker to GitHubAppConfig, validate the value (only
  "nono" is supported), and ignore private key settings in broker mode
- auth: return brokered installation tokens without network calls, return
  the placeholder for app JWTs, and report token_broker in auth metadata
- cli: `token` prints the placeholder with a stderr note; `doctor` shows a
  token broker check and an HTTPS_PROXY check; `setup --token-broker nono`
  writes the broker and drops private_key_path
- docs: add a nono token broker section to README and the workflow skill
- bump version to 0.3.0
- tests: isolate HERMES_HOME and GITHUB_APP_* per test (a developer's real
  ~/.hermes/config.yaml was leaking into test_load_config_from_environment)
@JWhitleyWork JWhitleyWork self-assigned this Nov 10, 2026
@JWhitleyWork
JWhitleyWork merged commit 300084e into main Nov 10, 2026
2 checks passed
@JWhitleyWork
JWhitleyWork deleted the feat/nono-token-broker branch November 10, 2026 19:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant