Local runner

Run your OpenCode agent on your own machine with the Evident CLI and reach it from the web and Slack.

Your agent runs on your machine — where your code, secrets, and tools already live. The Evident CLI starts (or attaches to) opencode serve locally and connects it to Evident over a secure tunnel, so you can reach the same agent from the web and from Slack. Your code never leaves your environment; only the messages you send travel through Evident.

How it works

When you run evident run, the CLI authenticates, works out which agent to run, and then:

  1. Ensures opencode serve is running on your machine, on loopback (127.0.0.1) — starting it for you if it isn't already running.
  2. Opens an outbound, encrypted tunnel from your machine to Evident.
  3. Lets Evident reach your agent through that tunnel: web traffic (the chat UI) is proxied transparently, and channel messages (such as Slack) are delivered to your local OpenCode. Replies flow back the same way.

Because the agent runs locally, it has access to your repositories, environment, and tooling without any of that being uploaded to Evident.

Prerequisites

  • An Evident account and a team (a team is created for you automatically on first use).
  • A local agent, created in the Evident web app.
  • OpenCode available on your machine — the CLI starts opencode serve for you.
  • Node.js to install and run the CLI.

Install the CLI

Install the Evident CLI globally with npm:

npm install -g @evident-ai/cli

Or run it directly with npx without installing:

npx @evident-ai/cli@latest <command>

The installed binary is named evident.

Sign in

Authenticate with your Evident account:

evident login

This uses a browser-based device flow: the CLI shows a one-time code and opens your browser to confirm it. Pass --no-browser to open the URL yourself.

Run your agent

Copy your agent ID from the Evident web app, then start the runner from your project directory: 

evident run --agent <agent-id>

The CLI validates the agent, ensures OpenCode is running on port 4096 (the default), and connects the tunnel. Once it's connected, the web shows the agent as online and you can open its chat.

Keep this terminal open while you want your agent to be reachable.

Connect with only an agent key

An agent key is a credential scoped to a single agent. With one set, the runner connects as that agent without a personal sign-in — and without you having to say which agent it is. This is ideal for unattended or CI-style setups.

Set the EVIDENT_AGENT_KEY environment variable and omit --agent; the CLI resolves the agent automatically from the key: 

EVIDENT_AGENT_KEY=<agent-key> evident run

You can generate an agent key from the agent's settings in the Evident web app. See the CLI reference for the full list of flags and environment variables.

Opening the chat

While your agent is online, open its chat from the web. Messages you send stream back in real time as the agent replies. If the agent needs you to answer a question or approve an action, you do it right there in the chat — you're never sent to a separate screen for it.

Reconnection and a single active copy

  • Automatic reconnection. If your machine briefly loses its connection, the agent reconnects on its own, and any conversation you had is still there for you to continue.
  • One active copy at a time. If you start a second copy of the same agent, the second copy becomes the active one and the first stops serving it.

When the agent is offline

What happens to messages while your runner isn't connected depends on whether message queuing is enabled for the agent (queuing is a Pro feature).

  • From the web, with queuing on: you're shown how to start the agent on your machine and can write a message to be sent once it comes online. Your message is held until the agent connects, then delivered in a new conversation you can see in the chat. You can review and delete a queued message while it's still pending.
  • From the web, with queuing off: you're shown how to start the agent on your machine, and you aren't offered the chat until the agent is running.
  • From a channel (e.g. Slack), with queuing on: the message is held and delivered when the agent comes online, and the reply is sent back to the channel it came from.
  • From a channel, with queuing off: the sender is told the agent is offline.

Keeping the runner alive in the background

The runner stays connected only while evident run is running. To keep it alive after closing your terminal, run it under a process manager.

tmux

tmux new-session -d -s evident 'evident run --agent <agent-id>'

pm2

pm2 start "evident run --agent <agent-id>" --name evident
pm2 save

Troubleshooting

Agent shows as offline in the web app

  • The tunnel may have dropped. The CLI reconnects on its own; if it doesn't, restart evident run.
  • Check the CLI's terminal output for the connection status and any errors. Use -v / --verbose for more detail.

Not signed in / authentication failed

evident logout
evident login

In unattended setups, make sure EVIDENT_AGENT_KEY (or EVIDENT_TOKEN) is set.

OpenCode isn't reachable

  • evident run starts opencode serve on the port from --port (default 4096) if it isn't already running.
  • If you start OpenCode yourself, bind it to 127.0.0.1 (loopback IPv4) on that port.

Next steps