Upgrade your network agent before 17 March 2027

Every network agent identifies itself to DeployHQ with a security certificate. The authority that signed those certificates expires on 17 March 2027, so we are moving agents to certificates signed by a new authority.

The latest version of the agent does this for you: it picks up its new certificate automatically the next time it connects. All you need to do is upgrade the agent on each machine that runs one, before 17 March 2027. There is no new agent to create, no claim code, and no configuration to change.

Which agent are you running?

There are two versions of the agent. Run whichever of these exists on the machine:

network-agent version
deploy-agent version

If network-agent responds, follow Upgrading network-agent. If only deploy-agent responds, you are running the legacy Ruby agent; follow Upgrading the Ruby deploy-agent.

If both respond, the machine was migrated but the old gem was left installed. Upgrade network-agent -- that is the one your account is connected through -- and ignore the gem. Only one agent should be running: check with deploy-agent status, and stop it with deploy-agent stop if it is.

Restarting the agent briefly disconnects it, so upgrade when no deployment is running through it.

Upgrading network-agent

network-agent update
network-agent restart

update replaces the binary; restart makes the running agent use it. Both steps are needed -- the agent does not update itself in the background.

If network-agent update reports an unknown command, you are on an early release that predates it. Reinstall with the install script instead, then restart:

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

If you installed the agent as a service with network-agent install, restart it through the service manager rather than with network-agent restart:

# Linux (systemd)
systemctl --user restart network-agent

# macOS (launchd)
launchctl kickstart -k gui/$(id -u)/com.deployhq.network-agent

Upgrading the Ruby deploy-agent

gem install deploy-agent
deploy-agent restart

Use gem install, not gem update. On some Ruby versions gem update deploy-agent reports that the gem is already up to date and installs nothing.

If you run the agent under systemd, as described in Run the DeployHQ agent on startup, restart the service instead of running deploy-agent restart.

If gem install deploy-agent fails, switch to network-agent rather than work out why. The gem needs Ruby 2.7 or later, and it builds a native extension during installation, so it can also fail on a machine without a compiler or with headers it does not match. network-agent is a single binary: no Ruby, no build step, and it keeps your existing agent, certificate and access list -- see Migrating from the Ruby deploy-agent to network-agent.

Switching is our recommendation for everyone still on the Ruby agent, whether or not the upgrade works on your machine.

What happens after you upgrade

Shortly after it starts, the agent asks DeployHQ for its new certificate, checks it, saves it in place of the old one, and reconnects once to begin using it. From then on it carries on exactly as before:

• It is the same agent, with the same name, in your account.
• Servers that connect through it need no changes.
• ~/.deploy/agent.access is untouched.
• The private key in ~/.deploy/ does not change and never leaves the machine.

The new certificate is only saved if it matches the agent's existing key and was signed by an authority the agent trusts. If anything about it is wrong, the agent keeps the certificate it already has and tries again on its next connection, so a failed check never takes a working agent offline.

Checking it worked

• The agent log is the check to trust. Look in ~/.deploy/agent.log (or your service manager's log, such as journalctl --user -u network-agent, if you run it as a service) for certificate renewed from network-agent, or Certificate renewed from deploy-agent.
• For network-agent, network-agent check lists the certificate authorities the agent trusts and when each expires. After a successful upgrade it lists the new authority.
• The agent also still shows as connected under Settings > Network Agents. Treat that as a supporting signal rather than proof: it reflects the last connection we recorded for the agent, so check the log if you need certainty.

What the log looks like

Both agents write to ~/.deploy/agent.log on the machine that runs them. If you run the agent as a service, the same lines go to your service manager's log instead.

network-agent collects the certificate, then reconnects to start using it:

time=... level=INFO msg="connected to server" addr=agent.deployhq.com:7777
time=... level=INFO msg="certificate renewed" issuer="DeployHQ Agent CA" serial=1234 expires=2036-03-01
time=... level=INFO msg="reconnecting to present the renewed certificate"
time=... level=INFO msg="connecting to server" addr=agent.deployhq.com:7777
time=... level=INFO msg="connected to server" addr=agent.deployhq.com:7777

deploy-agent records the same swap in its own format:

I, [...]  INFO -- : Successfully connected to server
I, [...]  INFO -- : Certificate renewed (issuer=/CN=DeployHQ Agent CA/O=DeployHQ)
I, [...]  INFO -- : Attempting to connect to agent.deployhq.com
I, [...]  INFO -- : Successfully connected to server

Your serial number and expiry date will differ. What confirms the swap is DeployHQ Agent CA as the issuer, followed by the agent connecting again -- that second connection is the agent presenting its new certificate.

This happens once. Once the agent holds the new certificate it has nothing left to collect, so you will not see these lines again on later restarts.

Check soon after upgrading. deploy-agent keeps a small rolling log -- five files of 10 KB, which you will see as agent.log, agent.log.0 and so on -- so on a busy agent these lines can rotate away.

Frequently asked questions

Do I need to create a new agent? No. The upgraded agent keeps its identity and collects its new certificate by itself.

Do I need to change my firewall? No. The agent still makes the same outbound connection on port 7777 to agent.deployhq.com.

I have agents on several machines. Do I need to upgrade all of them? Yes. Each agent holds its own certificate, so each one needs upgrading.

What happens if I don't upgrade in time? From 17 March 2027 an agent that has not collected its new certificate can no longer connect, and deployments to servers that use it will fail with The network agent is not connected. Upgrading at that point is not enough on its own, because the agent can no longer connect to collect the certificate. You would need to upgrade, then set up a new agent under Settings > Network Agents and select it on the servers that used the old one.

Need help?

If you're not sure which agent you're running or the upgrade doesn't behave as described here, please get in touch -- we're happy to help you through it before the deadline.