Skip to main content
The file commands copy files and folders between your computer and a machine. You can use them to copy a project into a machine before a build, to copy the results back out afterwards, or to read and write a single file from your own code.
This copies the folder to /data/home/my-app in the machine named dev. Files under /data, which is where the home directory /data/home lives, stay on the machine when you pause or stop it.

​
Copy a folder into a machine

Push a local folder when you want to work on it in the machine, for example to build or test a project there. When you give no destination, the folder keeps its name and lands in the home directory. In a git repository, only the files that git tracks are copied, so anything that you have not added to git is left out.
When you also need untracked files, add --all in the CLI, or pass all: true in the TypeScript SDK and all=True in the Python SDK. This adds the untracked files that git does not ignore. Files that git ignores, such as node_modules, are still left out.

​
Copy a folder out of a machine

Pull a folder when you want something that the machine produced, such as build output or logs, on your own computer. Everything under the folder is copied, dot files and empty directories included. When you give no destination, the CLI copies into the current directory.

​
Copy one file

When you only need to move a single file, instabox cp copies it in either direction, in the style of scp. You write the machine side as the machine’s name, a colon, and the path.
To copy the file out of the machine, put the machine side first and the local path second.

​
Write a file from code

When your program needs to put a config file or some generated content into a machine, you can write text or bytes straight to a path. The SDKs create the parent directories for you, so the folder does not have to exist yet. The API creates them only when you add parents=true. Without it, a missing folder gives 404 missing_parent.

​
Read a file from code

You can read a file into memory as text, which suits a config file or a result that your program wants to inspect. For a large file, read it as a stream instead, as TypeScript files shows.

​
List a directory

List a directory to see what is in it before you copy it, or to check that a file you expect is there. The list shows the entries of that one directory and is not recursive.
instabox files also prints a text file when the path is a file, so you can read a small file without copying it.

​
How a path is copied

Where a folder ends up depends on the destination that you give and on whether the source ends in a slash. push, pull, and cp follow the same four rules for a directory. To copy a directory with cp, add -r. The destination itself does not have to exist, but its parent folder does. When the parent is missing, push and cp fail with missing_parent. Add -p to create the missing parent folders.

​
Limits

  • push streams a single file of up to 5 GiB. For a larger file, split it, push the parts, and join them in the machine with cat.
  • pull streams a single file of any size.
  • A folder is copied as one compressed archive, and the archive has a size limit: 1 GiB for push and 32 MiB for pull. For a larger folder, copy it over instabox ssh.
  • For large files, use push or cp and not scp or rsync. See SSH for the reason.
  • The file routes of the API wake a machine that paused itself when it was idle. A machine that is stopped, or that you paused, answers 409 machine_not_running.

Run commands

Build, test, and start servers on the files you copied.

Snapshots

Save a machine’s disk and start new machines from it.