Migration

The Migration API brings workloads you deployed to a server by hand — Compose stacks and stray containers — under Openship management. It inspects a server's Docker over SSH, returns the stacks it can adopt, and then creates an Openship services project from the ones you pick. In the dashboard this is the migration wizard; there is no CLI equivalent.

Self-hosted only

This module is mounted only when your instance runs in self-hosted mode — adopting a deployment requires SSH into a server you manage, which Openship Cloud has no notion of. On a cloud instance these routes are not mounted and return 404.

Scan a server

Read-only. Enumerates the server's Docker — Compose stacks plus hand-run containers — reconciles them with any Compose files found on disk, and returns the discovered stack for the wizard to preview. Nothing on the server changes.

POST /api/migration/scan

Prop

Type

curl -X POST "$OPENSHIP_URL/api/migration/scan" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"srv_123"}'

On success the response is { "success": true, "stack": … }, where stack describes the discovered Compose stacks and containers that can be adopted.

Adopt discovered services

Creates an Openship services project from the services you selected. The server is re-discovered server-side (the server is the source of truth, not client-sent config), and existing named volumes are reused in place — this records the project only; deploy and cutover are separate steps.

POST /api/migration/adopt

Prop

Type

curl -X POST "$OPENSHIP_URL/api/migration/adopt" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"srv_123","projectName":"legacy-stack","serviceNames":["web","worker"]}'

On success the response is { "success": true, … } with the created project's details.

Run a reviewed migration

POST /api/migration/migrate starts the complete migration. Per-service options use the discovered container IDs as keys; legacy service-name keys remain accepted. routesByServiceName accepts an array of routes per service, preserving aliases, listen ports, path prefixes and exact matches. Environment values are saved in the service's production environment scope.

A hostname can contain only explicit paths, such as /api/ and an exact /health, without a service at /. Migration preserves that selection as a project-owned route: matching requests reach their selected services, and unmatched paths return 404. An exact / match does not become a catch-all. If an existing source catch-all is omitted, the run asks you to confirm the selected paths or cancel and review them before creating project records or changing source containers. Routing retries retain the previous complete table when any selected service has no live upstream.

When routes are selected, migration prepares the target edge before changing source containers. If another proxy must be replaced, the run waits for consent. Read pendingPrompt from GET /api/migration/migrations/:id (also included in the stream snapshot), then answer it with:

POST /api/migration/migrations/:id/respond
Content-Type: application/json

{"promptId":"<pendingPrompt.promptId>","action":"migrate"}

Use an action ID from the current prompt. An expired, already answered or invalid prompt returns 409. Answering requires write access to both migration servers. Cancelling keeps the original proxy and source containers intact. After attachment or deployment, Openship applies the owned routes and retries pending domain verification; unresolved routing failures remain visible on the run.

Errors

400 — missing or empty field

serverId is required on both routes; adopt additionally requires a non-empty projectName and at least one entry in serviceNames. The response body names the missing field.

404 — server not found

The serverId doesn't belong to your organization (or doesn't exist). List your servers with openship server list to get valid IDs. On a cloud instance the module isn't mounted at all, so every path here returns 404.

502 — scan or adopt failed

Openship couldn't reach or inspect the server's Docker (SSH unreachable, Docker not running, permission denied), or the adoption failed. The message includes the underlying reason. Confirm the server is online and its Docker is accessible, then retry.

Operations

Operation	SDK	REST API
List the active organization's migration-only SSH connections.	`migrations.listSources()` Remote client	`GET /api/migration/sources` `server:read`
Verify and save a public SSH source with encrypted credentials and a pinned host key. Does not enable external Cloud deployment destinations.	`migrations.createSource(input)` Remote client	`POST /api/migration/sources` `server:write`
Test a public SSH source without saving it and return its host fingerprint.	`migrations.testSource(input)` Remote client	`POST /api/migration/sources/test` `server:write`
Inspect a server's Docker and return the adoptable stack — read-only, changes nothing.	`migrations.scan(input)` Remote client	`POST /api/migration/scan` `server:write`
Reveal explicitly requested environment values for an authorized import.	`migrations.revealEnv(input)` Remote client	`POST /api/migration/reveal-env` `server:write`
Read Compose configuration from a repository for import.	`migrations.repoCompose(input)` Remote client	`POST /api/migration/repo-compose` `server:read`
Create an Openship project from the selected discovered services.	`migrations.adopt(input)` Remote client	`POST /api/migration/adopt` `server:write` · Self-hosted
Refresh an imported project from its source.	`migrations.reimport(input)` Remote client	`POST /api/migration/reimport` `server:write` · Self-hosted
Preview a migration plan.	`migrations.preview(input)` Remote client	`POST /api/migration/preview` `server:write`
Start a server migration from the reviewed plan.	`migrations.start(input)` Remote client	`POST /api/migration/migrate` `server:write`
Import a discovered project.	`migrations.moveProject(input)` Remote client	`POST /api/migration/project` `server:write`
List active server migration sessions.	`migrations.active(input)` Remote client	`GET /api/migration/active` `server:read`
List migration history.	`migrations.listRuns(input)` Remote client	`GET /api/migration/runs` `server:read`
Disconnect an idle migration source without deleting its external server or workloads.	`migrations.removeSource(id)` Remote client	`DELETE /api/migration/sources/:serverId` `server:write`
Read migration progress and state.	`migrations.get(id)` Remote client	`GET /api/migration/migrations/:id` `server:read`
Switch traffic to the prepared migration target.	`migrations.cutover(id, input)` Remote client	`POST /api/migration/migrations/:id/cutover` `server:write`
Request cancellation of a migration.	`migrations.cancel(id)` Remote client	`POST /api/migration/migrations/:id/cancel` `server:write`
Answer a pending migration prompt, including edge takeover consent.	`migrations.respond(id, input)` Remote client	`POST /api/migration/migrations/:id/respond` `server:write`
Resume an interrupted migration.	`migrations.resume(id, input)` Remote client	`POST /api/migration/migrations/:id/resume` `server:write`
Clean up resources created on the migration target.	`migrations.cleanupTarget(id)` Remote client	`POST /api/migration/migrations/:id/cleanup-target` `server:write`
Delete an eligible migration record.	`migrations.remove(id)` Remote client	`DELETE /api/migration/migrations/:id` `server:write`
Stream migration progress.	`migrations.events(id, options?)` Remote client	`GET /api/migration/migrations/:id/stream` `server:read`
Stream server-discovery progress.	`migrations.scanEvents(input, options?)` Remote client	`GET /api/migration/scan/stream` `server:write`

Scan a server

Adopt discovered services

Run a reviewed migration

Errors

Operations

On this page