curl

curl -sS -X POST "https://gateway.orbit/api/v1/instances/12/transfer" \
  --cacert /path/to/orbit-root-ca.pem \
  -H 'Accept: application/json' \
  -H 'X-Orbit-Request-Id: 9d6b1e5c-4a3f-4a1b-9f0e-6d2c3f5a7b81' \
  -H 'Content-Type: application/json' \
  -d '{"node_id": 7, "name": "default", "sqlite_source_path": "/home/acme/database/database.sqlite"}'

{
  "data": {
    "id": 123,
    "project_id": 123,
    "node_id": 123,
    "project": {
      "id": 123,
      "name": "<string>",
      "slug": "<string>",
      "type": "monorepo"
    },
    "node": {
      "id": 123,
      "name": "<string>"
    },
    "name": "<string>",
    "source_layout": "<string>",
    "checkout_path": "<string>",
    "production_user": "<string>",
    "production_home": "<string>",
    "root": "<string>",
    "effective_root": "<string>",
    "selected_branch": "<string>",
    "branch_override": "<string>",
    "starting_commit": "<string>",
    "detached": true,
    "status": "<string>",
    "route": {
      "id": 123,
      "kind": "<string>",
      "project_id": 123,
      "node_id": 123,
      "cluster_id": 123,
      "generation_basis_node_id": 123,
      "domain": "<string>",
      "provenance": "<string>",
      "publication": "<string>",
      "status": "<string>",
      "failed_step": "<string>",
      "error_code": "<string>",
      "replaces_route_id": 123,
      "replaced_by_route_id": 123,
      "replacement_step": "<string>",
      "target_set_step": "<string>",
      "target": {
        "id": 123,
        "instance_id": 123,
        "position": 123
      },
      "targets": [
        {
          "id": 123,
          "instance_id": 123,
          "position": 123
        }
      ],
      "process_id": 123,
      "upstream": "<string>",
      "analytics_instance_id": 123,
      "web_root": "<string>"
    },
    "domain": "<string>",
    "url": "<string>",
    "removal": {
      "operation_id": "<string>",
      "id": 123,
      "name": "<string>",
      "force": true,
      "status": "<string>",
      "current_step": "<string>",
      "total": 123,
      "completed": 123,
      "remaining": 123,
      "failed_step": "<string>",
      "error_code": "<string>"
    },
    "transfer": {
      "operation_id": "<string>",
      "id": 123,
      "source_node_id": 123,
      "destination_node_id": 123,
      "destination_name": "<string>",
      "destination_path": "<string>",
      "destination_domain": "<string>",
      "sqlite_selected": true,
      "status": "<string>",
      "current_step": "<string>",
      "cutover_completed": true,
      "cleanup_completed": true,
      "failed_step": "<string>",
      "error_code": "<string>",
      "recovery_evidence": {}
    },
    "deploy_steps": [
      {
        "name": "<string>",
        "phase": "<string>",
        "command": "<string>",
        "timeout_seconds": 123
      }
    ],
    "vite_port": 123,
    "ssr_port": 123,
    "seed_path": "<string>",
    "seed_commit": "<string>",
    "annotator_port": 123,
    "annotator_url": "<string>",
    "routes": [
      {
        "id": 123,
        "kind": "<string>",
        "project_id": 123,
        "node_id": 123,
        "cluster_id": 123,
        "generation_basis_node_id": 123,
        "domain": "<string>",
        "provenance": "<string>",
        "publication": "<string>",
        "status": "<string>",
        "failed_step": "<string>",
        "error_code": "<string>",
        "replaces_route_id": 123,
        "replaced_by_route_id": 123,
        "replacement_step": "<string>",
        "target_set_step": "<string>",
        "target": {
          "id": 123,
          "instance_id": 123,
          "position": 123
        },
        "targets": [
          {
            "id": 123,
            "instance_id": 123,
            "position": 123
          }
        ],
        "process_id": 123,
        "upstream": "<string>",
        "analytics_instance_id": 123,
        "web_root": "<string>"
      }
    ]
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "data": {
    "id": 123,
    "project_id": 123,
    "node_id": 123,
    "project": {
      "id": 123,
      "name": "<string>",
      "slug": "<string>",
      "type": "monorepo"
    },
    "node": {
      "id": 123,
      "name": "<string>"
    },
    "name": "<string>",
    "source_layout": "<string>",
    "checkout_path": "<string>",
    "production_user": "<string>",
    "production_home": "<string>",
    "root": "<string>",
    "effective_root": "<string>",
    "selected_branch": "<string>",
    "branch_override": "<string>",
    "starting_commit": "<string>",
    "detached": true,
    "status": "<string>",
    "route": {
      "id": 123,
      "kind": "<string>",
      "project_id": 123,
      "node_id": 123,
      "cluster_id": 123,
      "generation_basis_node_id": 123,
      "domain": "<string>",
      "provenance": "<string>",
      "publication": "<string>",
      "status": "<string>",
      "failed_step": "<string>",
      "error_code": "<string>",
      "replaces_route_id": 123,
      "replaced_by_route_id": 123,
      "replacement_step": "<string>",
      "target_set_step": "<string>",
      "target": {
        "id": 123,
        "instance_id": 123,
        "position": 123
      },
      "targets": [
        {
          "id": 123,
          "instance_id": 123,
          "position": 123
        }
      ],
      "process_id": 123,
      "upstream": "<string>",
      "analytics_instance_id": 123,
      "web_root": "<string>"
    },
    "domain": "<string>",
    "url": "<string>",
    "removal": {
      "operation_id": "<string>",
      "id": 123,
      "name": "<string>",
      "force": true,
      "status": "<string>",
      "current_step": "<string>",
      "total": 123,
      "completed": 123,
      "remaining": 123,
      "failed_step": "<string>",
      "error_code": "<string>"
    },
    "transfer": {
      "operation_id": "<string>",
      "id": 123,
      "source_node_id": 123,
      "destination_node_id": 123,
      "destination_name": "<string>",
      "destination_path": "<string>",
      "destination_domain": "<string>",
      "sqlite_selected": true,
      "status": "<string>",
      "current_step": "<string>",
      "cutover_completed": true,
      "cleanup_completed": true,
      "failed_step": "<string>",
      "error_code": "<string>",
      "recovery_evidence": {}
    },
    "deploy_steps": [
      {
        "name": "<string>",
        "phase": "<string>",
        "command": "<string>",
        "timeout_seconds": 123
      }
    ],
    "vite_port": 123,
    "ssr_port": 123,
    "seed_path": "<string>",
    "seed_commit": "<string>",
    "annotator_port": 123,
    "annotator_url": "<string>",
    "routes": [
      {
        "id": 123,
        "kind": "<string>",
        "project_id": 123,
        "node_id": 123,
        "cluster_id": 123,
        "generation_basis_node_id": 123,
        "domain": "<string>",
        "provenance": "<string>",
        "publication": "<string>",
        "status": "<string>",
        "failed_step": "<string>",
        "error_code": "<string>",
        "replaces_route_id": 123,
        "replaced_by_route_id": 123,
        "replacement_step": "<string>",
        "target_set_step": "<string>",
        "target": {
          "id": 123,
          "instance_id": 123,
          "position": 123
        },
        "targets": [
          {
            "id": 123,
            "instance_id": 123,
            "position": 123
          }
        ],
        "process_id": 123,
        "upstream": "<string>",
        "analytics_instance_id": 123,
        "web_root": "<string>"
      }
    ]
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Instances

Transfer an Instance

Transfer a development Instance to another app-dev Node.

Transfer moves one active development Instance to a distinct active app-dev Node in an active Cluster. The destination may be in the same Cluster or another Cluster.

Orbit stops source processes for the downtime window, copies the source checkout or worktree into an independent destination checkout, optionally copies one selected SQLite snapshot, rebuilds destination environment values, moves or replaces the Route, and deletes the old managed placement. Production, standalone, and same-Node transfers are refused.

Use —name when the destination path or generated domain must change. —json disables prompts and requires —force for transfer consent.

POST

api

instances

{instance}

transfer

curl

curl -sS -X POST "https://gateway.orbit/api/v1/instances/12/transfer" \
  --cacert /path/to/orbit-root-ca.pem \
  -H 'Accept: application/json' \
  -H 'X-Orbit-Request-Id: 9d6b1e5c-4a3f-4a1b-9f0e-6d2c3f5a7b81' \
  -H 'Content-Type: application/json' \
  -d '{"node_id": 7, "name": "default", "sqlite_source_path": "/home/acme/database/database.sqlite"}'

{
  "data": {
    "id": 123,
    "project_id": 123,
    "node_id": 123,
    "project": {
      "id": 123,
      "name": "<string>",
      "slug": "<string>",
      "type": "monorepo"
    },
    "node": {
      "id": 123,
      "name": "<string>"
    },
    "name": "<string>",
    "source_layout": "<string>",
    "checkout_path": "<string>",
    "production_user": "<string>",
    "production_home": "<string>",
    "root": "<string>",
    "effective_root": "<string>",
    "selected_branch": "<string>",
    "branch_override": "<string>",
    "starting_commit": "<string>",
    "detached": true,
    "status": "<string>",
    "route": {
      "id": 123,
      "kind": "<string>",
      "project_id": 123,
      "node_id": 123,
      "cluster_id": 123,
      "generation_basis_node_id": 123,
      "domain": "<string>",
      "provenance": "<string>",
      "publication": "<string>",
      "status": "<string>",
      "failed_step": "<string>",
      "error_code": "<string>",
      "replaces_route_id": 123,
      "replaced_by_route_id": 123,
      "replacement_step": "<string>",
      "target_set_step": "<string>",
      "target": {
        "id": 123,
        "instance_id": 123,
        "position": 123
      },
      "targets": [
        {
          "id": 123,
          "instance_id": 123,
          "position": 123
        }
      ],
      "process_id": 123,
      "upstream": "<string>",
      "analytics_instance_id": 123,
      "web_root": "<string>"
    },
    "domain": "<string>",
    "url": "<string>",
    "removal": {
      "operation_id": "<string>",
      "id": 123,
      "name": "<string>",
      "force": true,
      "status": "<string>",
      "current_step": "<string>",
      "total": 123,
      "completed": 123,
      "remaining": 123,
      "failed_step": "<string>",
      "error_code": "<string>"
    },
    "transfer": {
      "operation_id": "<string>",
      "id": 123,
      "source_node_id": 123,
      "destination_node_id": 123,
      "destination_name": "<string>",
      "destination_path": "<string>",
      "destination_domain": "<string>",
      "sqlite_selected": true,
      "status": "<string>",
      "current_step": "<string>",
      "cutover_completed": true,
      "cleanup_completed": true,
      "failed_step": "<string>",
      "error_code": "<string>",
      "recovery_evidence": {}
    },
    "deploy_steps": [
      {
        "name": "<string>",
        "phase": "<string>",
        "command": "<string>",
        "timeout_seconds": 123
      }
    ],
    "vite_port": 123,
    "ssr_port": 123,
    "seed_path": "<string>",
    "seed_commit": "<string>",
    "annotator_port": 123,
    "annotator_url": "<string>",
    "routes": [
      {
        "id": 123,
        "kind": "<string>",
        "project_id": 123,
        "node_id": 123,
        "cluster_id": 123,
        "generation_basis_node_id": 123,
        "domain": "<string>",
        "provenance": "<string>",
        "publication": "<string>",
        "status": "<string>",
        "failed_step": "<string>",
        "error_code": "<string>",
        "replaces_route_id": 123,
        "replaced_by_route_id": 123,
        "replacement_step": "<string>",
        "target_set_step": "<string>",
        "target": {
          "id": 123,
          "instance_id": 123,
          "position": 123
        },
        "targets": [
          {
            "id": 123,
            "instance_id": 123,
            "position": 123
          }
        ],
        "process_id": 123,
        "upstream": "<string>",
        "analytics_instance_id": 123,
        "web_root": "<string>"
      }
    ]
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "data": {
    "id": 123,
    "project_id": 123,
    "node_id": 123,
    "project": {
      "id": 123,
      "name": "<string>",
      "slug": "<string>",
      "type": "monorepo"
    },
    "node": {
      "id": 123,
      "name": "<string>"
    },
    "name": "<string>",
    "source_layout": "<string>",
    "checkout_path": "<string>",
    "production_user": "<string>",
    "production_home": "<string>",
    "root": "<string>",
    "effective_root": "<string>",
    "selected_branch": "<string>",
    "branch_override": "<string>",
    "starting_commit": "<string>",
    "detached": true,
    "status": "<string>",
    "route": {
      "id": 123,
      "kind": "<string>",
      "project_id": 123,
      "node_id": 123,
      "cluster_id": 123,
      "generation_basis_node_id": 123,
      "domain": "<string>",
      "provenance": "<string>",
      "publication": "<string>",
      "status": "<string>",
      "failed_step": "<string>",
      "error_code": "<string>",
      "replaces_route_id": 123,
      "replaced_by_route_id": 123,
      "replacement_step": "<string>",
      "target_set_step": "<string>",
      "target": {
        "id": 123,
        "instance_id": 123,
        "position": 123
      },
      "targets": [
        {
          "id": 123,
          "instance_id": 123,
          "position": 123
        }
      ],
      "process_id": 123,
      "upstream": "<string>",
      "analytics_instance_id": 123,
      "web_root": "<string>"
    },
    "domain": "<string>",
    "url": "<string>",
    "removal": {
      "operation_id": "<string>",
      "id": 123,
      "name": "<string>",
      "force": true,
      "status": "<string>",
      "current_step": "<string>",
      "total": 123,
      "completed": 123,
      "remaining": 123,
      "failed_step": "<string>",
      "error_code": "<string>"
    },
    "transfer": {
      "operation_id": "<string>",
      "id": 123,
      "source_node_id": 123,
      "destination_node_id": 123,
      "destination_name": "<string>",
      "destination_path": "<string>",
      "destination_domain": "<string>",
      "sqlite_selected": true,
      "status": "<string>",
      "current_step": "<string>",
      "cutover_completed": true,
      "cleanup_completed": true,
      "failed_step": "<string>",
      "error_code": "<string>",
      "recovery_evidence": {}
    },
    "deploy_steps": [
      {
        "name": "<string>",
        "phase": "<string>",
        "command": "<string>",
        "timeout_seconds": 123
      }
    ],
    "vite_port": 123,
    "ssr_port": 123,
    "seed_path": "<string>",
    "seed_commit": "<string>",
    "annotator_port": 123,
    "annotator_url": "<string>",
    "routes": [
      {
        "id": 123,
        "kind": "<string>",
        "project_id": 123,
        "node_id": 123,
        "cluster_id": 123,
        "generation_basis_node_id": 123,
        "domain": "<string>",
        "provenance": "<string>",
        "publication": "<string>",
        "status": "<string>",
        "failed_step": "<string>",
        "error_code": "<string>",
        "replaces_route_id": 123,
        "replaced_by_route_id": 123,
        "replacement_step": "<string>",
        "target_set_step": "<string>",
        "target": {
          "id": 123,
          "instance_id": 123,
          "position": 123
        },
        "targets": [
          {
            "id": 123,
            "instance_id": 123,
            "position": 123
          }
        ],
        "process_id": 123,
        "upstream": "<string>",
        "analytics_instance_id": 123,
        "web_root": "<string>"
      }
    ]
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Path Parameters

instance

integer

required

Numeric Instance ID.

Required range: x >= 1

Body

application/json

node_id

integer

required

Required range: x >= 1

name

string

Optional destination Instance name

Maximum string length: 63

Pattern: ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$(?![\s\S])

sqlite_source_path

string

Optional SQLite database path on the source

Maximum string length: 4096

Pattern: ^\/[^\x00-\x1F\x7F]*$(?![\s\S])

Response

The request succeeded; an exact retry returned the existing record.

data

object

required

Show child attributes

Using the API

Gateway

Nodes

Clusters

Firewall

Fleet rollout

Tools

Metrics

GitHub App

Analytics

Projects

Instances

Environment

Routes

Database connections

Processes

Schedules

Annotations

Tasks

Extensions

Doctor

Activities

proxycli

Vaultwarden

Conn

Realtime

Node callbacks

Transfer an Instance

Path Parameters

Body

Response