Guides

Add a sender (a machine, a project, a CI repo)

A sender is anything that posts items: an agent, an Orca automation, a VM's cron jobs, a CI workflow. Each one gets its own token so you can revoke it alone.

With an invite link (recommended) #

1. Make a link. In the Mac app: right-click the pill → Settings… → Connect a machine (or Connect a Machine… in the menu bar menu), keep A server or agent that sends alerts, set Uses to the number of machines, Create invite. On a server hub: needs-you-admin invite create my-server --role sender --uses 3 --ttl 72. You get:
   • a join URL, e.g. http://my-mac.example.ts.net:8765/join/nyi_...,
   • a one-liner: curl -fsSL <join_url>/install.sh | bash -s -- --yes --claude-hooks user --skill --alerts. The last three options set up Claude Code alerts; on a machine without Claude Code, drop them (Options),
   • an agent prompt: "Set up needs-you alerts on this machine: read <join_url> and follow it. If this machine runs Claude Code, use --claude-hooks user --skill --alerts. If it runs OpenAI Codex CLI, add --codex-hooks user; Gemini CLI, add --gemini-hooks user; opencode, add --opencode-plugin; GitHub Copilot CLI, add --copilot-hooks user; Kimi Code, add --kimi-hooks user; Grok Build, add --grok-hooks user; Cursor, add --cursor-hooks user; Cline, add --cline-hooks user; Aider, add --aider. Then run ~/.local/bin/needs-you doctor and, for each WARN or FAIL line, run the next step printed under it, or tell me if it needs me. If the installer says the link is unknown, expired or used up, ask me for a new one." (Codex)
2. Use it on the machine. Paste the prompt into the machine's agent (Claude Code, Orca), or run the one-liner yourself. The machine must reach the hub: on the Mac itself 127.0.0.1 always works (pass --hub http://127.0.0.1:8765 if the link's MagicDNS name doesn't resolve) and the installer puts it first; elsewhere it must be on the tailnet.
3. Check the card that the installer posts (setup:<host>:test, under Recent). On the machine, open a new terminal and run needs-you doctor: every line should be OK or INFO.

If the installer stops with can't reach the hub, nothing was installed and no use was spent: the machine can't reach the Mac (asleep, Tailscale off on one side, or macOS blocked python3). Tailscale → Check reachability has the checks.

The join URL is safe to open in a browser first: it's Markdown that explains what will happen. Opening it doesn't spend a use.

What the installer does #

Options #

Add them after --yes: curl -fsSL <join_url>/install.sh | bash -s -- --yes --skill --context personal.

Re-running with an already-configured machine updates the CLI and the schedule and keeps the token and every setting you don't pass again (the PATH line is added once). It doesn't spend a use, and it works until the link expires or is revoked, also after its last use is spent. A new machine (or --force) needs a use left; the installer stops with exit 1 before installing anything if there's none. Give provisioning scripts a link with a long enough expiry (up to 90 days).

Notes:

• An expired, revoked or unknown link fails with exit 1 and needs-you install: This invite link is unknown, expired or revoked. on stderr.
• After the link expires, remove things by hand (below).
• Update the CLI, hook, skill and Orca snippet later with needs-you update (or add --auto-update to the one-liner for a daily update). See Keeping up to date.

Manually (no invite link) #

Mint a token on a server hub (needs-you-admin token add <name> --role sender), then on the machine, from a checkout of this repo:

./scripts/setup-sender.sh

It installs the CLI, asks for the hub URLs and the token (hidden input), writes ~/.config/needs-you/env, checks health, schedules the 5-minute needs-you flush (crontab on Linux, a LaunchAgent on macOS, like the installer), puts ~/.local/bin on PATH in your shell profile, and offers a test item. Re-running it is safe. Unattended:

printf '%s' "$TOKEN" | ./scripts/setup-sender.sh --non-interactive \
  --url "http://hub-a.example.ts.net:8765,http://hub-b.example.ts.net:8765" \
  --token-stdin --install-cli --test

Without the CLI #

Anything that can make an HTTP request can post; see Agent guide → With curl. The trade-off: no outbox and no failover, so loop over NEEDS_YOU_URLS yourself (the GitHub Actions example does) or accept that an alert is lost while the hub is down.

To connect an agent or tool that has hooks, webhooks, plugins or a notification command, see Custom connector: the full item format, how to map its events to cards, and tested examples.

Picking keys and context #

• Key: <prefix>:<project-or-ticket>:<reason>, e.g. personal:my-server:backup-failed, work:ACME-456:feature-flag. Stable across runs, never a timestamp. The same key updates the item; resolve with the same key clears it.
• Context: work or personal; it decides when the item is prominent on the Mac. Set a machine default with --context.
• Kind: needs (you must act, raises the count), done (FYI, finished), info. done and info expire after 24 h.

Cron, systemd, CI #

For one command, wrap it in needs-you run:

needs-you run --key "personal:devbox:nightly-backup" --title "Nightly backup failed" -- ./backup.sh

It runs the command (no shell) and passes its output and exit code through. On failure it posts a needs card with the exit code and the last 5 lines of stderr (obvious tokens redacted; --no-output leaves them out). On success it resolves the key, and if the run took at least --done-after seconds (default 300) it posts a done FYI, so a long build you were waiting on says it finished. needs-you run --help lists the options; Agent guide has the rules.

Ready-made pieces are in integrations/ci: a wrapper that alerts on failure and resolves on success, an OnFailure= systemd template, and a GitHub Actions step that joins the tailnet.

Removing a sender #

1. Revoke its token. In the Mac app: right-click the pill → Settings… → Machines → Revoke next to the machine (open invite links are listed there too). Over HTTP with an owner token: DELETE /v1/tokens/<name> (API). On a server hub: needs-you-admin token revoke <name>. Or run the admin tool bundled in the app against its database (safe while the app runs):

   ADMIN=/Applications/NeedsYou.app/Contents/Resources/hub/needs_you_admin.py
   DB="$HOME/Library/Application Support/NeedsYou/hub.db"
   /usr/bin/python3 "$ADMIN" --db "$DB" token list
   /usr/bin/python3 "$ADMIN" --db "$DB" token revoke <name>      # e.g. orca-build-2

   invite list --all and invite revoke <name> work the same way for links.

2. Clean up the machine. Either run a live invite's installer with --uninstall, or by hand. First the Claude Code hooks, if they were installed (offline; user level, the current directory's project and every recorded project install):

   needs-you uninstall-hooks

   With a CLI older than uninstall-hooks: integrations/claude-code/install-hooks.sh --uninstall from a checkout, or fetch it from the hub:

   . ~/.config/needs-you/env; d=$(mktemp -d)
   curl -fsS "$NEEDS_YOU_URL/dl/install-hooks.sh" -o "$d/install-hooks.sh"
   bash "$d/install-hooks.sh" --uninstall; rm -rf "$d"

   Then the rest:

   crontab -l | grep -v needs-you-flush | crontab -                          # Linux
   launchctl bootout gui/$(id -u)/io.needs-you.flush; rm -f ~/Library/LaunchAgents/io.needs-you.flush.plist   # macOS
   rm -rf ~/.config/needs-you ~/.local/bin/needs-you ~/.local/state/needs-you ~/.claude/skills/needs-you

This page is docs/guides/add-a-sender.md in the repo. View or edit it on GitHub.