raft / docs
Guides

Copy or sync files

You can transfer files between your controller and a box you own. Set $box to its exact handle from raft list. Individual files work on running or stopped boxes; directory transfers and sync require a running box.

Guest paths must be absolute. Create parent directories first and quote paths containing spaces. Uploads run as guest root; change ownership when an application uses another user.

Copy a file

Uploading replaces an existing destination file. Downloading replaces the local destination only after a successful transfer:

printf '%s\n' 'Hello from the controller' > ./message.txt
raft upload "$box" ./message.txt /workspace/message.txt
raft download "$box" /workspace/message.txt ./message-copy.txt

For a failed download, your existing local file remains unchanged. Check free local disk and host connectivity before retrying.

Copy a directory

Inspect the source for secrets first. Recursive upload copies hidden files and ignored files too:

raft upload "$box" ./my-project /workspace/my-project --recursive
raft download "$box" /workspace/my-project ./project-copy --recursive

Both destinations must be absent, including symlinks, and their parents must exist. Raft publishes a complete tree; it does not merge into an existing directory. Use another destination name if a previous copy exists.

You keep file contents, executable bits, empty directories, internal hardlinks and relative symlinks within the tree. Links that escape the tree, devices, sockets and FIFOs are rejected. You need Python 3.11.8+ in the guest and enough controller scratch space for the directory archive.

If the project runs as developer, change its uploaded ownership:

raft exec "$box" -- chown -R developer:developer /workspace/my-project

Sync source edits

For repeated uploads, install rsync on your controller and use an image with rsync in the guest. Run from your Git working tree:

raft sync "$box" . /workspace/my-project --dry-run
raft sync "$box" . /workspace/my-project

Sync replaces matching files and detects changed content even when size and timestamps match. It keeps guest-only files, including files you deleted locally. Updates are atomic per file, not across the whole tree; rerun after an interrupted sync.

Git selects tracked files and unignored untracked files, including working-tree edits. .git is excluded and submodules are rejected. Tracked secrets are still included. For an inspected non-Git tree, pass --all to include hidden and ignored files as well. Unsafe symlinks and special files are skipped and reported rather than copied.

The destination must be an absolute guest directory other than /, with an existing parent. Unlike recursive upload, it may already exist. See project setup for credentials and setup commands.

On this page