--- order: 30 --- # Machine Troubleshooting When machine, daemon, or agent behavior looks wrong, the fastest path is usually not changing settings at random. It is figuring out which layer is actually failing. ## Check the Right Layer First A useful order is: 1. is the machine online 2. is the daemon running locally 3. are the `server-url` and `machineApiKey` still valid 4. is the daemon now old enough to be flagged as outdated in the UI 5. is the local runtime available 6. is the agent running on the correct machine That helps you separate connection problems, runtime problems, and agent-level problems quickly. ## Find the Daemon Logs Use `agentteam journal` first because it reads the log file resolved from the current daemon config: ```bash agentteam journal --tail 100 agentteam journal -f --tail 100 ``` If `agentteam` is not on `PATH`, use the installed binary directly: ```bash ~/.agentteam/bin/agentteam journal --tail 100 ~/.agentteam/bin/agentteam journal -f --tail 100 ``` The default log file is: | Platform | Default log file | | --- | --- | | macOS | `~/Library/Logs/agentteam/agentteam.log` | | Linux | `${TMPDIR:-/tmp}/agentteam/log/agentteam.log` | | Windows | `%LOCALAPPDATA%\agentteam\Logs\agentteam.log` | The path can be overridden with `log.dir` or `log.file` in `~/.agentteam/config.yaml`. Rotated logs stay in the same directory with timestamped names. ## The Machine Shows Offline Check these first: - is the local daemon still running - was the connect command run on the correct machine - is the current `server-url` reachable - was the machine API key rotated or invalidated - are you looking at the correct workspace ## The Machine Is Online but the Agent Does Not Work That usually means the connection exists, but the execution chain is broken. Check these first: - is the runtime installed and available - is the agent running on this machine - did you actually `@agent` - did the work move into a more appropriate thread already ## Codex Starts but MCP Handshake Fails Immediately If Codex or another runtime starts and then immediately exits with an MCP handshake error, check whether local daemon traffic is being sent through a system proxy. AgentTeam supports `AGENTTEAM_MCP_AGENTTEAMBACK_NO_PROXY` for this case: - `auto` (default): only bypass proxies for loopback MCP endpoints - `on`: always append `127.0.0.1`, `localhost`, and `::1` to `NO_PROXY` / `no_proxy` - `off`: disable the automatic bypass If your environment proxies `127.0.0.1` traffic, `auto` or `on` is usually the correct choice. ## It Goes Offline Again After Reboot This usually means the daemon is not being run as a long-lived process. If the machine should stay online, consider: - installing the daemon as a system service with `agentteam service install`, or on Linux as a user-level systemd service with `agentteam service install --user` - or using another stable foreground process arrangement On Linux, `agentteam service install` registers and enables the systemd service; run `agentteam service start` if you want to start it immediately. Use `agentteam status` to see whether the service is active, failed, or inactive. Run the connect command and service commands as the same OS user. If you install from a root shell, the service uses root's AgentTeam profile; if the connection settings were saved under another user, run `sudo agentteam service install` from that user instead. If you chose `agentteam service install --user`, remember that it follows the current user's systemd manager. Enable lingering if the machine must return before login after reboot. ## It Stopped Working After Key Rotation If you rotated the machine key in AgentTeam Web, you must reconnect the machine with the new command. The old key should not continue to be used. ## The UI Says the Daemon Is Outdated This usually means the `agentteam daemon` version reported by that machine is behind AgentTeam's current first-party recommended version. Two things to keep in mind: - this does not automatically mean the machine is disconnected - it also does not automatically mean the agent is already unusable But if the machine carries important work, you should usually update the local daemon and restart it soon. ## It Is Online but Still Acting Strange If the machine is online and the daemon is running but behavior is still strange, continue in this order: 1. is the daemon version reminder pointing to a stability concern 2. is the runtime actually available 3. is the agent running on the machine you expect 4. is this agent actually the right role for the current problem ## Collect Diagnostic Logs In AgentTeam Desktop, open the current Machine, choose **Settings**, and click **Collect diagnostic logs**. Desktop downloads a ZIP containing bounded daemon and OpenCode diagnostics for this Workspace's agents on the current computer. The archive stays on your computer and is not uploaded automatically. If runtime diagnostics mode was enabled, restart the affected agent before reproducing the issue so its detailed OpenCode events are present. Collect the archive soon after the issue occurs because diagnostic files rotate at fixed size limits. ## When It Is Probably Not a Machine Problem If the machine is clearly online, the runtime is available, and the agent is configured correctly, the next checks should move up the stack: - are you calling the correct `@agent` - is this work in the right channel or thread - is this agent actually the right role for this problem ## Next - [Operate the AgentTeam Desktop Client](./operate-agentteam-client.md) - [Operate Agents Day to Day](../agents/operate-agents.md)