Data transfer

Instance location

Use Settings → Instance → Instance location to move an entire controller between Desktop and a server. /api/system/instance/* uses one durable handoff in both directions: pause and drain the source, verify the encrypted snapshot, retire the source, then activate the receiver. Resume uses the same saved snapshot; it never reactivates stale source data. These operations require the instance administrator, while pairing a Desktop grants only its signed-in user's existing permissions.

POST /api/system/instance/provision accepts { serverId, access: "desktop" | "browser", domain: { kind: "custom" | "free", hostname }, confirmed: true }. Optional mapping contains sourceServerId and connectionServerId for a verified SSH connection to the source host. The normal deployment engine installs the compatible API image with persistent storage; browser also installs the dashboard. Server preparation completes before the source is paused.

See Move your Openship instance for prerequisites, credential handling, API addresses, cancellation and recovery. Archive import below is for data recovery and does not retire another controller.

Earlier team-mode migration endpoints

These routes remain for clients using the earlier team-mode workflow and require an instance administrator. New instance moves use the handoff above. Forward requests require teamMode === "single_user"; switch-back requires an earlier team mode.

POST /api/system/migration/start, client.instance.migrateToServer() and openship system migration start remain disabled with 501 SERVER_MIGRATION_UNAVAILABLE. They do not start the new handoff or copy any data. Use Settings → Instance → Instance location to review the destination and confirm a move.

The earlier preflight and disabled start endpoint share a body:

POST /api/system/migration/start

• POST /api/system/migration/start-cloud — Path B, migrate to Openship Cloud. Body: { allowNonEmptyTarget?: boolean }.
• POST /api/system/migration/start-tunnel — Path C, expose via an edge tunnel. Body: { slug: string } (required).
• POST /api/system/migration/switch-back — reverse any of them. Body: { abandonRemote?: boolean }.

Instance and project data transfer

Export the entire instance or a dependency-complete selection of projects and environments. These routes require instance administrator access (requireInstanceAdmin() plus a handler-level check). A workspace owner role alone does not grant access to instance credentials.

POST /api/system/data-transfer/export

POST /api/system/data-transfer/import

Project imports remap ownership to the active request workspace. They omit instance accounts/settings, reuse matching server connections, and skip existing projects by default. Overwrite replaces the selected projects, including removing destination-only records in the selected categories and clearing credentials that were cleared at the source. Categories excluded from the import are retained. Shared dependencies are kept unless overwriteDependencies is explicitly enabled. Source local hosts require an explicit serverMappings entry (local for a project without a server row). Cloud projects require the same connected cloud account. A project archive cannot be used with wipe.

Use the chunk-upload endpoints for large files. After uploading, POST { selection } to the session's preview endpoint. It returns projects, servers, availableServers, row counts, rowsRemoved, warnings, and blockers without consuming the upload. POST { mode, passphrase, selection } to /api/system/data-transfer/import/session/:sessionId/finalize/stream to apply. Validation is repeated inside the import transaction. A failed review or password attempt retains the uploaded chunks.

New instance and project exports use envelope version 4 and contain unencrypted JSON, including environment values, SSH keys, tokens, deployment snapshots, and inline Compose configuration. No password is required; a passphrase supplied by an older export client is ignored. Set includeSecrets: false explicitly to omit credentials. Imports still accept versions 1–3, including legacy password-protected files, and encrypt restored credentials with the destination instance's key. New archives with tables or fields the destination cannot store are rejected before any data changes; update the destination instead of losing those fields. Volume data, source folders, and host TLS files remain on their server.

In project imports, loopback server connections require explicit mapping. Backup policies that point at source-local storage or a changed backup host are disabled until the operator verifies the destination storage. Direct transfer supports whole-instance exports; project selections use the file review and import endpoints.

SDK and CLI

Remote client.instance.previewExport, exportData and importData use the existing instance-admin handlers. An organization-bound or scoped credential cannot export other workspaces by omitting its organization. The SDK does not retry an import whose response is lost.

const preview = await client.instance.previewExport();
const archive = await client.instance.exportData();
// Store privately: current exports include plaintext credentials.
const result = await destination.instance.importData({ file: archive, mode: "merge" });

Import requires an explicit mode in the SDK. selection supports project IDs, conflict choices, server mappings and included resources. Database rows and secret envelopes are opaque to the client; the controller owns archive validation and restoration.

Use openship system data-transfer for JSON exports/imports. Direct-transfer pairing and chunk upload remain the dashboard's recovery protocol. Legacy instance team-mode migration calls retain the API's capability restrictions; migrations is the separate workload move/copy API.

HTTP endpoints

Instance location