Settings

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.

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 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.

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 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.

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 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.

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.

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.

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.