--- name: tmon-connect description: Connect the owner's existing local Hermes installation to the TMON pixel-companion frontend using the verified TMON setup helper, then give the owner a pairing code and fingerprint for manual approval. version: 1 instructions_path: /skill.md discovery_path: /.well-known/tmon.json origin_policy: same_https_origin_as_these_instructions --- # Connect the owner's Hermes to TMON Use this procedure when the owner asks to connect their Hermes to TMON. Respect the owner's existing instructions and your tool permissions. Do the local checks and setup you can perform; ask only for a concrete missing installation, credential, provider configuration, profile choice or machine access that prevents progress. TMON is a companion frontend for an existing Hermes. This procedure creates no VM and assumes no public source repository or published npm package. It requires filesystem and shell access on the Hermes machine. A chat-only agent without those tools must explain that specific limitation; it cannot claim to have completed local setup. The agent handles discovery, verified downloads, local checks, helper configuration and starting its own connector. The signed-in owner reviews the pairing code and fingerprint in TMON and chooses Approve connection. Never approve the pairing for the owner or treat a generated code as an approved or ready connection. ## 1. Fetch the authoritative release descriptor Derive INSTRUCTIONS_ORIGIN from the HTTPS /skill.md URL the owner asked you to read. Fetch /.well-known/tmon.json on that exact same origin, with verified HTTPS and redirects disabled. Do not default to a different hosted domain. Hosted example: instructions at https://themasterofnone.xyz/skill.md use https://themasterofnone.xyz/.well-known/tmon.json. A self-hosted copy must use its own instructions origin. Keep this public fetch free of cookies, local credentials and provider keys. Bound metadata reads to a sensible size (64 KiB is sufficient for descriptor/manifest). Reject redirects, failed TLS, non-200 results or invalid metadata. The expected descriptor fields are: - schemaVersion: 1 - product: TMON - appOrigin: exactly INSTRUCTIONS_ORIGIN - apiOrigin: the published HTTPS TMON backend origin - instructionsUrl: INSTRUCTIONS_ORIGIN plus /skill.md - setup: {runtime:"node",minimumNodeVersion:"22.16.0",entrypoint:"byo-setup.mjs"} - package: {version,manifestUrl,manifestSha256,files:[{name,url,sha256,bytes}]} Use the descriptor's actual immutable release URLs and hashes. Do not guess a release version, fabricate a GitHub repository, install a similarly named npm package or download a shell installer from another origin. ## 2. Verify all code before executing any of it Create a new directory owned by the current user with mode0700 for the selected immutable release. Preserve the module layout and exact basenames: byo-setup.mjs byo-connector.mjs byo-protocol.mjs Fetch package.manifestUrl as bounded raw bytes with redirects disabled. Before JSON parsing, compute SHA-256 over those exact bytes and require an exact match to package.manifestSha256, which must be 64 hexadecimal characters. Reject a missing or mismatched manifest hash. Only after that check may you parse JSON and validate schemaVersion,product,version and every file entry against the descriptor. The exact module list is those three files; reject missing, duplicate, extra or path-traversal names. The manifest and every module URL must be verified HTTPS on the exact appOrigin, without userinfo, query secrets or fragments. They must belong to the same immutable /agent/releases// directory. Follow no redirects even to another HTTPS location. Download all three exact entries into the private release directory. For each file, check actual byte count against bytes and compute SHA-256 over the downloaded bytes; it must equal the sha256 recorded in both descriptor and manifest. A SHA-256 is 64 hexadecimal characters. Do not execute a partially verified release. Stop with the concrete mismatch if any check fails. The descriptor/manifest delivered by TMON over HTTPS are the trust source; do not claim an additional independent signature exists. Do not use curl-pipe-shell, disable TLS verification or execute an unverified module to discover how to verify itself. ## 3. Inspect the helper and the owner's chosen local profile Verify that Node.js meets setup.minimumNodeVersion (currently22.16.0). Reuse a compatible existing runtime first. Hermes itself may be Python-only, so Node can genuinely be absent. When installing a supported official Node.js runtime is already within the owner's instructions and your permissions, you may prepare it in your own user directory using the official release and its integrity verification. Preserve global runtimes, shell startup configuration and other running jobs; no administrator access or curl-pipe-shell is needed. Use that runtime's explicit path for the helper. If you cannot install with your permissions, report missing Node.js as the concrete blocker. The current managed helper supports macOS/Linux; it rejects unsupported Windows execution before writes. From the fully verified release directory, inspect the source as appropriate and run: node byo-setup.mjs --help Identify the current task-bound Hermes profile/home the owner is asking you to connect. HERMES_HOME belongs to that running task; HERMES_PROFILE_NAME/HERMES_PROFILE may pin its launch. A sticky active_profile file is a CLI preference and must not silently switch this connection to another profile. Do not borrow a default, operator or other agent's private profile/session. Hermes has no standardized standalone API-key file. Its native key is API_SERVER_KEY in that exact bound home's .env, its own effective process environment, or api_server.key in that profile's config.yaml. Read/extract only that one selected local API key into a new owner-only mode0600 file when needed. Never source/echo/copy the whole .env, dump the environment, scan auth/provider stores or send the value to TMON. If the current profile is ambiguous or the key is actually missing, ask about that concrete blocker. Use the available filesystem/shell tools yourself to find non-secret installation metadata and existing protected paths. Do not make the owner manually locate paths or write JSON when you can determine them safely. If several profiles could be intended, ask the owner to choose; do not silently select an unrelated private profile. The Hermes API URL must use numeric HTTP loopback, normally http://127.0.0.1:8642. The helper also accepts exactly /p/ for an existing namespaced profile, for example http://127.0.0.1:8642/p/my-profile. Other paths, userinfo, query strings, fragments and traversal are rejected. Match the current task's profile and its own key. Never fall back from a namespaced URL to the unprefixed default profile, or create a new profile/port just to avoid discovery. Keep the Hermes API local. Do not expose it publicly, change shared firewall/SSH rules or create an inbound tunnel as a shortcut. Inspect the selected local Hermes without requesting an inference: node byo-setup.mjs inspect --hermes-url --key-file --json The helper's current --help is authoritative. inspect can use supported defaults when available. The local Hermes API credential is read from an owner-only mode0600 file. Supply the path, never the raw credential in argv, a URL, a browser field or a message. If the selected Hermes is not running, start that chosen profile with its documented local command when the owner's task and your permissions authorize it. Preserve other running agents and profiles. If Hermes is absent, its selected API credential is unavailable, the current provider is unconfigured, or this machine is inaccessible, report that exact blocker and the smallest action needed. ## 4. Let the helper prepare and start its own connector Keep three separate locations: verified modules (for example ~/.local/share/tmon/connector//), protected local inputs (for example ~/.config/tmon/hermes-api-key, file0600 in directory0700), and the helper-exclusive state directory (for example ~/.local/state/tmon-managed/, mode0700). The API-key file and any input models JSON must be outside the exclusive helper state directory. Never put a key in the downloaded artifact directory. Choose a dedicated state directory for this TMON connection. The helper owns its protected connector state and process. Do not reuse an unrelated connector state directory, overwrite an unrelated key file or manipulate another agent's files. Run the local fixture-tested setup helper from the fully verified release: node byo-setup.mjs setup --state-dir --hermes-url --key-file --origin --app-origin --name --json Optional: add --models-file only when the owner supplied an explicit local model allowlist. With no explicit models file, the helper uses the current configured model. Let it do that rather than asking the owner to invent a model catalog. Models JSON is an explicit local array of {id,label,provider,model,order,modelOptions?}. Use only actual configured provider/model IDs approved for the chosen profile. If more power levels are wanted, prepare the owner-approved allowlist locally; never advertise mini, DeepSeek, Astra or any other model merely because its name is known. The setup helper handles local checks/configuration and starts a detached task-owned connector. It can continue after the starting terminal closes, but this MVP does not install automatic startup and does not survive a machine reboot without being started again. The connector performs outbound polling to the descriptor's apiOrigin and uses the local Hermes API. The local Hermes API credential and locally configured provider keys remain local; only the protocol's limited metadata and chat/check work go to TMON. An optional owner-selected STRAY BYOK connection is different: its provider key is encrypted on the TMON API host and the connector receives a short-lived model-only capability. Do not configure that optional provider as part of automatic local setup. A health check or inventory result does not prove paid provider quota. Check the helper's JSON outcome. Do not invent success, silently fall back to another provider/model, or restart an unrelated Hermes profile. Do not print secrets or the full connector state. If the setup helper cannot perform an operation, report its actual bounded error instead of substituting a broad installer. ## 5. Give the owner the code and fingerprint; leave approval to them When setup reports a pairing code, show only the useful review details: - The exact short pairing code. - The connector name and fingerprint from the helper. - The plain approval location descriptor.appOrigin plus / (no code in the URL), and instructions to open Connections, enter the code, choose Review connection, compare the fingerprint, then choose Approve connection. Do not put the code, local API key, connector credential or bearer token into an approval URL. Do not use the owner's browser session to auto-approve. If the code expires, generate a fresh candidate using the helper's supported workflow and let the owner review it again. Keep the detached connector running while the owner approves. You may check your own setup with: node byo-setup.mjs status --state-dir --json Connected means approval was accepted. Ready requires a fresh successful local Hermes check. Report waiting, offline or unavailable honestly; never label it ready based only on a generated code or running process. For cleanup of this setup's connector only, use: node byo-setup.mjs stop --state-dir --json Do not stop Hermes or another agent's process. Disconnect in the signed-in TMON UI revokes the binding; it does not uninstall Hermes or delete local profile data. ## 6. Preserve the owner's control over tools and models Chat can use the tools configured in the chosen Hermes profile. This connector is not a sandbox. Recommend a dedicated profile and explain that fact before pairing; do not broaden tool access or copy private profiles automatically. TMON's power slider comes only from connector-advertised capabilities. A requested level is pending until the connector acknowledges the exact available model ID and reports ready. Single-model setups are valid. Never promise a higher tier, price, speed, quota or fallback that the local profile has not configured. Do not make paid test inferences merely to claim setup succeeded. The first owner-requested chat exercises the selected actual model and can reveal provider/quota errors. Preserve stable idempotency on uncertain outcomes; do not repeat potentially paid work with new keys to mask a timeout. ## Browser pairing protocol (for understanding, not automatic approval) All browser mutations require the signed-in owner's Google session and CSRF. The agent setup flow must not obtain or replay those browser credentials. - GET /api/byo/status: enabled,connected,online,ready,status,connector,models,selectedModelId,requestedModelId. - POST /api/byo/pair/preview {userCode}: pairingId,label,fingerprint,expiresAt,permissions,toolNotice. - Explicit owner approval: POST /api/byo/pair {userCode,pairingId}. - POST /api/byo/model {modelId}: requests one advertised available ID; acknowledgment is asynchronous. - POST /api/byo/disconnect {}: revokes that account's binding. Do not handcraft connector authentication, bind another account/session, bypass candidate expiry, or turn the public download/descriptor route into a private credential endpoint. ## Optional owner-selected STRAY BYOK The AI providers panel can connect an owner's OpenAI or Anthropic key to the TMON API. This is separate from local setup and requires that owner's explicit choice. The provider key remains encrypted on the API host; it is not copied into the connector or Hermes. A short-lived model-only capability is used for the selected STRAY route. If the owner explicitly requests that route, follow this installation's /connect.md optional provider section. Its configuration snippet command must name the exact approved API origin, existing helper journal, numeric-loopback profile base and protected Hermes key-file path. Never run --model-token as a diagnostic, print its access_token, auto-edit provider/default-model/tool settings or silently substitute the broker for a local level. Installing a snippet does not prove provider quota; real owner-requested chat is the inference step.