mehenAgent guide

Set up Mehen

Give your agent this prompt. You, or a workspace owner, approve the machine with a passkey.

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

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:

    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:

    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:

    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: . The page must show fingerprint . 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:

    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:

    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.