jev-setup v0.1.0B

Immutable. This exact content is served forever at /api/v1/blob/3b66fb9f12c57d12.

---
name: jev-setup
description: Use when Jev is not working yet, a Jev tool reports no_key or auth_failed, or the person asks to connect, install or fix Jev. Gets the TypeSafe API key from the person into the secret store without the agent ever seeing it.
version: 0.1.0
license: MIT
metadata:
  hermes:
    tags: [jev, typesafe, setup, credentials]
---

# Connect Jev (the key never passes through you)

Jev is TypeSafe's decision model. It needs one API key. **You must never see, ask for, or handle that key.**

## Rules

- Never ask the person to paste the key into the chat. If they paste one anyway, do not store it, do not repeat it, tell them that key should be replaced, and start the flow below.
- Never read the secret store, `.env` files or `~/.config/jev/credentials` to "check" the key. Use `jev doctor`, which reports only presence and length.
- Never put the key in a command line, a URL, a config file you write, or a log.

## Flow

1. Check the state: `jev doctor`. If `key.present` is true and `jev.reachable` is true, you are done.
2. Start the private key page:

   ```bash
   jev setup-key
   ```

   It opens a page in the browser on the computer you are running on and prints one JSON line on stderr with a `url`. The URL holds no secret.
3. Tell the person, in one sentence, to paste their TypeSafe key into the page that just opened. If `browser_opened` is false, or they are talking to you from another device (Telegram, phone), send them the `url` and tell them it only opens **on the computer the agent runs on**. If they have no key yet, they create one at https://console.typesafe.ai/settings/keys.
4. Wait for the command to finish. It prints `{"status": "stored", "verified": true, ...}` when the key was saved and TypeSafe accepted it. `rejected` means the key was wrong: run it again. `timed_out` means nobody used the page within ten minutes.
5. Run `jev doctor` once more and report the result in a sentence.

## When there is no browser

Headless server over SSH: the person runs `jev setup-key --tty` **themselves** in their own terminal. It is a hidden prompt. Do not run it for them through a tool that captures the terminal.

Remote machine on a private network (Tailscale, VPN): `jev setup-key --host <private-ip> --no-open` and send them the link. That traffic is plain HTTP, so use it only on a network you trust end to end. Never bind a public address.

## Where the key goes

The OS secret store (macOS Keychain service `Hermes TypeSafe API`, or `secret-tool` on Linux), falling back to `~/.config/jev/credentials` (mode 0600). On a Hermes machine it is also written as `TYPESAFE_API_KEY` into `~/.hermes/.env` and every `profiles/*/.env`, because each Hermes lane reads its own file. Running gateways pick it up on their next restart; do not restart one without being asked.