File operations

boxd machine cp copies files in either direction. It works the same from your laptop and from inside a machine, and it does not need SSH keys or any setup. The console has a file browser for the same job, and the SDKs cover directories as well as files.

Upload and download

boxd machine cp ./local.txt myapp:/home/boxd/remote.txt    # upload
boxd machine cp myapp:/home/boxd/remote.txt ./local.txt    # download

The side with the NAME: prefix is the machine. Everything else is your local disk.

Where paths land

The path after NAME: follows three rules:

You write	It resolves to
`myapp:/etc/app/config.yaml`	used as-is
`myapp:~/notes.md`	`/home/boxd/notes.md`
`myapp:notes.md`	`/home/boxd/notes.md`

A bare relative path is the common case, so boxd machine cp ./notes.md myapp:notes.md puts the file in the home directory.

Whole directories

Add -r. The directory is tarred on the way out and untarred on arrival, so one call moves the whole tree. The destination is the parent to drop the directory into, not the name it gets:

boxd machine cp -r ./myproject myapp:.        # → /home/boxd/myproject
boxd machine cp -r ./myproject myapp:/opt     # → /opt/myproject

Naming the destination after the directory nests it, so myapp:myproject gives you /home/boxd/myproject/myproject.

Copying from macOS also carries over the ._name AppleDouble files that tar creates for extended attributes. They are harmless, and find . -name '._*' -delete inside the machine clears them.

Piping instead of files

Use - in place of a path to read from stdin or write to stdout:

echo "hello" | boxd machine cp - myapp:greeting.txt   # upload from stdin
boxd machine cp myapp:/var/log/app.log -              # download to stdout

Piping into machine exec works too, so cat data.json | boxd machine exec myapp -- 'jq .' behaves like a normal shell pipe. For moving bytes into a file, cp - stays the cleaner tool. It skips the shell entirely and verifies the byte count on arrival. To write somewhere root owns, upload to /tmp first and move it with exec:

cat nginx.conf | boxd machine cp - myapp:/tmp/nginx.conf
boxd machine exec myapp -- 'sudo mv /tmp/nginx.conf /etc/nginx/nginx.conf'

Between two machines

Every machine has the boxd CLI inside, so a machine can copy straight to another machine you own:

boxd machine exec myapp -- 'boxd machine cp ./file myapp-test:/tmp/file'

From your laptop there is no direct machine-to-machine copy. Download to your disk first, then upload to the other machine.

Limits

Uploads and downloads have different ceilings:

Uploads stream. Copying onto a machine has no practical size limit.
Downloads to your laptop move at most 4 MB per cp. A -r directory counts as one download of its tar.
From inside a machine, cp downloads at most 1 GB per file.

For anything above the download limit, stream it through exec instead, which has no cap:

boxd machine exec myapp -- 'cat /var/log/big.log' > big.log
boxd machine exec myapp -- 'tar -czf - myproject' > myproject.tgz

And for large public assets, download them inside the machine with curl or git. That uses the machine’s own bandwidth rather than yours.

From the console

Open a machine and pick the Files tab. It is a file browser over the same operations:

Browse folders, with a .. row to go up and a path bar to jump anywhere.
Upload with the button, or drag files and folders from your desktop onto the table. A dropped folder arrives whole. Drop onto a folder row to upload into that folder instead of the one you are in.
Download a file, or a folder as a .tar.gz.
Copy, cut, paste, rename, delete from the right-click menu, with the usual shortcuts: Ctrl or Cmd with C, X, V, D for download, F2 to rename, Delete. Click, Shift-click and Ctrl-click select several rows, Ctrl or Cmd with A selects everything, and the arrow keys move the selection.
Anything that would overwrite an existing file or folder asks first, and a folder pasted or uploaded over a folder of the same name replaces it rather than nesting inside it.

Transfers show a progress bar with a cancel button. A folder holding more than 5,000 entries is listed up to that many, with a note to use exec for the full listing. The Files tab, the terminal and the desktop follow the machine’s access rule: its owner, and every member of the org when the machine is shared.

From the SDKs

Both SDKs read and write files, and manage directories:

listing = boxd.machines.files.list_dir(machine.id, "/home/boxd")
listing.entries[0].name, listing.entries[0].is_dir, listing.entries[0].size_bytes
listing.truncated                       # True past 5,000 entries

boxd.machines.files.mkdir(machine.id, "/home/boxd/assets")
boxd.machines.files.rename(machine.id, "/home/boxd/a.txt", "/home/boxd/b.txt")
boxd.machines.files.copy(machine.id, "/home/boxd/src", "/home/boxd/src-copy")   # recursive
boxd.machines.files.delete(machine.id, "/home/boxd/src-copy")                    # recursive

const listing = await boxd.machines.files.listDir(machine.id, "/home/boxd");
listing.entries, listing.truncated;
await boxd.machines.files.mkdir(machine.id, "/home/boxd/assets");
await boxd.machines.files.rename(machine.id, "/home/boxd/a.txt", "/home/boxd/b.txt");
await boxd.machines.files.copy(machine.id, "/home/boxd/src", "/home/boxd/src-copy");
await boxd.machines.files.delete(machine.id, "/home/boxd/src-copy");

These are what the console’s Files tab uses. The in-VM boxd CLI stays read-only for other machines’ files on purpose.

Getting started

Guides

Integrations & automations

Use cases

References

File operations

Upload and download

Where paths land

Whole directories

Piping instead of files

Between two machines

Limits

From the console

From the SDKs

​Upload and download

​Where paths land

​Whole directories

​Piping instead of files

​Between two machines

​Limits

​From the console

​From the SDKs

Upload and download

Where paths land

Whole directories

Piping instead of files

Between two machines

Limits

From the console

From the SDKs