# Settings
URL: https://openship.io/docs/dashboard/settings.md

The Settings screen — GitHub connection, deploy defaults, tokens, MCP, team, notifications, audit log, cloud, and instance controls, one tab at a time.

Settings is where you configure everything that isn't tied to a single project: how you connect to
GitHub, where new deployments land by default, the tokens and AI clients that talk to your API, who's on
your team, and how this install itself is run and updated.

Open it from the dashboard's left navigation (the **Settings** item), or go straight to **`/settings`**. The
screen has a tab nav on the right (a horizontal strip on mobile) that switches between sections. Each tab
is also directly linkable with a `?tab=` query — e.g. `/settings?tab=team` — so you can bookmark or share the
exact place you mean.

<Callout title="Some tabs and sections only appear in some setups" type="info">
The **Cloud** tab is hidden on the managed Openship Cloud — it shows on self-hosted and desktop installs
only. The **Audit log** tab is always listed, but the log itself loads only for **admins and owners**
(members get an empty feed). Within **Instance**, the **Updates** and **data export/import** sections appear
only where they make sense — a self-hosted or desktop install. If something described here isn't where you
expect, that's why.
</Callout>

## General

The home tab contains language, interface preferences, and self-hosted build preferences.

## Appearance

Open **Settings → General** to use the existing Light, Dim, Dark and System switches; preset changes apply immediately. Choose **Customize** to open the editor inline (`/settings?tab=general&view=appearance`) while General stays selected, and **Back to General** to return. Built-in presets remain unchanged; editing one in the editor creates a personal copy. System follows the device, using Dim for a dark Desktop environment and Dark on the web.

The editor groups all registered design tokens into surfaces, text, controls, status, effects and scales. Search by token name, edit its color or value, and reset individual overrides. Typography controls the interface and monospace fonts, size, weight and line height. Uploaded WOFF2 files are embedded in theme JSON, so custom fonts travel with an export.

Edits preview immediately across the dashboard, including open terminals, without restarting their sessions. **Save** persists the theme to the authenticated user on the connected instance. **Discard** restores the saved appearance. The bottom controls retain a readable base palette; **Reset** previews the default Light appearance and clears the personal library only when you save. Navigating away discards the unsaved preview; a full reload warns about unsaved changes.

Import a JSON file, paste JSON, or load a public HTTPS JSON URL that permits browser CORS requests. URL imports omit credentials and are fetched once, rather than continuously following remote changes. A single-theme import replaces a matching theme ID or adds it to the library; a library import replaces the draft library. Nothing is persisted until Save.

**Download theme** exports the active theme; **Download all** exports the personal library. The versioned format supports up to 32 themes, two WOFF2 fonts per theme (256 KiB each), and 1 MiB total. Unsupported tokens, invalid values, cyclic token references and incompatible versions are rejected. These preferences affect this account's dashboard, not deployed applications or other members.

