Troubleshooting & FAQ

Fixes for the most common issues — agent offline, queued messages, Slack not responding, and CLI sign-in problems.

Most problems come down to one of a few things: the runner isn't connected, the agent hasn't been set up, Slack isn't connected, or your CLI session has expired. This page walks through each, with the practical fix.

My agent shows as offline / "runner not connected"

Your agent is only reachable while its runner is running on your machine. If the agent shows as offline:

  • Make sure evident run --agent <your-agent-id> is running in a terminal, and keep that terminal open. (To keep it alive after closing the terminal, run it under a process manager — see Local runner.)
  • Check the terminal's status line. It shows the tunnel state (connecting / reconnecting / connected) and the OpenCode state (opencode: :4096, or (down) if OpenCode isn't up).
  • If the tunnel keeps reconnecting, check your internet connection. The runner reconnects automatically; messages sent meanwhile are queued, not lost.
  • Run with -v / --verbose to see detailed request/response information when diagnosing a connection problem.

My message was queued and hasn't been answered

Evident never rejects a message for being offline — it holds it until your agent is available.

  • From the web: you'll see a status indicator showing the agent is offline. The message isn't lost; it's processed when the runner reconnects.
  • From Slack: the bot still reacts to acknowledge your message. When the runner connects and processes it, the reply is posted back to the thread and the acknowledgement reaction is removed.
  • The fix is the same: start (or restart) the runner. On connect it automatically drains any queued messages.

Note: message queuing is a Pro feature.

"You haven't set up an agent" / no agent configured

  • In the app: create an agent first (it runs in local mode), then connect a runner to it — see the Quickstart.
  • In Slack: if someone messages the bot before a default agent is set, the bot tells them an agent needs to be set up first. Set a default agent in your Slack settings (see Slack integration).

Slack isn't responding

  • Is the workspace connected? Open your Slack settings — it should show Connected. Each team has its own connection; a newly created team starts with none. If you message the bot from a workspace that isn't connected, it privately tells you so rather than answering.
  • Is the integration enabled? When the integration is turned off, the bot goes quiet for the whole team. Turn it back on in Slack settings.
  • Did you @mention the bot? In channels, the bot only acts on messages that explicitly mention it. Plain channel chatter is ignored.
  • Is a default agent set, and its runner connected? See the two sections above.
  • Waiting on a question or permission? If the agent paused to ask something, it won't reply until you answer in the agent's chat — use the "Open" / "View in Evident" link in the thread. Decisions are made in the agent's chat, not via Slack buttons. (See Slack integration.)

OpenCode won't start

  • Make sure OpenCode is installed and on your PATH: opencode --version.
  • Run evident run from your project directory.
  • If the default port is in use, point the runner at a different one with -p / --port (the default is 4096).

CLI sign-in issues

"Authentication required" or "authentication expired"

  • Run evident login to sign in (or sign in again — sessions can expire). You'll get a link and a short code to confirm in your browser.
  • If the sign-in code expires before you confirm it, just start again with evident login.
  • Check who you're signed in as with evident whoami.
  • For headless / automated setups, set EVIDENT_AGENT_KEY instead of an interactive login — then evident run doesn't need --agent. (See Agent keys.)

"--agent is required"

When you're not using an agent key, evident run needs to know which agent to connect to. Pass --agent <id> (copy the ID from the agent's settings in the app), or set EVIDENT_AGENT_KEY so the agent is resolved from the key.

Wrong settings URL

Slack settings live at https://app.evident.run/settings/slack. If you land on a "not found" page, double-check you're using that URL.

FAQ

Does my code leave my machine?

No. Your agent runs where your code, secrets, and tools already live. Only the messages you send travel through Evident — your code stays on your machine. (See Local runner.)

Why isn't my Slack reply streaming word-by-word?

By design. Slack replies are posted on completion, with a "View in Evident" link to read the full answer in the rich chat — so the thread stays tidy. (See Slack integration.)

How many agents can I run?

Free includes 1 agent; Pro includes up to 5. See pricing for details.

Can my whole team use the same agent?

Yes. Agents and the Slack connection are shared across your team. Everyone sees the same agents; only admins and owners can delete agents or disconnect Slack.

Still stuck?