---
title: "Migrate Worktree"
method: POST
path: "/api/v1/worktrees/{worktree_id}/migrate"
tags: ["worktrees"]
---

# Migrate Worktree

`POST /api/v1/worktrees/{worktree_id}/migrate`

Migrate a worktree to a different machine type (LOCAL or REMOTE).

For LOCAL: Requires target_machine_id pointing to a user's machine.
For REMOTE: Creates a managed machine (sandbox), provisions the workspace,
            and starts sessions in the sandbox.

The migration process:
1. Stops any running sessions on the current machine (if migrating from local)
2. Updates the worktree's machine association
3. For REMOTE: Provisions sandbox workspace and starts sessions in background

Special case: When source='base_ref' and worktree_name is provided, creates a
new worktree with that name as REMOTE from base_ref, ignoring the worktree_id.

## Path parameters

- `worktree_id` string, required

## Request body

- WorktreeMigrateRequest — Request to migrate a worktree to a different machine type.
  - `target_type` 'LOCAL' | 'REMOTE', required — Target type: LOCAL (user machine) or REMOTE (sandbox)
  - `target_machine_id` string, nullable — Target user machine ID (required for LOCAL, ignored for REMOTE)
  - `source` 'checkpoint' | 'base_ref' — Source for REMOTE migration: 'checkpoint' uses current checkpoint, 'base_ref' starts fresh from workspace base ref (requires sync enabled)
  - `worktree_name` string, nullable — Name for new worktree when using source='base_ref'. If provided, creates a new worktree with this name instead of migrating existing one.

## Response `200`

Successful Response

- WorktreeMigrateResponse — Response after migrating a worktree.
  - `worktree` WorktreeDescriptor, required — Serialized worktree entity returned to API clients.
    - `id` string, required — Unique worktree identifier
    - `workspace_id` string, required — Parent workspace identifier
    - `name` string, nullable — Worktree name (null for the main worktree)
    - `is_main` boolean, required — Whether this is the main/default worktree for the workspace
    - `path` string, nullable — Filesystem path for the worktree on the machine
    - `worktree_type` 'LOCAL' | 'REMOTE', nullable — Type of worktree: LOCAL (user machine) or REMOTE (sandbox)
    - `user_machine_path` SharedSchemasWorktreeUserMachinePathDescriptor — Machine path information associated with a LOCAL worktree.
      - `id` string, required
      - `machine_id` string, required
      - `local_path` string, required
    - `managed_machine_id` string, nullable — Managed machine ID if worktree_type is REMOTE
    - `last_heartbeat_at` string, date-time, nullable — Most recent liveness heartbeat received from the sandbox container (REMOTE only).
    - `last_synced_checkpoint_id` string, nullable — ID of the last checkpoint that was successfully synced to cloud storage. This may differ from current_checkpoint_id if a recent checkpoint failed to sync.
    - `checkpoint_restore_pending` boolean — Whether a checkpoint needs to be restored on next local session start
    - `current_checkpoint_id` string, nullable — Identifier of the current checkpoint for this worktree
    - `checkpoint_metadata` object, nullable — Metadata associated with the current checkpoint (e.g., commit info)
    - `created_at` string, date-time, required — Timestamp when the worktree was created
    - `updated_at` string, date-time, required — Timestamp when the worktree was last updated
  - `status` 'migrated', required — Status of the migration: 'migrated' on success

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/omnara/apis/omnara-api.md) · [All operations](https://skmtc.dev/omnara/apis/omnara-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/omnara/omnara-api/revisions/624048e40cad/schema)