# Connect this agent to Manyfold This guide is for the AI agent reading it. The Manyfold deployment below generated it: follow it to install the `mf` CLI, sign the user in, and connect this agent to their Manyfold account. ## This deployment - API: `https://api.manyfold.ai/api` - Web app: `https://manyfold.ai` - CLI channel: `stable` - CLI profile: chosen in step 2, written `` below. - `mf` command: chosen in step 1. Every `mf` in this guide means that command. ## Rules 1. Do the steps in order. Setup is complete only when step 3 passes. 2. Wait for each command to finish, and never run two logins at once. 3. Never ask the user for a token or an API key. The only thing they may send you is the one-time `mf_auth_` code from step 2. 4. Run `mf setup` or `mf daemon` commands only if the user asks: they register this computer as a Manyfold host. 5. Do not replace, update or delete an `mf` that is already installed, and do not edit shell startup files. 6. Run the `mf` commands exactly as written below. The ones that talk to the API carry `--profile --api-url 'https://api.manyfold.ai/api'`; keep it on any other `mf` command you run for this deployment, and never point another profile at this API: `mf` sends a profile's saved token to whatever `--api-url` it is given. 7. If your commands run in a sandbox that blocks network access or writes outside the workspace (Codex does by default), ask for approval to run the install, sign-in and plugin commands outside it before you run them: a sign-in the user approved is lost if it cannot be saved. 8. Talk to the user in their language. ## Step 1: Look around If you cannot run shell commands, stop and report B. Otherwise run this as one command. It only reads: it changes nothing and sends nothing anywhere. ```sh echo "MF_API_TOKEN=${MF_API_TOKEN:+set} MF_AGENT_ID=${MF_AGENT_ID:+set} MF_TOKEN=${MF_TOKEN:+set}" echo "SSH=${SSH_CONNECTION:+yes}${SSH_TTY:+yes} DISPLAY=${DISPLAY:-}${WAYLAND_DISPLAY:-} OS=$(uname -s)" for bin in "$(command -v mf)" "$HOME/.local/bin/mf"; do case "$bin" in /*) ;; *) continue ;; esac case "$("$bin" --version 2>/dev/null)" in [0-9]*) ;; *) continue ;; esac echo "mf=$bin" "$bin" --version "$bin" profile list --json "$bin" login --help | grep -e --print-auth-url || echo "no --print-auth-url" break done ``` - `MF_API_TOKEN=set` or `MF_AGENT_ID=set`: you are inside Manyfold (a managed agent or a Manyfold terminal) and already connected. Confirm with `mf whoami --json`, skip the other steps, and use `mf help --agent` as your guide. - `MF_TOKEN=set`: that variable overrides any sign-in and would send its token to this deployment. Stop and report B, asking the user to unset `MF_TOKEN` first. - A line `mf=`: that is the `mf` command, and every `mf` in this guide means that path. The lines after it are its version, its profiles, and whether it has `--print-auth-url`. - No `mf=` line: the Manyfold CLI is not installed, though another program called `mf` may be (METAFONT, for example). Install it. The installer takes the build for this computer from the stable channel, checks its SHA-256 against the release manifest, and writes only `~/.local/bin/mf`; it does not edit shell startup files. Then check it the same way: ```sh curl -fsSL https://manyfold.ai/cli/install.sh | sh bin="$HOME/.local/bin/mf" "$bin" --version "$bin" profile list --json "$bin" login --help | grep -e --print-auth-url || echo "no --print-auth-url" ``` From here on, `mf` means `"$HOME/.local/bin/mf"`. ## Step 2: Sign in ### Choose the profile Use the profiles step 1 listed. `` in the commands below means the one you choose here: 1. A listed profile has `"apiUrl": "https://api.manyfold.ai/api"` and `"loggedIn": true`: it is already signed in to this deployment. Use it and go to step 3. A trailing `/` makes no difference. 2. Otherwise, if `default` has no `apiUrl` or has this one, use `default`. 3. Otherwise use `manyfold`, unless the list shows `manyfold` with another `apiUrl`; then stop and report B. ### Where the user's browser is - `SSH=yes`, or `OS=Linux` with nothing after `DISPLAY=`: the browser is on another computer. Use 2b. - Otherwise it is on this computer. Use 2a. ### 2a. The user's browser is on this computer ```sh mkdir -p "$HOME/.cache/manyfold" nohup mf --profile --api-url 'https://api.manyfold.ai/api' login --json > "$HOME/.cache/manyfold/agent-login.log" 2>&1 < /dev/null & echo "$!" > "$HOME/.cache/manyfold/agent-login.pid" sleep 3 cat "$HOME/.cache/manyfold/agent-login.log" ``` Codex stops background processes as soon as a command returns, so this block does not work there. In Codex, run `mf --profile --api-url 'https://api.manyfold.ai/api' login --json` in the foreground instead: it prints the same lines at once and keeps running until the user approves, while you keep reading its output. Any agent: if the log stays empty, or the process is gone before the log shows a result, do the same. The log shows `Open:` with a sign-in link and `Code:` with a short code, and the link opens in the user's browser. Tell the user to approve Manyfold there, and give them both: the page shows the same code, so they can check the request is theirs. If they are not at this computer (they may be steering you from a phone), they can open the link on the device they have: the page then shows a code that starts with `mf_auth_` for them to send you. Waiting for that approval is part of this step, not the end of your turn. Do not ask the user to tell you when they are done. Run this, and run it again for as long as it prints `waiting`; one run takes at most 100 seconds: ```sh i=0; while [ "$i" -lt 50 ] && kill -0 "$(cat "$HOME/.cache/manyfold/agent-login.pid")" 2>/dev/null; do i=$((i + 1)); sleep 2; done kill -0 "$(cat "$HOME/.cache/manyfold/agent-login.pid")" 2>/dev/null && echo waiting || cat "$HOME/.cache/manyfold/agent-login.log" ``` Once the login has finished, the log ends with a JSON object. `"ok": true` means you are signed in: go to step 3. Anything else, for example `login timed out` after 15 minutes: use 2b. If the user sends you a code that starts with `mf_auth_` instead, they approved on another device, and this login will not finish on its own. Stop it (`kill "$(cat "$HOME/.cache/manyfold/agent-login.pid")"`, or end the foreground command in Codex), check that the code is `mf_auth_` followed only by letters, digits, `_` or `-`, and finish with it inside the single quotes. It is already approved, so do not start another sign-in: ```sh mf --profile --api-url 'https://api.manyfold.ai/api' login --auth-code '' --json ``` Success prints `"ok": true`: go to step 3. ### 2b. The browser is on another computer, or 2a failed If you started a 2a login, stop it first: `kill "$(cat "$HOME/.cache/manyfold/agent-login.pid")"`. This needs `--print-auth-url`, and step 1 showed whether this `mf` has it. If it printed `no --print-auth-url`, look for a newer release: ```sh mf update --check ``` If that offers a newer version, ask the user whether you may update `mf`; if they agree, run `mf update --yes` and check `mf login --help` again. If there is no newer version, or the user says no, stop and report B: this `mf` release cannot sign in from another computer yet, so the user should paste the prompt into an agent on the computer where their browser is. ```sh mf --profile --api-url 'https://api.manyfold.ai/api' login --print-auth-url --json ``` It prints a JSON object and exits. Give the user its `authUrl` and its `userCode` (the page shows the same code), and ask them to approve and then send you the code the page shows: it starts with `mf_auth_` and expires 15 minutes after the command ran. Ending your turn to wait for that code is expected here, and it is not the final report: do not write A or B yet. When the code arrives, check that it is `mf_auth_` followed only by letters, digits, `_` or `-`, then finish with it inside the single quotes: ```sh mf --profile --api-url 'https://api.manyfold.ai/api' login --auth-code '' --json ``` Success prints `"ok": true`. ## Step 3: Verify ```sh mf --profile --api-url 'https://api.manyfold.ai/api' whoami --json mf profile show --json ``` Setup is complete when `whoami` shows `"kind": "human-session"` or `"kind": "human-api-token"` with the user's email, and `profile show` has `"apiUrl": "https://api.manyfold.ai/api"` and `"loggedIn": true`. Otherwise go back to step 2, once. If `` is a profile you reused there (choice 1), sign in with this guide's own profile instead (choice 2 or 3): never sign in over a profile you reused. If it fails again, report B. ## Step 4: Add the Manyfold plugin The plugin gives new sessions a skill for working with Manyfold. It loads only in a new session, so do not try to use it in this one. Use the section for the agent you are: Claude Code and Codex both install it. ### If you are Claude Code ```sh claude plugin marketplace add manyfold-open/manyfold; claude plugin install manyfold@manyfold; claude plugin list ``` Both are safe to repeat. The first fails harmlessly when a marketplace named `manyfold` already comes from somewhere else, such as a local checkout; the install uses that one. The plugin is in place when the list shows `manyfold@manyfold` enabled. If `claude` is not on PATH, use `"$HOME/.local/bin/claude"`; if that is missing too, ask the user to run `/plugin marketplace add manyfold-open/manyfold` and then `/plugin install manyfold@manyfold` in Claude Code. ### If you are Codex (the desktop app or its CLI) ```sh codex_bin=/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex [ -x "$codex_bin" ] || codex_bin=$(command -v codex) "$codex_bin" plugin marketplace add manyfold-open/manyfold; "$codex_bin" plugin add manyfold@manyfold; "$codex_bin" plugin list ``` The desktop app's own CLI comes first; a `codex` on PATH works too when it has `codex plugin`. The plugin is in place when the list shows `manyfold@manyfold` as `installed, enabled`. ### Any other agent There is nothing to install. Read the always-current guide instead: ```sh mf help --agent ``` ## Step 5: Hand off Tell the user, in their language, that this agent is connected: their account email, this deployment, and whether the plugin was installed. Then give them this first message for a new session: > Use my Manyfold account through `mf --profile --api-url 'https://api.manyfold.ai/api'` (web app: https://manyfold.ai). List my agents and tell me what you can do for me. Write the command the way you ran it: the full `mf` path from step 1 (for example `"$HOME/.local/bin/mf"`) in place of `mf`, and the profile from step 2 in place of ``. Keep the rest of the message as written, quoted so the user can paste it: a new session has no memory of this one. ## If something fails | Symptom | Cause | What to do | | --- | --- | --- | | `command not found` for `mf` or `claude` | The install directory is not on PATH | Call it by its full path (step 1, or `"$HOME/.local/bin/claude"`); do not edit shell files | | `Browser login endpoint is not available` | The API is older than this CLI, or the API URL is wrong | Compare the URL with this guide; report B with the output | | Connection refused, or the host does not resolve | The deployment is unreachable: a local dev stack is stopped, or its tunnel expired | Report B; the user has to bring it back | | The 2a log stays empty, or its process is gone before a result | The agent host stopped the background process (Codex does) | Run the login in the foreground (2a) | | `login timed out`, or the login ends with an error | The browser step did not finish within 15 minutes | Use 2b | | `401` from `whoami` | Not signed in, or the saved token expired | Go back to step 2 as step 3 says | | `whoami` shows an account the user did not approve | `MF_TOKEN` overrides the sign-in | Report B; ask the user to unset `MF_TOKEN` | | `Operation not permitted`, or network access denied | A sandbox blocks the command | Ask for approval to run it outside the sandbox, then retry | | No `sh` (Windows without WSL) | The installer needs a POSIX shell | Download the Windows zip from https://github.com/manyfold-open/manyfold/releases, put `mf.exe` on PATH, then continue | | The plugin install fails | Network or git problem | Retry once; if it still fails, finish without it and say so in the report | ## Report Finish with exactly one of these: - **A — Connected.** The account email, the API, the profile, the `mf` command, whether the plugin was installed, and the first message for a new session from step 5, filled in. - **B — Not connected.** The step that failed and the exact error output.