AgentVera Runner setup guide

What Runner does

Use Runner when you want agents to run on a powerful, always-on server instead of your laptop. Runner keeps the agents’ terminal sessions on that server; close the lid, lose your connection or connect from another computer and the session carries on.

• Code and conversations stay on your server.
• The connection is relayed through the AgentVera server over encrypted TLS; relayed terminal traffic is not interpreted, logged or stored there.
• You see the server’s CPU, memory and disk use, open sessions and the files in the folders you allow.
• For tasks that come from webhooks or “Send to agent” on the web, the end of the agent’s output (up to 6,000 characters) is reported to the server as the task summary when its turn ends.

Requirements

• A server or computer running Linux or macOS.
• Node.js 20 or later, and npm.
• curl or wget.
• For agent sessions, a CLI installed and signed in on that server: Claude Code, Codex, Gemini CLI or opencode. Terminal sessions always work.
• An AgentVera organization on the Pro or Team plan.

If Node.js is missing, install it from nodejs.org or with fnm:

curl -fsSL https://fnm.vercel.app/install | bash && fnm install 22

To install Claude Code and sign in once:

npm install -g @anthropic-ai/claude-code
claude login

Installation

1. Open app.agentvera.dev/runners in your browser and click “Yeni runner ekle” (add a runner). An 8-character pairing code appears; it’s valid for 10 minutes.
2. Run the command below on your server, replacing KOD with your pairing code.
3. Within seconds the runner shows as online on /runners. Open it to see CPU, memory and disk use and start a Claude, Codex or terminal session with “Yeni ajan” (new agent).

curl -fsSL https://app.agentvera.dev/runner/install.sh | sh -s -- --pair KOD

If the pairing code has expired, just create a new one on /runners.

Installer options

Add these options to the install command:

• --name NAME: the runner’s name. Defaults to the machine’s hostname.
• --server URL: the AgentVera server. Defaults to https://app.agentvera.dev.
• --no-service: don’t install a background service, if you’ll only use the runner from the desktop app over SSH.

curl -fsSL https://app.agentvera.dev/runner/install.sh | sh -s -- --pair KOD --name build-server

What the installer does

• Installs Runner into ~/.agentvera-runner/app (a folder only you can open) and links the command as ~/.local/bin/agentvera-runner.
• On Linux with systemd, creates a user service named agentvera-runner that restarts itself if it stops.
• Without systemd, Runner starts in the background and logs to ~/.agentvera-runner/runner.log; after the server reboots you start it again by hand.
• On macOS, installs a launchd agent named dev.agentvera.runner that starts at login, restarts if it stops and logs to ~/.agentvera-runner/runner.log.
• Saves the access token to a file only you can read.

On Linux, to keep Runner running after you log out, run this once:

sudo loginctl enable-linger $USER

Command line

agentvera-runner status               # version, service, pairing, server and allowed folders
agentvera-runner roots ~/projects      # limit agents and file access to these folders
agentvera-runner pair KOD --name NAME  # pair again
agentvera-runner daemon                # run Runner in the foreground

Without roots, agents work in your home folder. After pairing again, restart the service; Runner connects on startup.

Managing the service

Linux (systemd):

systemctl --user status agentvera-runner
systemctl --user restart agentvera-runner
systemctl --user stop agentvera-runner
journalctl --user -u agentvera-runner -f

macOS (launchd):

launchctl unload ~/Library/LaunchAgents/dev.agentvera.runner.plist   # stop
launchctl load -w ~/Library/LaunchAgents/dev.agentvera.runner.plist   # start
tail -f ~/.agentvera-runner/runner.log

Connecting from the desktop app

The Runner page in the AgentVera desktop app connects to runners in two ways: through the cloud with the same account, or directly over a saved SSH server. If you’ll use SSH, you can install with --no-service; the app starts Runner itself when it connects.

Uninstalling

1. Delete the runner on app.agentvera.dev/runners. Its token is revoked immediately and it stops reconnecting.
2. Stop and remove the service.
3. Delete Runner’s files.

# Linux
systemctl --user disable --now agentvera-runner
rm ~/.config/systemd/user/agentvera-runner.service

# macOS
launchctl unload ~/Library/LaunchAgents/dev.agentvera.runner.plist
rm ~/Library/LaunchAgents/dev.agentvera.runner.plist

# both
rm -rf ~/.agentvera-runner ~/.local/bin/agentvera-runner

Security

• Runner only opens outbound connections; you don’t need to open ports or change the firewall.
• Only active members of your organization can see and connect to the runner. Support staff viewing as a user cannot connect.
• Open connections are closed for users whose membership ends or whose organization is suspended.
• Use roots to decide which folders agents and file access are limited to.
• Webhook-triggered tasks can send prompts to the runner; connect only sources you trust.

Troubleshooting

• “Node.js 20 ya da üstü gerekli” (Node.js 20 or later required): install Node.js 22 and run the command again.
• Invalid pairing code: its 10 minutes may have run out; get a new code on /runners.
• Runner doesn’t show as online: check the output of agentvera-runner status and the logs; make sure the server can reach app.agentvera.dev:443.
• An agent type is missing under “Yeni ajan”: install that CLI on the server and sign in; Runner only lists the agents it finds installed.