The [appearance API and CLI](/docs/api/settings#personal-appearance) use the same format. Saving requires a version of the API that supports the appearance endpoints; a failed settings read stays visible and blocks saving until a retry succeeds.

## Git

The **Git** tab owns outbound source-control access. On self-hosted instances, workspace owners first see
**Self-hosted GitHub Apps**, where they can create Apps with GitHub's manifest flow, register an existing
GitHub or GitHub Enterprise App, manage installations, rotate credentials, verify health, and choose a
default source. See [Self-hosted GitHub Apps](/docs/guides/self-hosted-github-app).

The **GitHub** connection card underneath manages the separate local `gh`/device/token identity and the
managed Openship App fallback. When workspace-owned Apps exist, their install, manage, and delete controls
remain exclusively in the source cards, so **Disconnect** cannot misleadingly remove only an unrelated
OAuth account.

The **GitHub clone credentials** card stores a personal token fallback for private clones. On desktop it can
also forward the local Git identity to remote build servers.

See [Deploy from GitHub](/docs/guides/deploy-from-github) for the full walk-through.

### Deploy Defaults

*(Self-hosted and desktop only.)* Pick where new deployments should land by default — **This Machine**
(local Docker/runtime), **My Server** (a configured SSH server), or **Openship Cloud**. The chosen target
is preselected on the deploy picker; you can still override it per deployment, or **Clear default
(ask every time)**.

### Build Preferences

*(Self-hosted and desktop only.)* Choose the default build strategy for new deployments: **Auto** (smart per-framework),
**Server** (build on the remote), or **Local** (build on this machine). Per-project overrides live in the
project's own settings.

### Language

Choose the language used across the dashboard. The change applies immediately.

## Tokens

Credentials that let other things act on your behalf. GitHub clone credentials live in **Git**; this tab
contains API access tokens.

### Personal Access Tokens

Bearer tokens for the API, CLI, and MCP clients. Each token **acts as you** — it carries your role's
permissions unless you narrow it. When creating one you can:

- Name it (e.g. "MCP client").
- Set an expiry: **No expiry**, **30 days**, **90 days**, or **1 year**.
- Mark it **Read-only** to block all writes.
- **Limit to specific resources** to scope it below your own role — ideal for a narrow MCP token.

Press **Create token**, then copy it immediately — this is the only time the value is shown. Existing
tokens are listed with **read-only** / **scoped** badges and a **Revoke** button.

<Callout title="Copy the token now" type="warn">
A new token's value is displayed once, at creation. If you lose it you can't recover it — revoke it and
make a new one.
</Callout>

## MCP

Connect AI agents (Claude, Cursor, VS Code, Windsurf, …) to your Openship API over the Model Context
Protocol. The tab shows this instance's **Endpoint** — a Streamable-HTTP JSON-RPC URL, typically
`https://<your-host>/api/mcp` — plus per-client install snippets.

Two ways to authenticate:

- **OAuth** — the client opens a browser to authorize; you approve access and pick what it can reach.
  Nothing to copy. Openship is a standards-compliant OAuth 2.1 MCP server.
- **Static token** — for clients without OAuth, drop a fixed, scoped token (created in the **Tokens** tab)
  into the client config.

**Connected clients** lists every authorized client with its access level (read-only / full control) and
resource scope, each with a disconnect action.

## Team

Who can reach this organization's projects, deployments, and servers. See
[Teams & members](/docs/guides/teams-members) for the full workflow.

- **Active members** — everyone with access, their role, and a **Remove member** action.
- **Pending invitations** — invites you've sent that haven't been accepted yet.
- **Invite member** — send through the instance's configured email service or create a link to copy.
  Pick a role: **Member** (read + write to everything), **Admin**
  (Member plus manage members and billing), or **Restricted** (no default access — you choose exactly which
  resources to unlock). Restricted invites open a resource picker.

Both delivery choices use the same email-bound invitation. The link is shown after creation
and stays available in Pending invitations, where it can also be revoked. From a connected
Desktop, copied links point to the remote instance. Recipients use their own accounts and
enter the invited organization after accepting.
Self-hosted recipients can choose **Open in Desktop** on the invitation page, confirm the
instance, and use the same sign-in and acceptance flow in the app. The page also provides
a copyable invitation URL for manual connection. Joining never grants more than the offered
role and resource access; opening the link alone does not join a workspace.

If you're on a personal workspace, this tab also offers **Create team** to spin up a separate, isolated
team organization.

## Notifications

Decide what you get told about and where it goes.

- **Delivery channels** — where notifications are sent. Add an **Email**, **Webhook**, **Slack**, **Discord**,
  or **Microsoft Teams** channel; the **in-app** dashboard bell is always on. Outbound channels are skipped
  until verified — send a test to verify one.
- **What to be notified about** — a grid of events × channels; each cell you switch on is one subscription.
  Events span the whole platform: deploys (succeeded / failed / cancelled), backups (succeeded / failed /
  restore completed), scheduled jobs, domain expiry + verification, team changes, and billing / quota alerts.
- **Organization defaults** — the subscriptions applied when a new member joins. Members can override their
  own per-channel.

## Audit log

*(Admin or owner only.)* A running feed of every change in the organization — who did it, what changed, and
when. Search across events, actors, and resources, filter by event type, and expand any entry to see the
**before**/**after** of the change plus actor details (name, email, IP, user agent).

## Cloud

*(Self-hosted and desktop only.)* Link this instance to Openship Cloud to unlock cloud deployments, managed SSL, and the
global CDN. Press **Connect to Openship Cloud**, sign in, and review the account and organization
before authorizing. The consent screen has **Switch** actions for both. Once connected the card shows
your cloud account with a **Disconnect** option. This connection also enables migrating your instance
to Cloud — see [Connect to Cloud & migrate](/docs/guides/cloud-connect-migration).

## Instance

Everything about *this install*. Two cards at the top show the instance type (**Desktop**, **Openship
Cloud**, or **Self-Hosted**) with its deploy mode and version, and the auth mode (**Zero Auth**, **Cloud
Auth**, or **Local Auth**) with the signed-in user. On a zero-auth desktop install a **Change** link lets
you add an email + password login without losing any projects or history.

### Updates

*(Self-hosted and desktop.)* Shows your current version and whether a newer release is available, with
**Check now** / **Update now**, a toggle for **Automatic updates** (off by default), and a toggle for
**Update & security notifications**. Openship only ever *pulls* this data from the public GitHub releases —
nothing can push updates to your install. More in [Updating Openship](/docs/guides/updating).

### Instance location

Move between Desktop and a connected or managed server from one card. Choose API-only or
API + dashboard, or connect Desktop to an existing remote instance without copying its data.
The move preserves workspaces and credentials, verifies the receiver before cutover, and
keeps the source inactive afterward. **Move back to Desktop** transfers the latest remote
state. [Read the instance move guide](/docs/guides/migrate-control-plane).

The card shows the current location and its main action. The **More instance options** menu
contains existing-instance connections, move codes and returning to a previous server.
An active server offers **Connect a Desktop** directly; a retired server offers
**Move an instance here**.

### Backup & recovery

*(Self-hosted and desktop, instance administrators only.)* **Export instance or projects** downloads a
portable JSON file. Choose the entire instance, or select projects and individual environments in bulk.
The same project export is available in **Project → Advanced → Export project**, with all of that
project's environments selected by default.

Project exports include deployments, service configuration, environment variables, overview analytics, linked apps, routing,
backup policies and destinations, and Git credentials. Related self-hosted servers are recommended and
included by default. You can choose which configuration and history to include. Both instance and project
exports include environment values, private keys, deployment snapshots, inline Compose configuration,
and credentials as **unencrypted JSON**, with no export password. Credentials and all history are selected
by default. Keep using the listed servers, or connect the destination to the same Openship Cloud account.

**Import data** uploads the file once and previews its contents. An instance archive starts in **Replace
the entire destination instance** mode, with confirmation before applying. It restores the source
projects, users, servers, credentials, settings and included history over the destination's older records.
For project archives, select the environments to import into
the current workspace, review conflicts, and map source servers to destination servers. Matching
self-hosted servers are reused with their existing connection credentials. Existing projects are skipped
by default; **Overwrite matching project records** replaces the selected projects, removes destination-only
records in the selected categories, and respects credentials cleared at the source. The review shows
how many records will be removed. Excluded categories and other projects are retained. Individual projects
can override that choice. Shared integrations and backup
destinations are reused unless you explicitly choose to overwrite shared settings.

Cloud projects require the destination workspace to be connected to the **same Openship Cloud account**.
Cloud servers cannot be transferred between accounts. For project imports, a source control-plane host needs an
explicit target mapping. Projects mapped to a different host arrive disabled with live container
references cleared, ready for a migration or redeployment.

In project imports, loopback SSH addresses also require explicit mapping. Backup schedules that use a source-local folder
or a different backup host arrive disabled; reconnect the storage, verify it, and then enable the schedules.

Exports contain control-plane metadata. Volume contents, database payloads, source folders, and host TLS
files stay on their server. Keep using that server, or move the runtime data with migration/backup
restore. Reconnect local source folders and update Git/webhook callback URLs when the control-plane
address changes. The import result keeps these follow-up notes available.

Use **Instance location** for a live move of the whole control plane. Use an export file for
project selections so you can review conflicts and server mappings before applying them.

<Callout title="Import can wipe this instance" type="warn">
An instance archive offers merge or full replacement. Replacement erases
all destination data and signs you out. A project archive can never wipe an instance. Only an
**instance administrator** can export or import. Older password-protected archives still require their
original password. If an older file contains no credentials, export again from the updated source;
an import cannot recover values absent from the file. Update the destination before importing a newer
archive so all its fields can be restored.
</Callout>