Data transfer

Team-mode migration

Move a single-user instance into team mode along one of three paths, or reverse it. All four routes require org admin/owner and refuse (409) unless teamMode === "single_user". See the cloud connect / migration guide.

Preflight and start (Path A — your own server) share a body:

POST /api/system/migration/start

• POST /api/system/migration/start-cloud — Path B, migrate to GramCode 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.

Operations

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.