Skip to content
Arugula

Troubleshooting

Start with arugula status, then find your symptom below. If you’re still stuck, ask on GitHub.

First: arugula status

Section titled “First: arugula status”

This one command answers most questions about the machine’s state.

Terminal window
arugula status

arugula status says how Arugula is doing on this machine: the daemon’s version, the service that runs it, its binary and log; whether and where it’s joined to Arugula control (connected, or dropped by control); each agent’s adapter; and whether Claude Code has Arugula’s MCP server. It exits 1 when the daemon doesn’t answer or control dropped the machine. The logs are listed in Service and logs.

Installing

Section titled “Installing”

These come up while installing or starting the daemon.

  • Windows SmartScreen stops the installer: choose More info, then Run anyway.
  • The daemon doesn’t start at boot on Linux: run loginctl enable-linger $USER.
  • A Mac reached only over ssh doesn’t start the daemon after a reboot until someone logs in to its desktop; arugulad install --system starts it at boot (Service and logs).
  • arugulad: command not found on a Mac with the desktop app: the app runs the daemon from inside itself; use its buttons, or the full path (The Mac app’s daemon).
  • The desktop app says the daemon is too old or too new: use the update it offers, or Update now on the machine’s page.

The page

Section titled “The page”

These come up in the browser, the desktop app or on your phone.

  • “Run arugula web” on http://127.0.0.1:7681: the browser hasn’t been signed in with the machine’s local token. arugula web opens the page signed in.
  • Over ssh, arugula web prints the link and the ssh -L command that forwards the port to the computer you’re at.
  • Chrome asks to reach your local network when a machine has a tailnet or LAN address. Allow it to connect directly; if you don’t, Arugula goes through Arugula control’s relay.
  • Notifications don’t arrive on a phone: the page has to come over HTTPS (through control or tailscale serve), and on an iPhone it has to be added to the Home Screen and opened from there (Phone).
  • tailscale serve fails: turn on MagicDNS and HTTPS certificates in the tailnet’s DNS settings; on Linux, run sudo tailscale set --operator=$USER first.
  • Panes didn’t come back as expected after a reboot: each pane does what its After a restart setting says; change it in the pane’s menu (Panes and sessions).
  • A teammate can’t type in your pane: on your own machine they need your permission to drive, for a set time; they ask with Ask the owner to let me drive it (Teams).

Arugula control

Section titled “Arugula control”

These come up when joining machines and devices.

  • “This machine is no longer in {account or team}” (a banner, Dropped by control in the host menu, arugula status exiting 1): control no longer knows this machine. It left, was removed from a device, or its account was deleted. Join again on the banner (or Daemon › Join again… in the desktop app) adds it again with a new code to approve.
  • An approval is refused: the page says which check failed and what to do. Closing it doesn’t turn the machine down.
  • A browser was removed: it says so when it opens control’s page, and offers to add itself again, approved by another device or a recovery code.
  • You can’t find Teams… or Add a phone or browser…: those are in the account menu of control’s page (or the signed-in desktop app), not on the machine’s own page.

Agents

Section titled “Agents”

These come up when starting or answering agents.

  • Start an agent… says the adapter isn’t installed: Install runs the install in a pane, or run arugula setup claude (or setup codex). The adapters need Node 20 or newer on your PATH.
  • An agent block can’t find node or your tools: blocks get your login shell’s environment, read once. After changing an rc file, run arugula shell-env --refresh (Environment variables).
  • A turn fails on logging in: the block says which Claude Code login it used (CLAUDE_CONFIG_DIR) and how to log in to it: run CLAUDE_CONFIG_DIR=… claude (or env -u CLAUDE_CONFIG_DIR claude for the default one), then /login.
  • Claude Code in a terminal doesn’t show as needing you: arugula describe %N --detection shows how its screen reads, rule by rule. Claude Code’s hooks make it certain: arugula setup claude, or just arugula hooks install (Agents).

Blocks

Section titled “Blocks”

These come up with browser and editor blocks.

  • “Dev servers in blocks are off here” or “VS Code in blocks is off here”: they need a listener of their own. arugulad install -- --block-listen 127.0.0.1:7701 turns them on for this computer; other devices need a domain too (Blocks).
  • A block on a port doesn’t load from your phone through control: blocks on ports aren’t relayed through Arugula control; your phone has to reach the listener over your tailnet.

The Linux desktop app asks you to sign in again

Section titled “The Linux desktop app asks you to sign in again”

The .deb and the AppImage share the app’s saved data, including your Arugula control sign-in. If you switch to a build with an older WebKitGTK (say, from the .deb on a newer system to the AppImage), that build gets a profile of its own, and you sign in to control again there.

Next steps

Section titled “Next steps”