All pages
  1. Getting started
  2. Connect machines
  3. Folders: what the building sees
  4. Views
  5. Chatting with sessions
  6. Approvals and notifications
  7. Everyday tools
  8. Agent teams
  9. Code and Git
  10. Preview on your phone
  11. On your phone
  12. Plan usage
  13. Codex
  14. Antigravity
  15. GitHub Copilot
  16. Buildings, people and roles
  17. Command
  18. Enterprise: policy, SSO and reports
  19. Your account
  20. Subscription
  21. Keyboard shortcuts
  22. Troubleshooting
Docs

Troubleshooting

Start with the collector log: almost every problem shows up there with a clear message. The collector’s messages are in Portuguese; the main ones are below.

The machine doesn’t show up

What to checkHow
Log on Mactail -f ~/Library/Logs/fleetly-coletor.log
Log on Linuxjournalctl -u fleetly-coletor -f
Log on WindowsGet-Content $env:USERPROFILE\.fleetly\collector\coletor.log -Wait
Is Claude Code signed in?claude should open with your account
The collector’s Node~/.fleetly/node/bin/node -v (only exists if the machine had no Node 20)
  • "Não consegui abrir …/login" (couldn’t open the hub): the machine can’t reach the hub. Check outbound internet access and the network proxy.
  • "Rode com o seu usuário, não como root": install as the user signed in to Claude Code.
  • Mac, sessions in Documents or Desktop don’t show up: give Full Disk Access to the collector’s Node (see Connect machines).
  • Mac, an agent opened by Fleetly can’t read OneDrive, iCloud or Dropbox ("Operation not permitted"): everything the Fleetly app opens inherits its privacy permissions, even if VS Code has its own. The chat explains why. At the Mac, in System Settings → Privacy & Security → Files and Folders (or Full Disk Access), allow Fleetly. Away from the Mac, a session open in VS Code can do the same. To know before you leave the Mac: in Settings → Chat, Mac permissions shows the folders Fleetly can’t read, with Open Mac Settings; and the collector app checks on its own: the first time, the Pastas protegidas do Mac step (“Protected Mac folders”) in the setup window lists each folder, opens Settings at Full Disk Access, shows ✓ once you turn Fleetly on and has Já liguei: reiniciar o Fleetly (“Done: restart Fleetly”) (macOS only applies it after a restart); and every time the app opens, if any is missing, it notifies you and adds Liberar pastas do Mac (“Allow Mac folders”) to the menu bar menu. A folder you don’t use drops out with Não uso essa pasta (“I don’t use this folder”). It can’t be allowed from afar: macOS only lets someone at the Mac do it.

"A central recusou o token" (the hub rejected the token)

The token was revoked, or the machine was removed from the building. Create a new command in Settings → Buildings → Machines → Add machine → With a command and run it on the machine: it replaces the token and restarts the service.

Approvals don’t reach the dashboard

  • Check that the hooks are written: run node ~/.fleetly/collector/fleetly-collector.mjs hooks.
  • For Codex, approve the Fleetly hooks: in VS Code, Review hooks → Allow all; in the terminal, /hooks.
  • In Settings → Notifications and approvals, in Automatic mode, a request only comes to the dashboard after the idle time at the computer. To test, use Always here.
  • If the log says port 4747 is in use, reinstall with --hook-port and another free port.
  • The session must be inside the machine’s folders.

A session doesn’t show up

  • It is outside the folders the machine shows (see Settings → Buildings → Machines).
  • A filter is hiding it: check the active filters in the corner of the stage, or the number on the Filters button.
  • Codex session: Codex must be signed in for the same user that runs the collector.

The session open in VS Code didn’t do what I asked

For a session open in VS Code or the terminal, the dashboard’s message arrives as a note, and the agent decides what to do with it. For the request to count as yours, use Take over in Fleetly or Continue in the Claude app (see Chatting with sessions).

That delivery uses Claude Code’s inbox, a format Anthropic doesn’t document and that may change in an update. If sending fails, the chat shows the error.

The preview won’t open

  • "Nada respondendo em 127.0.0.1:<port>" (nothing answering): the dev server isn’t running, or is on another port. Start the app (for example npm run dev) and try again.
  • "Não respondeu como um site" (didn’t answer like a website): the port belongs to another kind of service, such as a database.
  • "A porta é do próprio Fleetly": the collector’s own ports never become a preview.
  • "Esta prévia foi fechada" (this preview was closed): it timed out. Open it again from the dashboard.

I can’t reply or send work

The trial ended or the subscription is more than 3 days overdue, and the account is on Free: you see the agents and approve requests on one machine, but replying and sending work are part of Personal. Subscribing in Settings → Subscription unlocks it immediately. Nothing is deleted.

Didn’t find what you were looking for? Write to admin@fleetly.tools.