Local Runner

Run your OpenCode agent on your own machine and connect it to Evident.

The Local runner connects your machine to Evident via a secure tunnel, making your locally-running OpenCode agent accessible from the web UI and Slack.

How it works

When you run evident run, the CLI:

  1. Starts OpenCode as a managed subprocess
  2. Opens an encrypted WebSocket tunnel to Evident's Cloudflare relay
  3. Forwards messages from the web UI (and Slack, if connected) to your local OpenCode
  4. Streams responses back in real time

Your code and secrets never leave your machine — only the conversation messages travel through the tunnel.

Installation

Install the Evident CLI globally with npm:

npm install -g @evident-ai/cli

Verify the installation:

evident --version

Login

Authenticate with your Evident account:

evident login

This opens a browser window to complete the OAuth flow. Your credentials are stored in your system keychain.

Running the agent

Find your agent ID in the Evident dashboard (Settings → Agent Details), then start the runner:

evident run --agent <your-agent-id>

The CLI will:

  • Start OpenCode in the current directory (or the directory where you run the command)
  • Connect to Evident's relay
  • Show a confirmation when the tunnel is live

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

Message queuing when offline

When the tunnel is not running, Evident queues incoming messages. When you start the runner again, it automatically pulls and processes any queued messages.

Senders see a status indicator in the web UI showing the agent is offline. Their message is not lost.

Running as a background process

To keep the runner alive after closing your terminal, use a process manager:

pm2 (recommended)

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

tmux

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

Troubleshooting

Tunnel not connecting

  • Check your internet connection
  • Run evident login again — your session may have expired
  • Verify the agent ID is correct (copy it from the dashboard)
  • Check the Evident status page if issues persist

OpenCode not starting

  • Make sure OpenCode is installed: opencode --version
  • Run evident run from your project directory
  • Check that Node.js 18+ is installed: node --version

Agent shows as offline in the web UI

  • The tunnel may have dropped. Restart the CLI.
  • Check the terminal output for error messages

Next steps