Back to guidesGuide 04

Set up an SSH host and remote agent.

This walkthrough takes you field by field through Remote Agents → Setup: add an SSH host, verify and pin its host key, install the managed CrazyToad Agent, and pick how much the agent is allowed to do.

Before you start

Open Remote Agents → Setup

In CrazyToad, open Remote Agents and click the Setup rail item. With nothing configured you'll see "No remote hosts yet" — the empty state explains the flow: point CrazyToad at a machine over SSH, verify its host key, then install the first-party CrazyToad Agent on it. Installs are refused until the host key is verified and pinned. The two screenshots below show the chatbox you'll drive the agent from and the Setup screen you're about to fill in.

remote agents - chatbox
CrazyToad Remote Agents chatbox and overview
Chatbox, overview, live stream, daily log, and agent rail
remote agents - setup
CrazyToad Remote Agents setup without sensitive host details
Host setup with sensitive details redacted
01
Have your SSH access ready

You need SSH access to the box and a private SSH key — password auth is not supported.

02
Add the SSH host

Register the machine, then let CrazyToad verify and pin the host key. Nothing installs until that pin succeeds.

03
Install the CrazyToad Agent

For a managed agent, install the binary at /usr/local/bin/crazytoad-agent — the dialog can do it for you, or you can run the commands manually.

04
Set the run envelope

Pick how autonomous the agent is — observe, suggest, approve, or auto-limited — and list any protected paths it must pause on.

Step 1

Add an SSH host

Click Add SSH host to open the "Add remote host" dialog. Auth is SSH private key only — there is no password field. On Save, CrazyToad stores the host, then verifies and pins its host key before any install is allowed.

01
Name the host

Enter a Name. This becomes the host id used everywhere else in Remote Agents.

02
Point at the machine

Fill in SSH host (hostname or IP), Port (defaults to 22), and the User to connect as.

03
Choose a key

Under Stored key, pick a key already saved in Manage, or choose "Paste new key…" to add one now.

04
Supply the private key

Either enter an existing vault Key id, or leave it blank and paste a key below with a New key label so CrazyToad saves it.

05
Save and pin

Click Save. CrazyToad connects, verifies the host key, and pins it. Until that succeeds, no agent can be installed on this host.

NameRequired. A friendly label that becomes the host id.
SSH hostRequired. The hostname or IP of the machine.
PortSSH port number. Defaults to 22.
UserRequired. The SSH user CrazyToad connects as.
Stored keyPick a key saved in Manage, or “Paste new key…” to add one.
Key idAn existing vault key id, or leave blank to paste a key below.
New key labelName for the key you’re pasting, so it’s saved to the vault.
Paste SSH keyThe private key body, starting -----BEGIN OPENSSH PRIVATE KEY-----.
Installs are gated on the host key. CrazyToad refuses to install any agent until the host key is verified and pinned. Private keys are stored in the OS-bound vault and only materialized to a temp file while connecting.
Step 2

Install the CrazyToad Agent

Open the "Install CrazyToad Agent" dialog. Choose the managed install to let CrazyToad provision the agent for you, or a generic log tail if you only want to read logs. The managed agent streams health and activity, answers Chatbox messages, exposes MCP listings, and self-tests stream, chat, MCP, and config before it connects.

01
Name the agent

Enter a Name for this agent and pick the Host you added in Step 1. The list shows free slots as Name (N/2 agent slots).

02
Pick the agent type

Choose "CrazyToad Agent (managed install)" for a full managed agent, or "Generic log tail (no agent install)" to attach without installing anything.

03
Choose the LLM account

Pick a connected account under LLM account to drive the agent's reasoning. Subscription accounts render disabled — use an API or local account.

04
Confirm the bridge commands

Keep the default Bridge command and Message command unless your install path differs. The bridge command must be an absolute path.

05
Write the persona

Use Persona to author the agent's system prompt — how it should behave and what it's responsible for.

NameRequired. The display name for this remote agent.
HostThe host to install on. Shows “Name (N/2 agent slots)”; max 2 agents per host.
Agent type“CrazyToad Agent (managed install)” or “Generic log tail (no agent install)”.
LLM accountA connected account that drives the agent. Subscription accounts are disabled here.
Bridge commandRequired, absolute path. Default /usr/local/bin/crazytoad-agent stream.
Message commandOptional. Default /usr/local/bin/crazytoad-agent chat -q {{message}}.
PersonaThe agent’s system prompt — how it should behave.
Two limits to remember. A subscription account can't drive a remote agent — it ships disabled in the LLM account picker, so use an API or local account. And each host holds a maximum of 2 agents. Keep the {{message}} placeholder in the Message command — that's where your Chatbox text is inserted.
Advanced

Prefer the command line? Manual install

If you'd rather provision the agent yourself, run these from your CrazyToad checkout. They copy the agent and run the provisioning script, which installs a hardened systemd service. Replace HOST and root with your own host and user.

01
Copy the agent to the host

scp deploy/remote-agent/agent.py root@HOST:/tmp/crazytoad-agent.py

02
Run the provisioning script

ssh root@HOST 'bash -s' < deploy/remote-agent/provision.sh

03
Register the host

Back in CrazyToad, add the host in the dialog (Step 1) so CrazyToad can attach to the service you just provisioned.

The bridge is a wire protocol. The agent speaks crazytoad.remote-agent.v1 — newline-delimited JSON with a 15s heartbeat. Once attached, the Brain management panel catalogs the agent's brain connections (MCP, API, Docs, Other) and shows each as live, planned, or error.
Step 3

Set the run envelope

The run envelope is a safety ladder — four rungs from least to most autonomy. Start low and raise it only as you trust the agent. Whatever rung you pick, list Protected paths the agent must always pause on.

01
observe

Watches only — never changes anything. Safest starting point.

02
suggest

Plans and proposes — you run the changes yourself.

03
approve

Acts, but pauses for your OK on risky work.

04
auto-limited

Runs routine work alone — stops at protected paths.

observeWatches only — never changes anything.
suggestPlans and proposes — you run the changes.
approveActs, but pauses for your OK on risky work.
auto-limitedRuns routine work alone — stops at protected paths.
Protected pathsGlob patterns the agent must pause on, e.g. /etc/**, **/.env.
Protected paths apply at every rung. Even on auto-limited, the agent stops when it touches a protected path. Use globs like /etc/** and **/.env to fence off config and secrets.
All guidesLilly PodManageFeatures