File transfer
Upload and download individual files between your local controller and running workspaces over verified host SSH and Incus instance APIs.
Target workspace handle
Commands in this guide target a running workspace. Select one from raft list (see First working box):
raft list
box="lab:rf-a1b2c3d4e5f60718" # Replace with your actual workspace handleUploading files
Transfer a file from your controller to an absolute path inside the workspace:
# Create local sample file on controller
echo "Hello from controller" > ./local-file.txt
# Upload to workspace
raft upload "$box" ./local-file.txt /workspace/target-file.txtExisting destination files are overwritten. Create parent directories before uploading if needed:
echo '{"mode": "debug"}' > ./settings.json
raft exec "$box" -- mkdir -p /workspace/configs
raft upload "$box" ./settings.json /workspace/configs/settings.jsonAbsolute guest paths required
Guest file paths must be absolute paths beginning with /. Relative paths inside the container are rejected by the CLI parser.
Downloading files
Download a file from a workspace to your controller:
raft download "$box" /workspace/target-file.txt ./downloaded-file.txtThe destination path on the controller must specify the target filename.
Paths with spaces
Wrap paths in quotes when transferring files with spaces:
mkdir -p "./my documents"
echo "col1,col2" > "./my documents/data file.csv"
raft exec "$box" -- mkdir -p "/workspace/my documents"
raft upload "$box" "./my documents/data file.csv" "/workspace/my documents/data file.csv"
raft download "$box" "/workspace/my documents/data file.csv" "./downloaded-data.csv"Transferring directories
raft upload and raft download operate on individual files. Archive directories with tar for batch transfers:
Uploading a project directory
1. Create a local tar archive
mkdir -p ./my-project && echo "package main" > ./my-project/main.go
tar -czf ./project.tar.gz -C ./my-project .2. Upload archive to workspace
raft upload "$box" ./project.tar.gz /workspace/project.tar.gz3. Extract inside workspace
raft exec "$box" -- bash -lc '
mkdir -p /workspace/my-project
tar -xzf /workspace/project.tar.gz -C /workspace/my-project
rm /workspace/project.tar.gz
'Downloading a directory
1. Create archive inside workspace
raft exec "$box" -- bash -lc '
tar -czf /workspace/results.tar.gz -C /workspace/my-project .
'2. Download archive to controller
raft download "$box" /workspace/results.tar.gz ./results.tar.gz3. Extract locally on controller
mkdir -p ./results
tar -xzf ./results.tar.gz -C ./resultsFile ownership
Uploaded files are owned by root in the guest. Update ownership to developer when needed:
raft exec "$box" -- chown -R developer:developer /workspace/my-project