Skip to content

Reach the API without a hostname ​

The agent's API does not have to be reachable from the internet. This page shows how to leave it unexposed and use shipwick through an SSH tunnel or a private network instead. It is for servers where you have no hostname to spare for the API, or prefer not to publish it.

Never expose port 9000

The API speaks plain HTTP, and an admin token is equivalent to root SSH access to the server. Do not publish port 9000 on a public interface and do not open it in your firewall. The ways in are HTTPS through Caddy, an SSH tunnel, or a private network.

Leave the API hostname empty ​

When the installer asks for the API hostname, press Enter. SHIPWICK_AGENT_DOMAIN stays empty in /opt/shipwick/.env, Caddy serves no route to the API, and the agent container publishes no port. The installer says so when it finishes:

text
  No API hostname was set, so the API is not exposed. Reach it through a tunnel:
    1. create /opt/shipwick/compose.override.yml:
           services:
             agent:
               ports: ["127.0.0.1:9000:9000"]
       and run:   cd /opt/shipwick && docker compose up -d
    2. on your laptop:   ssh -N -L 9000:127.0.0.1:9000 root@<this-server> &   shipwick login

To take an existing API hostname away, set SHIPWICK_AGENT_DOMAIN= to empty in /opt/shipwick/.env and run docker compose up -d in /opt/shipwick.

shipwick server install user@host without --agent-domain does the same from your laptop: the API is not exposed, and the context it saves points at http://127.0.0.1:9000, ready for the tunnel below. Through the tunnel, shipwick doctor cannot check the ports and the records' targets, since it learns the server's address from the agent's hostname.

Applications and the dashboard are not affected. The dashboard reaches the agent over the internal shipwick-control network, so you can keep the dashboard on a hostname while the API stays private.

Publish the API on the server's loopback ​

In the installer's setup the agent runs in a container that publishes no port, on purpose. For a tunnel to have something to connect to, publish the port on the server's loopback address only.

Create /opt/shipwick/compose.override.yml with a ports entry for the agent service. Compose merges this file with compose.yml, and an upgrade never replaces it:

yaml
services:
  agent:
    ports: ["127.0.0.1:9000:9000"]

Then:

bash
cd /opt/shipwick && docker compose up -d

The 127.0.0.1: prefix matters. Without it, Docker publishes the port on every interface of the server.

A published port wants Docker 28 or later

Docker forwards a published port to the network a container's default route goes through, and before 28 that is the network the applications are on. The agent then keeps listening there so that the port works, and the API is open to the containers of applications, protected by the token alone; shipwick doctor says so. On Docker 28 and later the port arrives on the control network and nothing is open. Upgrade Docker, or give the API a hostname and remove the port. There is no third way on Docker 27: the compose files start the agent on the control network alone, and the moment it joins shipwick for its health checks the daemon moves the port there — measured on Docker 27.5.1, where the forwarding rule went from the control address to the application network's with the join, and a listener on the control address alone was reset; on 29.9 with the agent's gateway priority it stayed. That is why the installer publishes no port. See Who can reach the API.

If the agent runs as a service of the host instead — installed from a package, or as a plain binary — there is nothing to do: it listens on 127.0.0.1:9000 by default.

Open an SSH tunnel ​

On your laptop:

bash
ssh -N -L 9000:127.0.0.1:9000 user@server &

This forwards port 9000 on your laptop to port 9000 on the server's loopback, over SSH. -N opens the tunnel without starting a remote shell.

Then log in. The default URL of shipwick is http://127.0.0.1:9000, which is the tunnel:

bash
shipwick login
text
Agent URL [http://127.0.0.1:9000]:
API token:

Press Enter to accept the URL, and paste the token. From then on every shipwick command works as long as the tunnel is open. Without the tunnel, shipwick reports that it cannot reach the agent and reminds you of the ssh -L command.

If you also use a server that has a hostname, save the tunnelled one under a name of its own — shipwick login --context lab — and switch with shipwick context use; see Several servers.

shipwick does not warn about plain HTTP here: the token only travels to your own machine's loopback address, and SSH encrypts it from there.

Use a private network ​

If the server and your laptop or CI runner share a private network — WireGuard, Tailscale or similar — you can reach the API over it. Publish the agent's port on the server's private address instead of loopback, in the same compose.override.yml:

yaml
services:
  agent:
    ports: ["<private address>:9000:9000"]

Then point shipwick at it:

bash
shipwick login --url http://<private address>:9000

shipwick warns whenever a token is about to travel over plain HTTP to anything other than the local machine, and it will do so here. It cannot know that the network underneath is encrypted. Make sure that it is, and that the address is not reachable from outside the private network.

CI ​

A pipeline needs to reach the API as well. A runner inside your private network can use the private address. For hosted runners, serving the API over HTTPS with SHIPWICK_AGENT_DOMAIN is the usual choice; see Deploy from CI.

What's next ​