worktrees

Migrate Worktree

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.

post/api/v1/worktrees/{worktree_id}/migrate

Request

  • Base URL: https://docs.omnara.com (the document declares no server; this is the origin it was published from)
  • URL: https://docs.omnara.com/api/v1/worktrees/{worktree_id}/migrate
  • Auth: HTTP bearer

Path parameters

worktree_idstring required

Request body

target_type'LOCAL' | 'REMOTE' required

Target type: LOCAL (user machine) or REMOTE (sandbox)

target_machine_idstring 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_namestring 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

Successful Response

status'migrated' required

Status of the migration: 'migrated' on success

Changes

No recorded changes to this operation across all 1 revision of this API.