Servers & SSH
Fix a server that won't connect over SSH, a component that won't install or reports unhealthy, missing Docker, and port-forward tunnels that won't start.
When you deploy to your own machine, Openship reaches it over SSH — the same way you'd type ssh you@your-box
in a terminal. Most "my server won't work" problems come down to one of four things: Openship can't log in,
can't reach the box, can't install a tool it needs, or a tool it installed isn't running. This page walks
through each one.
Where this lives
Servers are at /servers; each server's detail screen is /servers/<serverId> with Overview,
Components, Security, Ports (desktop app only), and Terminal tabs. For the happy-path
walkthrough see Deploy to your own server and the
Servers dashboard reference. From the terminal, the matching commands live under
openship server.
Two commands that tell you what's wrong
Before fixing anything, find out which stage is failing. Two actions answer that:
- Test Connection (the button on the server form, or
openship server test-connection --host ...) tries only the SSH login, using the details you typed, and saves nothing. Use it while you're still guessing at credentials. - Re-check (the Components tab, or
openship server check <serverId>) logs into a saved server and reports which components are installed, healthy, and which required ones are missing.
If Test Connection succeeds but Re-check shows problems, your SSH is fine and the issue is a component. If Test Connection itself fails, start with the SSH sections below.
SSH connection fails
Authentication failed
Authentication failed - check your credentials, or a longer line like
SSH password authentication failed for root@123.45.67.89:22. Check the username/password, or verify that the server allows password login. / SSH key authentication failed for … Check the username, private key, passphrase, or whether the server accepts this key.
What it means. Openship reached the server, but the server rejected the login. The network is fine — the username, the secret (password / key / passphrase), or the chosen auth method is wrong, or the server doesn't accept that kind of login.
How to fix.
Confirm the Username and Port. The form defaults to root and 22; if your provider uses a
different user (like ubuntu) or a non-standard port, set them explicitly.
Match the Authentication method to how you actually log in:
- Password — the server must allow password login (
PasswordAuthentication yesin its sshd config). Many cloud images disable it. - SSH Key — the Key Path must point at a private key the machine running Openship can read
(e.g.
~/.ssh/id_rsa), and the matching public key must be in the server's~/.ssh/authorized_keys. Add the Passphrase if the key has one. - Agent — uses the host machine's running
ssh-agent; see Agent auth finds no keys.
Verify the same details work from a plain terminal: ssh -p <port> <user>@<host>. If that fails too, the fix
is on the server, not in Openship.
Re-run Test Connection. A green Connection successful means you're good; Save & Continue to Setup persists the server.
Editing keeps your old secret
When you Edit a saved server, leaving the password or key field blank keeps the stored secret. You only re-enter it when you switch auth method or rotate the credential.
Can't reach the host (refused, timed out, or unreachable)
A failure that isn't about credentials — the underlying message contains something like ECONNREFUSED,
ETIMEDOUT, EHOSTUNREACH, ENETUNREACH, or SSH connection closed before ready.
What it means. Openship never got as far as logging in. Either nothing is listening on that host and port, a firewall is dropping the packets, or the address is wrong.
ECONNREFUSED— the host answered but nothing is listening on that port (wrong port, or sshd is down).ETIMEDOUT/EHOSTUNREACH/ENETUNREACH— the packets never got a reply: wrong IP, or a firewall / security group is blocking the SSH port.
How to fix.
Double-check the Server IP Address and Port. A typo here is the most common cause.
Confirm the SSH port is open to the machine running Openship — check your provider's firewall / security-group rules, not just the server's local firewall.
Test raw reachability from the Openship host: nc -vz <host> <port> (or ssh -p <port> <user>@<host>). If
that can't connect, the problem is network/firewall, not Openship.
"Cooling down after repeated failures"
After a couple of consecutive failures Openship trips a short circuit breaker and fast-fails with
Server is unreachable — cooling down after repeated failures, retry in ~30s. instead of hammering a dead box
on every check. This is expected — fix the underlying reachability problem, wait out the countdown, then retry.
A single success clears it.
A jump host or extra SSH args seem ignored
You set a Jump Host (bastion) or Extra SSH Arguments under Advanced, but the connection behaves as if they weren't there.
What it means. The Jump Host (-J) and Extra SSH Arguments fields are only applied on the
Agent auth path, which drives your operating system's real ssh client. Password and SSH-Key auth connect
through an in-process SSH library that does not use those two fields.
How to fix.
Switch the server's Authentication to Agent so the jump host and extra args take effect.
Make sure the key that reaches the final host is loaded in your ssh-agent (see the next section), then
Test Connection again.
Prefer configuring the bastion once in your ~/.ssh/config and pointing Openship at the target host — the
Agent path reads your SSH config the same way your terminal does.
Agent auth finds no keys
Agent is selected, but the connection fails as if no key was offered — often surfacing as an authentication failure.
What it means. Agent auth authenticates exactly the way ssh <host> does in your terminal: through the
host machine's ssh-agent. Openship looks for the agent socket in SSH_AUTH_SOCK, and — because a
GUI-launched desktop app often doesn't inherit that variable — falls back to launchctl getenv SSH_AUTH_SOCK
on macOS and systemctl --user show-environment on Linux. If no agent (or no loaded key) is found, the login
has nothing to offer and fails. The Agent path is also non-interactive (BatchMode=yes), so it never prompts
for a password or passphrase — it must succeed with agent/keys alone.
How to fix.
On the machine running Openship, confirm an agent is running and has your key:
ssh-add -l. If it lists "no identities", load one with ssh-add ~/.ssh/id_rsa.
Confirm plain ssh <user>@<host> works from that same machine. If it does but Openship doesn't, the agent
socket isn't being found — restart Openship from a shell that has SSH_AUTH_SOCK set, or switch to SSH Key
auth and point at the key file directly.
On Windows, the OpenSSH agent is a named pipe rather than a socket and isn't supported on this path — use SSH Key or Password auth instead.
A component won't install or reports unhealthy
Openship installs and health-checks a small set of components on each server: Docker, Git,
OpenResty, Certbot, and rsync. Docker and Git are the core requirements for deployments; the rest
are optional infrastructure. Manage them from the server's Components tab (the System Health card) or
with openship server install/check.
Docker is missing or the daemon isn't running
Docker is not installed, or Docker is installed but the daemon is not running.
What it means. The health check runs docker --version to see if it's installed, then
docker info to see if the daemon is actually up. The first message means the binary is absent; the second
means it's present but the background service is stopped.
How to fix.
For a missing Docker, use Install on the Docker row (or openship server install <serverId> -c docker).
Openship installs it via the official curl -fsSL https://get.docker.com | sh script and, on systemd hosts,
enables and starts the service.
If it's installed but not running, start it on the server: systemctl start docker (and systemctl enable docker so it survives reboots).
Press Re-check (or openship server check <serverId>) — the Docker row should read healthy with a version.
Docker installs only on Linux
Automated Docker (and OpenResty) installation targets Linux servers. On a non-Linux host you'll see
Docker installation is only supported on Linux servers — install Docker yourself, then Re-check.
A component is installed but "unhealthy"
A row shows a version but is flagged unhealthy, e.g. OpenResty is installed but not running or
OpenResty is running but analytics scripts are not deployed - reinstall to fix.
What it means. The binary exists, but the check for it doing its job failed — the service isn't running, or (for OpenResty) its managed Lua scripts aren't in place.
How to fix.
For "not running", start the service on the server (systemctl start openresty) and Re-check.
For "analytics scripts are not deployed", use Reinstall on that component's row — this re-lays OpenResty's managed config and scripts without a destructive removal.
Watch the streamed Install Logs panel for the real error if a reinstall fails; the last lines name the package or permission problem.
Reinstall, don't remove, to refresh
Remove is destructive — removing OpenResty takes down the reverse proxy and its managed config until you install it again. If you only need to refresh scripts or settings, use Reinstall.
An install stops with an error
An install returns an error such as install_in_progress, Invalid component names, or
Invalid or missing component name.
What it means.
install_in_progress— a setup session for this server is already running; only one runs at a time.Invalid component names/Invalid or missing component name— the component isn't one Openship installs. The valid names aredocker,git,openresty,certbot, andrsync.
How to fix.
For install_in_progress, wait for the running setup to finish (its progress streams live), then start the
new install. On the dashboard the in-progress session simply re-attaches.
For an invalid name, re-run with one of the five supported components — the CLI rejects anything else up front
with Unknown component(s): … Valid: docker, git, openresty, certbot, rsync.
If an install genuinely fails, the per-component result carries the underlying error and the failed step is kept as Failed — use Retry Failed to re-run only those components.
Not the same as a build failure
If SSH and components are all healthy but a deployment fails, the problem is in the build or run step, not the server. Head to Troubleshooting → Deployments.
Port-forward tunnels won't start
Port forwarding maps a remote server port to localhost:<port> on your own machine (like VS Code's port
forwarding). It's on the Ports tab of the server detail screen.
The Ports tab is missing, or a tunnel returns "Not available"
There's no Ports tab, or a tunnel action fails with Not available in this mode.
What it means. Port forwarding is desktop-only. Forwarding a remote port to "localhost" only makes sense when the Openship orchestrator is your own machine, so the feature is hidden on hosted and self-hosted VPS instances.
How to fix. Use the desktop app to manage port forwards for that server. There's nothing to change on the server itself.
A tunnel won't open, or a port is rejected
Adding a forward is rejected with Remote port must be between 1 and 65535 or
Local port must be 0 (auto) or 1–65535, or starting one fails — the error shows the underlying reason
(often the same SSH problem as above), or a generic Failed to start tunnel when there's no detail.
What it means. The first two are validation: the remote port must be a real port, and the local port must
be 0 (let the OS pick) or a valid port. A start failure means the SSH connection couldn't open the forward —
usually the same underlying SSH problem as the sections above, or the local port is already in use.
How to fix.
Enter a Remote port in 1–65535, and either leave Local as 0 (auto) or pick a free port.
Confirm the server itself connects — open its Terminal tab or run Re-check. A tunnel rides the same SSH connection, so if SSH is down the tunnel can't start.
If the start still fails, the OS may have picked a busy local port — set Local to 0 so Openship binds any
free port, then Start again. Stop and Start cleanly reopen a stuck forward.
Still stuck?
Deploy to your own server
The full walkthrough for connecting a server and deploying to it.
Servers dashboard reference
Every field, tab, and button on the Servers screens explained.
System API
The server, check, install, and tunnel endpoints behind these screens.
Logs & monitoring
Read CPU, memory, and health signals for a connected server.
GitHub connection & repos
Fix an expired or unauthorized GitHub connection, a private repo that won't import, a public repo that should just work, and auto-deploy webhooks that never fire.
Desktop app & local data
Fix desktop and self-hosted startup problems — the database lock, "can't reach the server", a stuck update — and find where your local data lives and how to recover it.