Last updated on 23rd March 2026

Migrating from the Ruby deploy-agent to network-agent

The original DeployHQ agent was distributed as a Ruby gem (deploy-agent). It has been replaced by network-agent, a single static binary written in Go that requires no runtime dependencies.

What's new

  • No Ruby installation required — download one binary and run it
  • Supports Linux (amd64, arm64) and macOS (amd64, arm64)
  • Same configuration files (~/.deploy/) — no reconfiguration needed
  • Same CLI commands (setup, start, stop, restart, status, run)
  • New commands: check (verify configuration and connectivity) and install (register as a system service)

Migrating an existing agent

Your existing certificate and access list work unchanged. The migration is a binary swap:

1. Stop the running Ruby agent

deploy-agent stop

2. Install the new binary

curl -sSL https://deployhq.com/install/network-agent | bash

3. Start the new agent

network-agent start

That's it. The agent will reconnect using the same certificate and appear online in your account.

To roll back, you will need Ruby and RubyGems installed on the host. Stop the Go binary, reinstall the Ruby gem, and start again:

network-agent stop
gem install deploy-agent
deploy-agent start

If Ruby is not installed, follow the installation steps for your OS (e.g. sudo apt install ruby on Debian/Ubuntu or sudo yum install ruby on RedHat/CentOS) before running gem install.

Fresh installation

For new agents, follow the setup steps at Settings > Network Agents > New Network Agent. The page now uses the new binary automatically.

Installing as a system service

The new binary includes a built-in install command that registers it as a system service so it starts automatically on boot:

network-agent install

This creates a launchd agent on macOS or a systemd user service on Linux.

Verifying your setup

Run network-agent check to validate your certificate, private key, access list, and connectivity to the DeployHQ servers:

network-agent check

Frequently asked questions

Do I need to create a new agent in my account? No. The existing certificate in ~/.deploy/ is reused. The agent will appear online under the same name.

Do I need to update the access list? No. The ~/.deploy/agent.access file format is unchanged.

Can I run the agent without installing it as a service? Yes. network-agent run runs the agent in the foreground, which is useful with Docker or systemd if you prefer to manage the process yourself.