Agent Deployment

The EasyShell Agent is a lightweight Go binary that runs on each managed host. It handles script execution, metrics collection, and real-time log streaming.

Features

• Single binary — No runtime dependencies, simple deployment
• Cross-platform — Linux (amd64, arm64), macOS
• Low overhead — Typically under 20 MB memory usage
• Auto-registration — Agents automatically register with the server on first start
• Self-healing — Automatic reconnection on network interruptions

Installation

Automatic Deployment (Recommended)

The easiest way to deploy agents is through the EasyShell web interface:

1. Go to Host Management → Add Host
2. Select Automatic Deployment
3. Enter the target host’s SSH credentials (IP, port, username, password/key)
4. The server will SSH into the target, upload the correct binary (amd64/arm64), and start the agent

Tip

Before using automatic deployment, ensure PROVISION_SERVER_URL in your .env is set to the server’s externally reachable address (e.g., http://your-server-ip:18080).

Extract from Docker Image

Agent binaries are bundled inside the server Docker image. You can extract them:

# Extract amd64 binary
docker cp $(docker create --rm laolupaojiao/easyshell-server:latest):/opt/easyshell/agent-binaries/easyshell-agent-linux-amd64 ./easyshell-agent
chmod +x ./easyshell-agent

Pre-built Binaries (GitHub Releases)

Caution

GitHub Releases are not yet available. For now, use automatic deployment via the web UI or extract binaries from the Docker image.

Build from Source

cd easyshell-agent
GOOS=linux GOARCH=amd64 go build -o easyshell-agent-linux-amd64 ./cmd/agent

Requires Go 1.24+.

Configuration

The agent is configured via environment variables or a configuration file:

Variable	Default	Description
EASYSHELL_SERVER_URL	http://localhost:18080	Server API endpoint
EASYSHELL_AGENT_NAME	hostname	Display name for the agent
EASYSHELL_HEARTBEAT_INTERVAL	30s	Heartbeat frequency
EASYSHELL_METRICS_INTERVAL	60s	Metrics reporting frequency

Running as a Service

Create a systemd service for the agent:

[Unit]
Description=EasyShell Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/easyshell-agent
Restart=always
RestartSec=5
Environment=EASYSHELL_SERVER_URL=https://easyshell.example.com

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable easyshell-agent
sudo systemctl start easyshell-agent

Communication Protocol

The agent communicates with the server using two protocols:

• HTTP — Registration, heartbeat (30s interval), metrics reporting (60s interval), configuration polling
• WebSocket — On-demand connections for real-time log streaming during script execution and interactive terminal sessions

Tip

If your hosts are behind a firewall, ensure outbound HTTP/HTTPS and WebSocket connections to the server are allowed. The agent always initiates connections — no inbound ports need to be opened.

Verifying Agent Status

After starting the agent, verify it appears in the EasyShell web interface:

1. Navigate to Host Management
2. The new agent should appear with a green status indicator
3. Click the host to view real-time metrics

If the agent does not appear, check the agent logs:

journalctl -u easyshell-agent -f