> ## Documentation Index
> Fetch the complete documentation index at: https://orbit.nckrtl.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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



## OpenAPI

````yaml /openapi.json post /api/v1/instances/{instance}/transfer
openapi: 3.1.0
info:
  title: Orbit Gateway API
  version: v1
  description: >-
    The HTTP API of the active Orbit Gateway. The CLI and the PHP SDK send every
    fleet command through these endpoints over WireGuard. See [Using the
    API](/api/overview) for transport, authentication, envelopes, and errors.
servers:
  - url: https://gateway.orbit
    description: >-
      The active Gateway on the private WireGuard network, resolved by Orbit
      private DNS.
security: []
tags:
  - name: Gateway
    description: >-
      Status and trust of the active Gateway, and the releases of the Gateway
      itself.
  - name: Nodes
    description: Machines in the fleet, their roles, access grants, and storage settings.
  - name: Clusters
    description: Groups of Nodes with one Router and one development TLD.
  - name: Firewall
    description: Named UFW rules on one Node.
  - name: Fleet rollout
    description: >-
      The rollout of each verified Gateway release to the managed Nodes, and its
      catch-up.
  - name: Tools
    description: Packages that Orbit installs on a Node through a Tool Manager.
  - name: Metrics
    description: The Prometheus and Grafana role and its exporters.
  - name: GitHub App
    description: The Gateway's own read-only GitHub App and the accounts that installed it.
  - name: Analytics
    description: >-
      The analytics role, its Plausible version, and the Stats API key the
      Gateway uses to read visits.
  - name: Projects
    description: Repository records with one type, default branch, and web root each.
  - name: Instances
    description: Development checkouts and production releases of a Project on one Node.
  - name: Environment
    description: Stored Instance environment configuration and its .env projection.
  - name: Routes
    description: Domains that reach an Instance.
  - name: Database connections
    description: The registry of mysql, pgsql, and sqlite connections.
  - name: Processes
    description: >-
      systemd services and Docker containers owned by an Instance, a Node, or a
      Project definition.
  - name: Schedules
    description: Recurring commands run by native systemd timers.
  - name: Annotations
    description: Instance annotations, T3 delivery, and replayable status events.
  - name: Tasks
    description: Commander feature groups and ordered subtasks.
  - name: Extensions
    description: Gateway-owned extension switches.
  - name: Doctor
    description: Verify-only drift checks across the fleet.
  - name: Activities
    description: The Gateway log of authorized commands.
  - name: proxycli
    description: CLIProxyAPI quota snapshots, provider pools, and account controls.
  - name: Vaultwarden
    description: The copy of database credentials into a Vaultwarden collection.
  - name: Conn
    description: >-
      Profiles, shared workspace settings, registered T3 servers, and the
      pairing links the Gateway mints on them for each Node.
  - name: Realtime
    description: >-
      The record-change event feed broadcast to Reverb, its channel
      authorization, and Reverb connection discovery.
  - name: Node callbacks
    description: Endpoints that managed Nodes and Caddy call; operators do not call them.
