Skip to main content
Shipways reaches a machine in two ways. The agent runs on the server and calls out over HTTPS, which is why a firewall that blocks everything inbound does not stop it. SSH is the fallback, used for provisioning and whenever the agent cannot do the work itself. Losing both is what “locked out” means here, and it is the one fault the panel cannot repair on its own: putting a way in back would itself need a way in. Everything on this page is done from your provider’s console, or from another machine that can still sign in. The server’s Network tab has a If Shipways is locked out section holding that machine’s key and a ready-made repair command, with its real user, port and paths filled in. Copy them from there rather than from here.

​
Start with the agent

A silent agent is more common than a missing key, and it is a different fault. If the panel says the agent is not reporting in, that may be the whole problem. The unit is shipways-agent, and its configuration — including the token it authenticates with — is /etc/shipways/agent.env.
An agent that has stopped usually needs nothing more than systemctl restart shipways-agent. One that starts and then fails to authenticate is a token problem, not a key problem, and reconnecting the server is the fix.

​
The key, and the two files it belongs in

Every server gets its own key from Shipways. It opens that one machine, so the one on the Network tab is safe to read out over the phone to whoever is at the console — it is not a key to your fleet.
Shipways’ own key is never shown in the server’s SSH keys list and is never offered for removal, because removing it is exactly this situation.
It belongs in two files, and they fail differently. The deploy user’s ~/.ssh/authorized_keys is written by Shipways and rewritten every time the key set changes. It repairs itself, as long as something can still get in. Root’s /root/.ssh/authorized_keys is written once, when the machine is connected, and never touched again. That makes it the copy that quietly goes missing — to a provider image, a configuration management tool, or a colleague tidying up — and its absence tends to be discovered on the day it was the last way in.
sshd refuses to read a key file that anybody but its owner can write, and says nothing about it in any log you are likely to find. Both files want mode 0600, in a .ssh directory at 0700, owned by the account they belong to.If a key looks correct and still does not work, check the modes before you check anything else.

​
Putting it back

1

Open a console on the machine

Your provider’s web console, or SSH from another machine that can still sign in.
2

Copy the command from the Network tab

It appends the key to both files if it is absent, fixes the directory and file modes, and restarts the agent. It is safe to run on a machine that is fine — nothing is duplicated and nothing is overwritten.
3

Run it as root

Not as the deploy user. Root’s copy of the file is half the point.
4

Watch the server go online

The agent reports in within a minute or so and the panel follows by itself.
Password authentication is off on every machine Shipways provisions, so a key is the only way in. If you are pasting the key by hand rather than running the command, mind the newline: providers often leave authorized_keys without a trailing one, and a key joined onto the end of the previous line is a key that silently does nothing.

​
When the firewall is what shut the door

A rule set with no SSH in it locks people out while leaving the agent working, because the agent is outbound. The panel warns before syncing a rule set like that, and the fix is to add the rule back and sync — Shipways can still reach the machine. The reverse — a working SSH rule and a dead agent — is the case above.