Repositories and worktrees
A workspace is an exact checkout on your host. Several workspaces can share a repository while using different branches or tool-managed worktrees.
Transfer an initial repository
Run from a committed local Git repository:
devbox setup --computer homeSetup transfers a bounded Git bundle over the trusted connection. The initial remote path is stable per repository and branch. Private and unpushed commits can be included without copying laptop GitHub tokens.
Ignored files are excluded. Credential-like tracked and historical paths are refused. Only a small allowlist of literal boolean .npmrc settings is accepted; authentication and interpolation are refused. Submodules need separate setup. The default bundle ceiling is 64 MiB.
Include uncommitted work explicitly
devbox setup --computer home --include-working-treeThis includes non-ignored untracked files and your working-tree changes. It does not mean your ignored .env will be copied. Inspect what you are transferring first.
Find the correct workspace
devbox workspace list --computer home
devbox workspace refresh --computer home
devbox workspace enter <workspace-id> --computer homeThe owner-local inventory includes approved Git roots, verified linked worktrees and supported Claude/Codex/Paseo/T3 locations. It reads Git/filesystem metadata, not transcripts or private vendor databases.
Complete scans remove deleted entries. Partial scans retain unconfirmed cached entries as stale. A stale or ambiguous match needs an explicit choice; it does not authorize a reset or a fresh overwrite.
Open an existing tool-created tree
devbox open --computer home --workspace <workspace-id> --with codexThe CLI revalidates the chosen path, origin and HEAD. A unique current repository-and-branch match can be reused automatically. Detached HEAD does not match merely because both branch names are absent.
Understand persistence
After initial transfer, the remote files are canonical. There is no automatic two-way laptop file sync. Push or pull with Git deliberately, using authentication configured on the host.
Default setup refuses divergent remote work. Explicit reconciliation policies below let you choose how to update it. Opening reports changed or dirty state without cleaning it. Do not delete a workspace to troubleshoot a connection problem.
Choose the host directory
devbox setup --computer home --remote-dir '~/src/payments'
devbox open --computer home --remote-dir '~/src/payments' --with codeQuote ~/… so your laptop shell does not expand it: the host expands it using the SSH account's home. Absolute host paths such as /srv/dev/payments also work. Without --remote-dir, the default remains ~/work/<repository>-<stable-repository-and-branch-key>. A custom destination is explicit per command; it does not change your default or rename existing worktrees.
The directory must be dedicated to this workspace, owned by the SSH account and reachable without symlink ancestors. The host needs Git and Python 3 for custom destinations and reconciliation. Root, the account's home and critical configuration directories cannot be destinations. --remote-dir and --workspace are mutually exclusive.
When the directory already exists
No policy silently overwrites arbitrary existing code. An existing directory must be the root of a Git worktree with the same canonical origin. Empty directories and other repositories are refused; choose a new destination instead.
| Intent | Command | Behavior |
|---|---|---|
| Accept existing code | devbox setup --remote-dir '~/src/payments' --existing reuse | Adopt the matching repository and branch without changing files, even if dirty or ahead. This is the custom-directory default. |
| Fast-forward only | devbox setup --remote-dir '~/src/payments' --existing update | Apply laptop commits only when the existing clean branch can fast-forward. Divergence is refused. |
| Merge cleanly | devbox setup --remote-dir '~/src/payments' --existing merge | Merge histories in a disposable checkout first. Publish only a successful merge; conflicts leave the live HEAD, index and working files unchanged. |
| Replace, retain backup | devbox setup --remote-dir '~/src/payments' --existing replace | Move the entire old ordinary repository to a sibling .backup-<id> directory, then publish the laptop copy. Print the backup path. No old directory is deleted. |
Add --computer home to select a host when you have several. open --remote-dir … always reuses; mutating --existing policies are accepted only by setup. With no custom directory or policy, legacy setup still verifies an unchanged canonical copy and refuses divergence.
Updates and merges require clean, matching branches on both sides; --include-working-tree is for initial transfer or explicit replacement, not merging dirty trees. Ignored host files stay local; an incoming tracked path that would overwrite an ignored file is refused. Before mutation, stop agents, terminals and dev servers using that worktree. Automatic mutation requires Linux process inspection and refuses when a visible same-account process has its working directory there. When hardened processes hide their directories, it refuses by default: stop workspace tools yourself, then explicitly add --confirm-stopped to acknowledge the incomplete check, or reconcile manually. The flag never overrides a detected active workspace. This is a busy check, not an editor lock or an open-file detector. The CLI serializes its own operations by destination, but cannot lock out another tool or a human editing the files: coordinate changes on a shared account.
Linked tool-created worktrees support reuse, update and merge. Replacement of a linked worktree **or its owning main repository** is refused to preserve Git's shared worktree metadata; use a fresh directory instead. Executable repository configuration such as custom filters, merge drivers, branch merge overrides and config includes requires manual reconciliation. Neither hooks nor a laptop credential store are used for reconciliation.
Recover or undo
Successful updates/merges print a refs/remote-workspace-backups/<id> reference to the previous HEAD. Inspect it with git show <ref> and recover deliberately with Git after stopping current work. Conflicting merges are not left half-applied in the live checkout.
For replacement, the printed sibling backup contains tracked edits, untracked files and ignored host secrets. To restore it, stop work, move the new directory aside and rename the backup to the original path. Keep both until verified. Backups remain on the host, consume disk and are never uploaded or automatically pruned; review and remove them yourself when no longer needed. An interrupted transfer can leave a .workspace-<id>.lock sibling: inspect the destination, any .backup-* sibling and running processes before removing a confirmed-stale lock. Never remove an active operation's lock.