System API

The System API runs the machinery behind a self-hosted Openship box: first-run onboarding, the SSH servers you deploy onto, installing the components those servers need (Docker, OpenResty, certbot…), port-forward tunnels, browsing the host filesystem, migrating a single-user instance into team mode, and exporting or importing the entire instance. In the dashboard this is spread across the onboarding wizard and the Settings → Servers area; from the terminal it's openship server and openship system.

Endpoints

Onboarding & setup

GET /api/system/onboarding returns { configured: boolean } — true once at least one server exists. The POST variant runs the same logic as the internal /setup push but only while the instance is unconfigured (it returns 403 "Instance already configured" afterward), so first-run flows don't need a token.

POST /api/system/onboarding

openship system onboarding apply --ssh-host 203.0.113.10 --ssh-user root --ssh-auth-method agent

The POST /api/system/setup route accepts the same body but is reserved for the desktop app and requires the internalAuth shared token rather than a user session; it can also target an existing server by passing serverId.

Instance settings

GET /api/system/settings returns the instance config (auth mode, tunnel provider, default build mode and rollback window, invitation mail source, team mode, migration target). PATCH updates only the fields you send. DELETE wipes instance settings and every server row.

PATCH /api/system/settings

curl -X PATCH https://your-host/api/system/settings \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"defaultBuildMode":"docker"}'

# Same thing from the CLI:
openship system settings set --default-build-mode docker

Promote zero-auth to a real login

POST /api/system/upgrade-to-auth turns the synthetic zero-auth user into an email/password account and flips authMode from none to local, keeping the same user id so existing projects, deployments, and audit rows still resolve. It is only callable while authMode === "none" (otherwise 400).

POST /api/system/upgrade-to-auth

openship system upgrade-to-auth --name "Ada" --email ada@example.com

Servers

A server is an SSH target you deploy onto. Responses never include SSH secrets — passwords and key passphrases are encrypted at rest and only decrypted inside the SSH client. See the custom servers guide.

POST /api/system/servers

PATCH /api/system/servers/:id takes the same fields, all optional — only the keys you send are changed.

curl -X POST https://your-host/api/system/servers \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sshHost":"203.0.113.10","sshUser":"root","sshAuthMethod":"agent"}'

# Same thing from the CLI:
openship server add --host 203.0.113.10 --user root --auth-method agent

Server health check & install

Test a connection before saving, check what a saved server has installed, then install or remove components. These routes identify the server by serverId in the body (not a URL param), and each handler runs its own per-server server:admin (or server:read) check.

POST /api/system/test-connection opens an ephemeral SSH connection from body credentials and returns { ok, message } — nothing is persisted. It requires the caller be an org owner/admin.

POST /api/system/check

Returns { components, ready, missing }.

POST /api/system/install

POST /api/system/remove mirrors install for a single removable component. POST /api/system/install/stream takes { serverId, components: string[], config? } and returns a Server-Sent Events stream (progress, log, complete, end); it returns 409 install_in_progress if a session is already running.

# One-shot install:
openship server install <serverId> --component docker

# Stream logs live (attaches to POST /api/system/install/stream):
openship server install <serverId> --component docker --component openresty --follow

GET /api/system/monitor/stream?serverId=<id> emits a stats event every few seconds with CPU %, memory, disk, uptime, and load average gathered over SSH — openship server monitor <serverId>.

Per-server rate limiting

Read or update the OpenResty request rate limit for a server. OpenResty on the target server is the source of truth; the API parses and rewrites its ratelimit.conf.

PATCH /api/system/servers/:id/rate-limit

openship server rate-limit <serverId> --rps 50 --burst 100

Port-forward tunnels

Desktop-only. Forward a remote server port to localhost on the operator's machine, VS Code style. Every handler additionally asserts desktop mode; on a non-desktop instance they refuse.

POST /api/system/servers/:id/tunnels

Start / stop / delete a saved tunnel with POST .../tunnels/:tunnelId/start, .../stop, and DELETE .../tunnels/:tunnelId. A started tunnel returns the actually-bound localPort and a http://localhost:<port> URL.

Browse the host filesystem

GET /api/system/browse?path=<dir> lists child directories of a path (defaults to the host's home directory), flagging which look like deployable projects. Used by the "deploy a local folder" picker.

openship system browse /srv/apps

Returns { path, directories: [{ name, path, isProject }] } — projects first, then alphabetical. Non-directory paths return 400, missing paths 404.

Team-mode migration

Move a single-user instance into team mode along one of three paths, or reverse it. All four routes require org admin/owner and refuse (409) unless teamMode === "single_user". See the cloud connect / migration guide.

Preflight and start (Path A — your own server) share a body:

POST /api/system/migration/start

• POST /api/system/migration/start-cloud — Path B, migrate to Openship Cloud. Body: { allowNonEmptyTarget?: boolean }.
• POST /api/system/migration/start-tunnel — Path C, expose via an edge tunnel. Body: { slug: string } (required).
• POST /api/system/migration/switch-back — reverse any of them. Body: { abandonRemote?: boolean }.

# Readiness check first, then migrate onto your server:
openship system migration preflight --server-id <id> --hostname app.example.com
openship system migration start --server-id <id> --hostname app.example.com

Whole-instance data transfer

Export or import the entire database — every organization's data. Both routes are owner-only (requireRole("owner") on top of the settings:admin tag), because the tag alone would also admit admins and members.

POST /api/system/data-transfer/export

POST /api/system/data-transfer/import

openship system data-transfer export --passphrase "$SECRET" --out instance.json
openship system data-transfer import --file instance.json --passphrase "$SECRET" --mode wipe