paths:
  /api/v1/instances/{instance}/transfer:
    post:
      tags:
        - Instances
      summary: Transfer an Instance
      description: >-
        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.
      operationId: instance-transfer
      parameters:
        - name: instance
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: Numeric Instance ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                node_id:
                  type: integer
                  minimum: 1
                name:
                  type: string
                  pattern: ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$(?![\s\S])
                  maxLength: 63
                  description: Optional destination Instance name
                sqlite_source_path:
                  type: string
                  pattern: ^\/[^\x00-\x1F\x7F]*$(?![\s\S])
                  maxLength: 4096
                  description: Optional SQLite database path on the source
              required:
                - node_id
              additionalProperties: false
      responses:
        '200':
          description: The request succeeded; an exact retry returned the existing record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Instance'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                  - data
                  - meta
        '201':
          description: Created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Instance'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                  - data
                  - meta
        '403':
          description: >-
            The caller is not an active WireGuard peer (`peer.identity_unknown`)
            or lacks Node access to the target (`node_access.required`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No record matches the path parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            A guard refused the change and the Gateway changed nothing;
            `error.code` names the guard.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            The JSON body is not an object, has duplicate or unknown members, or
            fails validation (`validation.failed`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: bash
          label: curl
          source: >
            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"}'
        - lang: php
          label: PHP SDK
          source: >
            <?php


            use Orbit\Sdk\GatewayConnector;

            use Orbit\Sdk\Requests\Instances\TransferInstanceRequest;


            $connector = new GatewayConnector(
                baseUrl: 'https://gateway.orbit',
                caPemPath: '/path/to/orbit-root-ca.pem',
            );


            $response = $connector->send(new TransferInstanceRequest(instanceId:
            4, nodeId: 7))->dto();
components:
  schemas:
    Instance:
      type: object
      properties:
        id:
          type: integer
        project_id:
          type: integer
        node_id:
          type: integer
        project:
          $ref: '#/components/schemas/ProjectIdentity'
        node:
          $ref: '#/components/schemas/NodeIdentity'
        name:
          type: string
        source_layout:
          type: string
        checkout_path:
          type: string
        production_user:
          type:
            - string
            - 'null'
        production_home:
          type:
            - string
            - 'null'
        root:
          type:
            - string
            - 'null'
        effective_root:
          type:
            - string
            - 'null'
        selected_branch:
          type:
            - string
            - 'null'
        branch_override:
          type:
            - string
            - 'null'
        starting_commit:
          type:
            - string
            - 'null'
        detached:
          type: boolean
        status:
          type: string
        route:
          oneOf:
            - $ref: '#/components/schemas/Route'
            - type: 'null'
        domain:
          type:
            - string
            - 'null'
        url:
          type:
            - string
            - 'null'
        removal:
          oneOf:
            - $ref: '#/components/schemas/InstanceRemoval'
            - type: 'null'
        transfer:
          oneOf:
            - $ref: '#/components/schemas/InstanceTransfer'
            - type: 'null'
        deploy_steps:
          type: array
          items:
            $ref: '#/components/schemas/DeploymentStep'
        vite_port:
          type:
            - integer
            - 'null'
        ssr_port:
          type:
            - integer
            - 'null'
        seed_path:
          type:
            - string
            - 'null'
        seed_commit:
          type:
            - string
            - 'null'
        annotator_port:
          type:
            - integer
            - 'null'
        annotator_url:
          type:
            - string
            - 'null'
        routes:
          type: array
          items:
            $ref: '#/components/schemas/Route'
    Meta:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            The request ID the Gateway assigned or accepted; the same value is
            in the `X-Orbit-Request-Id` response header and in the Activity
            record.
      required:
        - request_id
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                Stable error code, namespaced by family, such as
                `node.not_active` or `route.target_conflict`.
            message:
              type: string
              description: >-
                Safe message without credentials, environment values, or remote
                output.
            details:
              type: object
              additionalProperties: true
              description: >-
                Bounded, redacted details such as the conflicting record IDs or
                the failed validation rule.
            request_id:
              type: string
              format: uuid
          required:
            - code
            - message
      required:
        - error
    ProjectIdentity:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        type:
          type: string
          enum:
            - monorepo
            - laravel-app
            - symfony-app
            - laravel-package
            - node-package
    NodeIdentity:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    Route:
      type: object
      properties:
        id:
          type: integer
        kind:
          type: string
        project_id:
          type:
            - integer
            - 'null'
        node_id:
          type:
            - integer
            - 'null'
        cluster_id:
          type:
            - integer
            - 'null'
        generation_basis_node_id:
          type:
            - integer
            - 'null'
        domain:
          type: string
        provenance:
          type: string
        publication:
          type: string
        status:
          type: string
        failed_step:
          type:
            - string
            - 'null'
        error_code:
          type:
            - string
            - 'null'
        replaces_route_id:
          type:
            - integer
            - 'null'
        replaced_by_route_id:
          type:
            - integer
            - 'null'
        replacement_step:
          type:
            - string
            - 'null'
        target_set_step:
          type:
            - string
            - 'null'
        target:
          oneOf:
            - $ref: '#/components/schemas/RouteTarget'
            - type: 'null'
        targets:
          type: array
          items:
            $ref: '#/components/schemas/RouteTarget'
        process_id:
          type:
            - integer
            - 'null'
        upstream:
          type:
            - string
            - 'null'
        analytics_instance_id:
          type:
            - integer
            - 'null'
        web_root:
          type:
            - string
            - 'null'
    InstanceRemoval:
      type: object
      properties:
        operation_id:
          type: string
        id:
          type: integer
        name:
          type: string
        force:
          type: boolean
        status:
          type: string
        current_step:
          type:
            - string
            - 'null'
        total:
          type: integer
        completed:
          type: integer
        remaining:
          type: integer
        failed_step:
          type:
            - string
            - 'null'
        error_code:
          type:
            - string
            - 'null'
    InstanceTransfer:
      type: object
      properties:
        operation_id:
          type: string
        id:
          type: integer
        source_node_id:
          type: integer
        destination_node_id:
          type: integer
        destination_name:
          type: string
        destination_path:
          type: string
        destination_domain:
          type: string
        sqlite_selected:
          type: boolean
        status:
          type: string
        current_step:
          type: string
        cutover_completed:
          type: boolean
        cleanup_completed:
          type: boolean
        failed_step:
          type:
            - string
            - 'null'
        error_code:
          type:
            - string
            - 'null'
        recovery_evidence:
          type:
            - object
            - 'null'
          additionalProperties: true
    DeploymentStep:
      type: object
      properties:
        name:
          type: string
        phase:
          type: string
        command:
          type: string
        timeout_seconds:
          type: integer
    RouteTarget:
      type: object
      properties:
        id:
          type: integer
        instance_id:
          type: integer
        position:
          type: integer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.