Installation settings
Read and change self-hosted installation settings and setup.
Installation settings control a self-hosted Openship instance. Resource operations below use the shared SDK/HTTP interface where available; onboarding, recovery, and remaining setup endpoints are HTTP-only.
See Servers for hosts and component installation, Edge administration for existing sites, and Data transfer for imports, exports, and team-mode migration.
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/onboardingProp
Type
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.
const result = await ship.system.updateSettings({
defaultBuildMode: "docker",
});
console.log(result);curl -X PATCH "$OPENSHIP_URL/api/system/settings" \
-H "Authorization: Bearer $OPENSHIP_TOKEN" \
-H "Content-Type: application/json" \
-d '{"defaultBuildMode":"docker"}'Prop
Type
Zero-auth is double-gated
Setting authMode: "none" on anything other than a desktop deployment means anyone who can reach the API acts
as admin. The operator must both start the process with OPENSHIP_ALLOW_ZERO_AUTH=true (else 403) and
send confirm: "I-understand-no-auth" in the body (else 400).
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-authProp
Type
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.
Returns { path, directories: [{ name, path, isProject }] } — projects first, then alphabetical. Non-directory
paths return 400, missing paths 404.
Operations
Resource methods
| Operation | SDK | REST API |
|---|---|---|
| Browse an authorized host filesystem location. | system.browse(input?) | GET /api/system/browsesettings:read · Self-hosted |
| Read database and installation health. | system.health() | GET /api/system/diagnosticssettings:read · Self-hosted |
| Read instance settings. | system.getSettings() | GET /api/system/settingssettings:read · Self-hosted |
| Change instance settings. | system.updateSettings(input) | PATCH /api/system/settingssettings:write · Self-hosted |
| Read SMTP settings with secrets masked. | system.getEmailSettings() | GET /api/system/settings/emailsettings:read · Self-hosted |
| Configure SMTP delivery for the installation. | system.updateEmailSettings(input) | PUT /api/system/settings/emailsettings:write · Self-hosted |
| Send a test message using the configured SMTP settings. | system.sendTestEmail(input) | POST /api/system/settings/email/testsettings:write · Self-hosted |
| Reset supported instance settings. | system.resetSettings() | DELETE /api/system/settingssettings:admin · Self-hosted |
HTTP endpoints
| Operation | SDK | REST API |
|---|---|---|
| First-run check — is any server configured yet? | instance.onboardingStatus()Remote client | GET /api/system/onboardingHandler authentication · Self-hosted |
| First-run setup; persists settings and creates the first server. Returns 403 once configured. | instance.configureOnboarding(input)Remote client | POST /api/system/onboardingHandler authentication · Self-hosted |
| Promote a zero-auth instance to email/password login. | instance.upgradeToAuth(input)Remote client | POST /api/system/upgrade-to-authHandler authentication · Self-hosted |
| Create the initial administrator during authorized bootstrap. | HTTP only | POST /api/system/bootstrap-adminInternal operator · Self-hosted |
| Exchange the private installation credential for a temporary local CLI admin session; requires X-Internal-Token and refuses Cloud/browser callers. | HTTP only | POST /api/system/cli-sessionInternal operator · Self-hosted |
| Begin the installation's Cloud account connection. | HTTP only | POST /api/system/cloud-connectInternal operator · Self-hosted |
| Read the installation's Cloud connection status. | HTTP only | GET /api/system/cloud-statusInternal operator · Self-hosted |
| Read installation health. | HTTP only | GET /api/system/healthInternal operator · Self-hosted |
| Create an account from an eligible self-hosted invitation. | HTTP only | POST /api/system/invite-signupHandler authentication · Self-hosted |
| Test a connection during initial onboarding. | HTTP only | POST /api/system/onboarding/test-connectionHandler authentication · Self-hosted |
| Reset the administrator password through the local recovery boundary. | HTTP only | POST /api/system/reset-admin-passwordInternal operator · Self-hosted |
| Register the Openship installation as a managed application. | HTTP only | POST /api/system/self-registerInternal operator · Self-hosted |
| Stream installation registration progress. | HTTP only | GET /api/system/self-register/streamInternal operator · Self-hosted |
| Read instance config for the desktop app. | HTTP only | GET /api/system/setupInternal operator · Self-hosted |
| Push instance config from the desktop app. | HTTP only | POST /api/system/setupInternal operator · Self-hosted |