# Vando: setup steps for an AI agent

Last verified: 2026-10-15, against the `vando` command in the Vando code as it is today.

Output note: when you run `vando` (no terminal), problems start with `Error:` and warnings with `Warning:`; a person at a terminal sees ✗ and ⚠ instead.

You are helping a person connect Claude Code on their computer to the Vando app on their phone. After setup, risky commands wait for the person's OK on their phone, and you can ask them for a secret through their phone instead of reading it from a file or the chat. Tell them up front that the first time takes about 5 to 8 minutes, with the app already set up on their phone.

Human-readable version: https://getvando.com/docs/connect-claude-code

## Rules

- Never ask the person to paste a secret's value into the chat. When a command needs one, run it as `vando run --secret NAME -- <command>` (see "Secrets for a command" below): the person approves it on their phone and the value goes to that program only. Use the `get_secret` tool only when you must see a value yourself.
- Never run `vando connect` yourself. It asks the person to pick a set of words that only their phone shows; without a keyboard it stops with "there is no terminal to check the words at" and sends nothing. Ask the person to run it in their own terminal.
- Never pass `--unverified` to `vando connect`. It skips the check that nobody sits between the terminal and the phone.
- Don't suggest "don't ask again" for any vando command, and never for `vando run` (it would let any command wrapped as `vando run -- …` skip Claude Code's own check).
- Never pipe or pass a secret's value to `vando add`; it refuses, and asks the person in their own browser or terminal instead.
- Never open, print or edit `.env*` files. To move a project's `.env` files into Vando, run `vando init --dry-run` (names and guesses only) and show the person; the real `vando init` is theirs. Never run `vando clean` or `vando init --rewrite` (they move the person's files).

## What exists today (early access)

- There is no published npm package and no hosted MCP server yet. The `vando` command runs from the person's copy of the Vando code: `node <VANDO_CODE>/packages/mcp/bin/vando.mjs`. Its packages must be installed once (`pnpm i` in that folder). Node 22 or later.
- Coming soon, not working yet: a published `vando` package. When it exists, `vando` will be on the PATH and step 1 below finds it.
- Claude Code does not see the person's shell aliases, so use the full `node …` form unless `command -v vando` finds a real command.

## Steps

1. **Find the command.** If `command -v vando` prints a path, use `vando`. Otherwise use `node <VANDO_CODE>/packages/mcp/bin/vando.mjs`, where `<VANDO_CODE>` is the person's copy of the Vando code (ask if you don't know it). If it prints "vando couldn't start: its packages aren't installed", ask the person to run `pnpm i` in that folder.
2. **Ask it what's next.** Run `vando` on its own. It prints where this computer stands and one `Next:` command, and never asks the phone or the network. `vando --json` gives `{"state": …, "next": …}`.
   - `vando · not connected` (next: `vando connect <code>`): stop. Ask the person to open the Vando app, go to Connections → Connect an AI → Claude Code, copy the command it shows (`vando connect <8 characters>`, sometimes with `--api <address>`), and run it in their own terminal. They pick the set of words their phone shows and tap Connect on the phone. When they say it's done, run `vando` again.
   - Next `vando init`: the project has `.env` files. Run `vando init --dry-run` and show the person the names; the real `vando init` is theirs (see below).
   - Next `vando setup`: go to step 3.
   - Next `vando run …`: it is set up; carry on with the person's task.
3. **Set up this project.** In the project folder: `vando setup`. It shows what it writes, then writes it: the `AGENTS.md` note on how to ask for secrets (and `@AGENTS.md` in `CLAUDE.md`), Claude Code permission rules (`vando request`, `status` and `grants` without asking; `vando run`, `vando get` and `vando env` always ask) in `.claude/settings.json`, and the guard (risky commands wait for the phone). It ends with `Done. Ask Claude to run your command`. Show the person the output. Options: `vando guard --global` for every project; `sudo vando guard --managed` (the person runs it) for a guard you can't edit.
4. **Check it.** Run `vando doctor`. It checks Node, the connection, the keychain, Vando's server and the clock, the guard, the note and the rules, and prints the command that fixes anything wrong (exit 1 when something needs fixing). `vando doctor --json` gives the same as data. Tell the person anything it says to fix that you can't run yourself.
5. **Optional: the tools.** Only if you must read a secret's value yourself: `claude mcp add vando -- node <VANDO_CODE>/packages/mcp/bin/vando-mcp.mjs` (or `claude mcp add vando -- vando-mcp` if `command -v vando-mcp` finds it), then the person starts a new Claude Code session. `vando test` sends a harmless ask to the phone.

## Secrets for a command

