Installation settings

Installation settings control a self-hosted Synq 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/onboarding

The POST /api/system/setup route accepts the same body but is reserved for the local host process of desktop app versions up to 1.2.5 (the current app doesn't call it) 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 "$SYNQ_URL/api/system/settings" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"defaultBuildMode":"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

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

HTTP endpoints