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.

Read preferences

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

curl "$GRAMCODE_URL/api/settings" \
  -H "Authorization: Bearer $GRAMCODE_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 "$GRAMCODE_URL/api/settings/build-mode" \
  -H "Authorization: Bearer $GRAMCODE_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 "$GRAMCODE_URL/api/settings/deploy-defaults" \
  -H "Authorization: Bearer $GRAMCODE_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 "$GRAMCODE_URL/api/settings/clone-credentials" \
  -H "Authorization: Bearer $GRAMCODE_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 "$GRAMCODE_URL/api/settings/transfer" \
  -H "Authorization: Bearer $GRAMCODE_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