# Set up Mehen

Human prompt: Set me up with Mehen by following https://mehen.dev/setup.md

Mehen lets agents use credentials without seeing their values. A workspace owner approves new machines; a human approves sensitive requests with a passkey on the vault page.
Never ask for or accept a secret, never open an approval link yourself, and use `--json` for every Mehen command. Unless your harness already sets `MEHEN_SESSION`, prefix each setup command with `MEHEN_SESSION=setup-agent` (or another short label for this conversation); an export may not survive between harness calls.

The human needs an invite to a Mehen workspace first. Ask a workspace owner or administrator for an invite, accept it and register a passkey on the vault page. If there is no invite yet, stop here. Do not ask for their password, passkey or credentials.

1. **Install on macOS or Linux (WSL counts as Linux).** Run:

   ```sh
   curl -fsSL https://mehen.dev/install | sh
   ```

   Success ends with `mehen-install: {"version":"...","path":".../mehen"}`. If `mehen` is not on PATH, apply the exact PATH line printed by the installer in this shell, or use the absolute path in that JSON. On native Windows or an unsupported architecture, stop and explain that macOS, Linux or WSL on arm64 or x64 is required. A checksum failure is a refusal: do not bypass it. Report it and retry only after the release or download is fixed.

2. **Register the machine's agents and skill.** Run:

   ```sh
   MEHEN_SESSION=setup-agent mehen setup --json
   ```

   Success has `agents`, each with `mcp`, `skill`, `files` and `restart`, and `next` equal to `mehen enrol --json` (or `mehen status --json` if already enrolled). `added`, `updated` and `unchanged` are success. Report `skipped` entries: a foreign or symlinked skill is left alone, and a malformed config is never overwritten. Do not use `--force` without the human's agreement. If no agent was detected, repeat with `--agent <name>` from `mehen setup --help` for the agent in use. Setup edits user settings only, not the project. An agent whose Mehen entry the human added by hand (for example with `claude mcp add`) comes back `skipped` as "not written by setup": that entry is fine to leave as it is.

   This release has no workspace choice: do not pass or invent a `--workspace` flag.

3. **Request enrolment, without opening its link.** Run:

   ```sh
   MEHEN_SESSION=setup-agent mehen enrol --json > "$HOME/.mehen-enrol.json" 2>&1 &
   ```

   This command streams a `status: "pending"` object containing `enrolment`, `fingerprint`, `ask` and `expiresAt`, then waits. Run it in the background with its output captured (your harness's background option or the command above), then read the first `pending` line from that output. Interrupting it is safe and keeps the key; `mehen wait <id>` resumes. Follow the `enrolment` id, not the PID. If setup already returned `next: "mehen status --json"`, or enrol returns `error: "already_enrolled"`, continue to step 5.

   A workspace owner approves new machines. If the human is not an owner, they send the link and the full check to an owner, who opens it and compares the check.

   Relay `ask.title` and `ask.what`, `ask.url` as `Open:`, the full `ask.check.label` and `ask.check.value`, and `ask.expiresAt`. For example: "Approve this machine. Open: <exact ask.url>. The page must show fingerprint <full ask.check.value>. If it differs, do not approve. Valid until <ask.expiresAt> (15 minutes). I will wait." Never shorten the check, hide the URL, describe the request as safe or drive the page yourself. If your harness draws vault cards from Mehen output, do not also send the link. Follow https://mehen.dev/skill.md for the complete ask rules.

4. **Wait in short calls.** If enrolment is no longer running, use the exact `enrolment` id from step 3:

   ```sh
   MEHEN_SESSION=setup-agent mehen wait <id> --timeout 30 --json
   ```

   Success has `kind: "enrol"` and `status: "active"` (or `status: "active"` directly from the original enrol command), with `tenant` and `device`; this completes enrolment. A `timeout` or `device_pending` means the human has not finished: keep the ask visible and repeat a short wait. Do not start another enrolment just because the human needs time. Links expire after 15 minutes. If expired, run `MEHEN_SESSION=setup-agent mehen enrol --json` again to get a fresh link for the same key and relay the new ask, including its full check. A refusal or identity mismatch is a stop, not a reason to bypass the check. A `forbidden` refusal on the page means the human is not an owner: ask an owner to approve.

5. **Reload the agent, then confirm.** Tell the human to follow each agent's `restart` instruction from setup so the new MCP tools load. Run:

   ```sh
   MEHEN_SESSION=setup-agent mehen status --json
   ```

   Success exits 0 with `vault`, `tenant`, `device`, `name` and `scope`: the vault accepts this machine. If the `vault_*` tools are missing after the reload, run `MEHEN_SESSION=setup-agent mehen setup --json` again; it should report `added` for that agent, then reload again. After reload call `vault_status` too; it must show `enrolled: true`. If the CLI returns `error: "unauthenticated"` (exit 6), return to step 3. For other failures run `MEHEN_SESSION=setup-agent mehen doctor --json`, relay its `next` instruction and stop on a refusal. Never try another identity, host or credential to evade one.

## What you can do now

Label these commands as the skill says: keep a `MEHEN_SESSION` your harness sets, or prefix your own short label for this conversation.

- Run a project's command using the environment in `mehen.toml`: `mehen run --env dev -- npm test`. This runs a process rather than returning JSON; never print its environment.
- Call an API without reading its key: `mehen fetch github GET https://api.github.com/user --json` (replace `github` with an item the human has granted).
- Request a credential: `mehen request api-key --name openai-dev --provider openai --reason "Use the development API" --json`. Relay the ask to the human; they enter the credential only on the vault page.