Wiadro Agent

The Wiadro Agent is a CLI tool that runs on machines you want to manage via the Wiadro server. It maintains a persistent connection to the cloud server and manages the local OpenCode instance.

Installation

# Install globally
npm install -g wiadro

# Or from source
git clone https://github.com/your-org/wiadro.dev.git
cd wiadro.dev/packages/agent
npm install
npm run build
npm link

Quick Start

# Get your agent token from the Wiadro dashboard
# (Machines -> Add Machine -> Copy Token)

# Connect to your server
wiadro connect https://your-server.com YOUR_AGENT_TOKEN --daemon

# Check status
wiadro status

# View logs
wiadro logs

Commands

Connection Management

# Connect to server (foreground)
wiadro connect <serverUrl> <agentToken>

# Connect as background daemon
wiadro connect <serverUrl> <agentToken> --daemon

# Options:
#   -p, --port <port>   OpenCode port (default: 4096)
#   --auto-start        Auto-start OpenCode on connect
#   -d, --daemon        Run in background

# Disconnect and remove config
wiadro disconnect

Daemon Control

# Start daemon (requires prior connect)
wiadro up

# Stop daemon
wiadro down

# Check status
wiadro status

# Restart agent
wiadro restart --agent

OpenCode Control

# Start OpenCode server
wiadro start

# Stop OpenCode server
wiadro stop

# Restart OpenCode server
wiadro restart

Logs

# View last 50 lines
wiadro logs

# View last N lines
wiadro logs -n 100

# Clear logs
wiadro logs --clear

Configuration

The agent stores its configuration in ~/.wiadro/:

| File | Description | | ----------------- | -------------------------------- | | config.json | Server URL, token, port settings | | agent.pid | PID file for daemon | | agent.log | Standard output | | agent.error.log | Error output |

config.json

{
  "serverUrl": "https://your-server.com",
  "agentToken": "your-agent-token",
  "opencodePort": 4096,
  "autoStart": false
}

Running as a System Service

systemd (Linux)

Create /etc/systemd/system/wiadro-agent.service:

[Unit]
Description=Wiadro Agent
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/home/your-user
ExecStart=/usr/local/bin/wiadro run
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

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

launchd (macOS)

Create ~/Library/LaunchAgents/com.wiadro.agent.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.wiadro.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/wiadro</string>
        <string>run</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.wiadro.agent.plist

How It Works

1. Connection: Agent establishes an SSE (Server-Sent Events) connection to the Wiadro server
2. Heartbeat: Every 30 seconds, agent sends status + OS info to server
3. Commands: Server can send commands (START, STOP, RESTART) via SSE
4. Status Updates: Agent reports OpenCode status changes back to server
5. Reconnection: Auto-reconnects with exponential backoff on disconnect

Requirements

• Node.js 20+
• OpenCode CLI installed (npm install -g opencode)
• Network access to Wiadro server

Troubleshooting

Agent won't connect

# Check logs
wiadro logs

# Verify config
wiadro status

# Try foreground mode to see errors
wiadro down
wiadro run

OpenCode won't start

# Check OpenCode is installed
opencode --version

# Check port availability
lsof -i :4096

# Try starting manually
opencode serve --port 4096

Permission denied

# Make sure the binary is executable
chmod +x $(which wiadro)

# Check npm global bin is in PATH
npm bin -g

Development

cd packages/agent
npm install
npm run dev    # Watch mode
npm run build  # Build

License

MIT