- **Save one secret.** `vando add NAME` (for example `vando add STRIPE_KEY`). Without a terminal it opens a one-time page in the person's own browser; they paste the value there and it goes to their phone, locked so only the phone can open it. They tap Save on the phone. Never give it a value yourself.
- **Run with it.** `vando run --secret NAME -- <command>` (repeat `--secret` for more). The phone shows what is asked and for how long; once given, the value is in that program's environment only, and anything the program prints of it shows as `[vando:NAME]` in what you see (best effort: it hides accidents, not a transformed copy).
- **Exit 75** means it is waiting for the phone: say "Approve NAME on your phone, then I'll run it again", do other work, then run the same command again (it continues the same ask). After two waits, stop and tell the person to open Vando on their phone.
- **Exit 77** means the person said no, or the access ended: don't retry; ask the person.
- **Move a project's env files into Vando.** `vando init --dry-run` lists, per environment (`.env` → dev, `.env.staging` → staging, `.env.production` → prod), the folder it would fill (`Work/<project>/dev`) and each name with its guess (secret, setting, or "secret?"); never a value, and it needs no connection. The person runs `vando init` in their own terminal (it asks them to type yes); if you run it without a terminal, it opens a one-time page in their browser where they press Send, and it waits up to 45 seconds for the phone (exit 75: run it again later; it doesn't send twice). Their phone shows every folder and saves it with one tap; then `vando init` writes `.vando.toml` and `.env.example`. Their `.env` files are never changed unless they ask (`vando init --rewrite`, at their terminal).
- **A whole project.** If the project has a `.vando.toml` (names only: `project = "Work/acme"`, and under `[environments]` lines like `dev = [".env"]`), run `vando run -- <command>`: one approval on the phone for everything directly in the current environment's folder (`Work/acme/dev`); `vando run --env staging -- <command>` picks another. Without that file, `vando run --folder Work/acme/dev -- <command>` names a folder. Don't create or edit `.vando.toml` unless the person asks you to.
- **References.** A `.env` line like `KEY=vando://Work/acme/dev/KEY` is filled in by `vando run` when the program starts; leave such lines as they are. If the phone doesn't give it, the command doesn't start (it says which variable): ask the person.
- `vando request` (same selectors) asks early without waiting; `vando grants` lists what this computer can use now (`vando grants end --all` ends it); `vando env` lists the names a run would set, without values.
- Don't use `vando get` or `vando env --reveal`: they print values where you can read them, and they refuse without a terminal.

## The tools you get

- `get_secret(item_hint, purpose)`: asks the person for one secret by a hint ("stripe test key") and a reason. Blocks while they decide, up to about 45 seconds; then it answers `pending` with a `request_id`.
- `check_approval(id, wait_s?)`: checks an ask you were told to check later.
- `list_pending()`, `cancel_request(id)`, `whoami()`.

If a tool answers `not_connected`, the connect step hasn't been done, or the session started before it: connect, then start a new session.

## Honest limits (tell the person when it matters)

- **A secret returned by `get_secret` is in this conversation from then on.** `vando run` keeps it out of the chat: the value goes to one program, and its output is scrubbed for you (best effort).
- **Taking access back is not taking the secret back.** Disconnecting stops the next ask, not what you already have. If it matters, the person should change the secret where it came from.
- **Anything running as the person can read what they give a program**, and can read the agent's keys (in the macOS keychain, or a 0600 file under `~/.vando/keys` elsewhere) or remove an unmanaged guard. A program already running keeps a value until it exits.
- **The guard covers Claude Code only.**

## The block a person pastes

People start this by pasting the block below into Claude Code (it is on https://getvando.com/docs/connect-claude-code#paste-this). It is the same steps, shorter:

```
Set up Vando in this project with me, step by step. The full steps are at https://getvando.com/docs/for-agents.md
1. Find the vando command: if `command -v vando` finds it, use `vando`; otherwise use `node [PATH]/packages/mcp/bin/vando.mjs`, where [PATH] is my copy of the Vando code (ask me if you don't know it). Run `vando` on its own: it says what this computer needs next.
2. If it says "not connected", stop and ask me to run the connect command my phone shows (Connections, Connect an AI, Claude Code) in my own terminal. It asks me to compare words with my phone, so you can't run it for me. When I say it's done, run `vando` again.
3. If this project has .env files, run `vando init --dry-run` and show me the names (it never shows values). I'll run `vando init` myself.
4. Run `vando setup` and show me what it printed.
5. Run `vando doctor` and tell me anything it says to fix.
Never ask me to paste a secret into this chat, and never open my .env files. When a command needs a secret, run it as `vando run --secret NAME -- <command>` (or `vando run -- <command>` in a project after `vando init`), and I'll approve it on my phone. To save a new one, run `vando add NAME`: it opens a page in my browser.
```

## Undo

```
vando unguard
claude mcp remove vando
vando disconnect
```

`vando disconnect` refuses while the guard is on, so run `vando unguard` first.

## When it goes wrong

- Anything else: run `vando doctor`; it says what is wrong and the command that fixes it.
- `That isn't a connect code.` or `Vando doesn't know that code.`: the person gets a new code on their phone (codes work once, for 10 minutes).
- `Can't reach Vando at …`: check the `--api` address matches the phone's command; run again with `VANDO_DEBUG=1` in front.
- `Already connected as "Claude Code" to …`: it is connected; carry on from step 3.