User settings

User settings apply to the authenticated user. There is no settings ID to select. References to servers are checked against the current organization and access grants; an inaccessible default server is hidden. Use installation settings for instance-wide configuration.

Personal appearance

GET /api/settings/appearance returns { "appearance": null } for an unset preference, or an appearance library. PUT /api/settings/appearance accepts the same wrapper. Pass null to clear the saved appearance. Both endpoints operate exclusively on the authenticated user and retain the existing settings permissions; there is no user ID selector. Other settings and credentials are preserved.

const { appearance } = await ship.settings.getAppearance();
await ship.settings.setAppearance({ appearance });
// Clear the saved personal appearance.
await ship.settings.setAppearance({ appearance: null });

A library has version: 1, an active preset (light, dim, dark, system) or custom theme ID, and themes. Each theme contains version: 1, id, name, base, tokens, typography and optional embedded fonts. Missing token overrides inherit the base theme. Token references may use registered variables of the same type and must not form cycles. Unknown tokens, executable CSS, remote font references, unsupported versions and excessive payloads are rejected.

{
  "version": 1,
  "active": "ocean",
  "themes": [{
    "version": 1,
    "id": "ocean",
    "name": "Ocean",
    "base": "dim",
    "tokens": { "--th-bg-page": "#142333", "--radius": "12px" },
    "typography": {
      "sans": "system", "mono": "systemMono",
      "size": 16, "monoSize": 13, "lineHeight": 1.5, "weight": 400
    },
    "fonts": []
  }]
}

The same library JSON can be exported, imported and reset from the CLI. set also accepts a single theme exported by the dashboard and merges it by ID into the current library.

openship --json settings appearance get > appearance.json
openship settings appearance set appearance.json
openship settings appearance reset

Font choices are gellix, system, serif or custom for the interface and mono, systemMono or custom for monospace. A custom choice requires a matching font asset with role, name and base64 WOFF2 data. Each font is limited to 256 KiB; the full library is limited to 1 MiB and 32 themes. All clients validate the same schema. Existing instances receive a nullable column through an additive migration; older users retain their default appearance.

Read preferences

const settings = await ship.settings.get();
console.log(settings.buildMode, settings.defaultDeployTarget);

curl "$OPENSHIP_URL/api/settings" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

The result includes build and route strategy, deploy defaults, transfer preferences, and Git options. cloneToken reports hasToken, setAt, and asDefault; it never contains the token value.

Set build and routing defaults

await ship.settings.setBuildMode({ buildMode: "server" });

curl -X PATCH "$OPENSHIP_URL/api/settings/build-mode" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"buildMode":"server"}'

update({ buildMode }) also creates or updates the settings row; it maps to PUT /api/settings. Route strategy controls how the edge reaches an application. Provider constraints still apply; for example, container-IP routing is unsupported on Docker Desktop.

Set a deployment destination

await ship.settings.setDeployDefaults({
  defaultDeployTarget: "server",
  defaultServerId: "srv_123",
});

curl -X PATCH "$OPENSHIP_URL/api/settings/deploy-defaults" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"defaultDeployTarget":"server","defaultServerId":"srv_123"}'

defaultDeployTarget is server, cloud, or null. A server target requires an accessible defaultServerId. Other targets clear that server reference. Pass null to clear a default; omit a field to retain its value. local is derived from the project at deployment time and is not a selectable default destination.

Manage clone credentials

await ship.settings.setCloneCredentials({ token: "ghp_example", asDefault: true });

curl -X PATCH "$OPENSHIP_URL/api/settings/clone-credentials" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"token":"ghp_example","asDefault":true}'

Use a real Git token from your secret store. The token is encrypted and never returned. Omit token to leave it unchanged; send null or an empty string to clear it. asDefault controls whether it is used automatically for clones.

setCloneStrategy({ preference }) accepts prompt, local, or remote-with-token. setGitForwarding({ enabled }) controls forwarding the local Git identity to an authorized build server for the clone. See Git authentication.

Set transfer preferences

await ship.settings.setTransferPreferences({
  transferMode: "auto",
  transferCompression: "zstd",
});

curl -X PATCH "$OPENSHIP_URL/api/settings/transfer" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transferMode":"auto","transferCompression":"zstd"}'

Both fields are optional. transferMode accepts auto, stream, direct, or rsync; transferCompression accepts auto, zstd, gzip, or none. These are defaults for migration volume transfers; target capabilities determine the effective transport.

Operations