Installation

Openship has a few different front doors, and they all lead to the same place. Think of it like getting a new appliance: you can grab the quick-start cable (the install script), unpack it with tools you already own (npm), buy the ready-to-use boxed version (the desktop app), or wire it into your workshop for good (Docker Compose). Pick the one that fits you — you can always switch later.

Install

curl -fsSL https://get.openship.io | sh

irm https://git.openship.io/windows | iex

npm i -g openship

pnpm add -g openship     # pnpm
yarn global add openship  # yarn
bun add -g openship       # bun

curl -fsSL https://get.openship.io/dev | sh

curl -fsSL https://get.openship.io/dev | OPENSHIP_REF=my-branch sh

openship-dev            # interactive setup + control panel
openship-dev up         # run locally
openship-dev update     # pull the latest source + rebuild in place (no npm release needed)

openship install

chmod +x Openship.AppImage
./Openship.AppImage

git clone https://github.com/oblien/openship.git
cd openship
cp .env.example .env          # then edit the secrets inside
docker compose --env-file .env -f docker/docker-compose.yml up -d

Run Openship

If you installed the CLI (the install script or npm), the quickest start is the guided setup — run:

openship

With no arguments, openship walks you through it: private or public, your domain (if public), and your admin name, email, and password. It then deploys, creates your admin account, and prints the URL to sign in. This is the recommended way to stand up a new instance.

Prefer to skip the prompts? openship up starts the same background service directly:

openship up

Either way, Openship runs as a background service that starts on boot and restarts itself if it crashes — like a delivery truck that always comes back to the depot. It runs the API on :4000 and the dashboard on :3001, backed by a built-in database in bare mode (or Postgres + Redis in Compose mode). A CLI instance always requires a login — the admin you create during openship setup, or the first account you register in the dashboard when you run openship up directly.

openship stop              # stop the service — it won't restart or come back on reboot
openship up --foreground   # run it attached to this terminal instead (a one-off; stop with Ctrl-C)
openship up --no-ui        # run the API only, without the dashboard
openship uninstall         # remove Openship + its data (see below)

Host control (hardening)

The control plane can operate the machine it runs on: free ports 80/443 from an existing proxy, read host config, scan listening ports, open a host shell. On a Compose install that channel is an SSH key to the host that openship up generates and authorizes for the invoking user (reached over the internal host.docker.internal bridge, never the public IP).

You can withhold it:

openship up --no-host-control

With it set: no host key is generated or mounted, host operations refuse with a clear error, and this box stops being listed as a deploy target ("This Server" disappears). It is CLI-only on purpose — a toggle in the dashboard would be reachable by the very thing it defends against.

Which posture to use

Removing Openship

openship stop halts Openship but keeps everything — the database, issued certificates and edge config all survive, so openship up picks up where it left off. To remove it:

openship uninstall                 # asks first; removes the stack, its data, its images and ~/.openship
openship uninstall --keep-data     # remove the running stack only, keep the database + certificates
openship uninstall --keep-images   # don't delete the Openship container images
openship uninstall --yes           # skip the confirmation (scripts)

Two things it deliberately leaves alone, because a self-hosted box is usually shared:

• Your deployed apps keep running. Removing the control plane doesn't stop the containers it created — docker ps still shows them. Delete the projects first if you want those gone too.
• Nothing is pruned. Only Openship's own three images (by exact tag) and this stack's volumes are removed; your other images, volumes and containers are untouched.

Under the hood, openship up registers with your operating system's service manager so it can survive reboots:

• Linux — a systemd unit (--user with linger enabled, or a system unit when you run it as root).
• macOS — a launchd agent that reloads at login.
• Windows — a Scheduled Task at logon (best-effort; here openship up --foreground or the desktop app are the more reliable options).

Fully unattended install (headless)

openship up on its own installs only the service — the first admin is created in the dashboard (or via the interactive openship wizard). Add --non-interactive (alias --yes) plus the install flags to provision a box with no prompts — admin account and (where supported) domain included. Ideal for CI, cloud-init, or scripted fleets.

The admin bootstrap and the byo / free / none domain steps run on both install methods (Compose and bare). The one difference is a managed custom domain (Openship issues the Let's Encrypt cert itself), which is wired only for the bare install — see below.

Bare install (--bare, embedded DB, no Docker) — Openship manages the host's OpenResty, so --domain-kind custom provisions the cert end-to-end:

OPENSHIP_ADMIN_PASSWORD='a-strong-password' openship up --bare --non-interactive \
  --admin-email you@example.com --admin-name "You" \
  --domain-kind custom --hostname ops.example.com \
  --acme-email you@example.com --edge takeover

Compose install (the default on Linux with Docker) — the edge runs as a container, and takes every domain kind the bare install does, including custom. If an existing proxy holds :80/:443, --edge pre-answers what to do with it (migrate imports its sites into Openship's edge first; takeover stops it and its sites stop serving):

OPENSHIP_ADMIN_PASSWORD='a-strong-password' openship up --non-interactive \
  --admin-email you@example.com --admin-name "You" \
  --domain-kind custom --hostname ops.example.com \
  --acme-email you@example.com --edge migrate

• Admin — --admin-email (required) + optional --admin-name. The password comes from --admin-password or, preferably, the OPENSHIP_ADMIN_PASSWORD env var (keeps it out of your shell history). Idempotent: re-running resets the existing admin's password instead of failing. Works on both methods.
• Domain — --domain-kind:
  • byo — front Openship with your own reverse proxy (--hostname, or derived from --public-url). Both methods.
  • custom — Openship's edge issues a Let's Encrypt cert for --hostname; --acme-email and --edge migrate|takeover|cancel pre-answer the :80/:443 takeover. Both methods: the API picks the host OpenResty or the container edge from OPENSHIP_EDGE_MODE, so the CLI makes the same calls either way.
  • free — a <slug>.opsh.io subdomain (--slug). Requires the box to already be connected to Openship Cloud (the free-domain connect is an interactive browser step) — connect first, then run the headless install, or use byo.
  • none (default when no domain flags) — a private box with no public domain.

Any missing or invalid flag exits non-zero with a precise message, so it's safe to script. Certificate issuance streams its progress as it goes (ACME can take a minute on a fresh domain) and is best-effort: if it doesn't finish, the install still succeeds and reports why, then retries in the background and on the next boot. Add --dry-run to preview the installed service without provisioning.

Open it and check it's working

With a local instance running, open the dashboard in your browser:

openship open

Or check the API's health straight from the terminal:

openship status

Openship Cloud

Don't want to run a server at all? Sign up for Openship Cloud — the same platform, fully managed for you.

Next steps