> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipways.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# When Shipways is locked out

> The two ways Shipways reaches a machine, and what to do when both are gone.

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`.

```bash theme={null}
systemctl status shipways-agent
journalctl -u shipways-agent -n 50
```

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.

<Note>
  Shipways' own key is never shown in the server's
  [SSH keys](/servers/ssh-keys) list and is never offered for removal, because
  removing it is exactly this situation.
</Note>

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.

<Warning>
  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.
</Warning>

## Putting it back

<Steps>
  <Step title="Open a console on the machine">
    Your provider's web console, or SSH from another machine that can still
    sign in.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Run it as root">
    Not as the deploy user. Root's copy of the file is half the point.
  </Step>

  <Step title="Watch the server go online">
    The agent reports in within a minute or so and the panel follows by itself.
  </Step>
</Steps>

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](/servers/firewall#sync) — Shipways can still reach the machine.

The reverse — a working SSH rule and a dead agent — is the case above.