Skip to main content
Running a command in a machine lets you build code, run tests, or start a server there without opening a shell. The command runs as the machine’s login user, in the home directory, and you get back its output and its exit code, so a script or an agent can act on the result.
A machine that paused itself when it was idle wakes for the command, so you do not need to resume it first. For work that takes longer than ten minutes, run the command in the background.

​
Run a command

A command’s exit code becomes the result of the call, so your script can tell whether the command worked. The CLI exits with the same code, and the TypeScript SDK throws CommandExitError when the code is not zero.
The CLI treats one argument as a shell string, so when you want a pipeline to run inside the machine and not on your computer, put it in quotes. When you pass several arguments, they run as that exact program and arguments, with no shell in between.

​
Set the directory, environment, and timeout

By default a command starts in the home directory, /data/home, and is stopped after 60 seconds. You can set another directory, add environment variables for this one command, and set a longer timeout for a build or a test run, up to 600 seconds. A command that runs past its timeout is killed and exits with code 124.
These variables apply to one command only. To set variables for every command in a machine, see Environment variables.

​
Stream output as it is written

By default the output arrives all at once when the command ends. You can stream it instead, which lets you watch a build or a test run while it happens. Streamed output also has no size cap, so use streaming for a command that prints a lot.

​
Send input to a command

When a command reads from standard input, you can pipe data into it from your computer, such as a SQL file for a database client. The CLI takes up to 5 GiB this way, binary data included.

​
Run a long command in the background

A background command is detached from your terminal and has no time limit, so use it for a dev server, a long build, or an agent run. The command returns a job ID at once, and you use that ID to follow the job or end it later.
The CLI and the SDK see the same jobs, so you can start a job from code and follow it from a terminal.

​
Follow, wait for, and stop a job

When you do not have a job’s ID at hand, list the machine’s jobs. The list shows each job’s ID and whether the job is running or has exited.
To watch a job, follow its output until the job ends. The command then exits with the job’s exit code, so it behaves like a command that you ran in the foreground.
In a script, you can wait for a job to end without printing its output. When the timeout passes first, wait exits with code 124 and leaves the job running.
When you no longer need a job, such as a dev server you are done with, stop it. This sends TERM to everything that the job started.

​
Run one command in a new machine

instabox run creates a machine, runs the command in it, and deletes the machine afterwards, also when the command fails or you press Ctrl-C. Use it for a CI job or a one-off script, where you want a clean machine each time and nothing left behind. You can add --push to upload a local folder into the machine before the command runs.
run exits with the command’s exit code, so a CI step fails when the command fails. For a full pipeline, see CI.

​
See what ran

The machine keeps a history of the commands that were run through exec, by anyone, together with their exit codes. Read it to find out what an agent or a teammate did in the machine. The history also works while the machine is stopped.
The output of each command is stored too, so you can print the output of the last command again, or of an earlier one by its ID.
The history shows commands that were run before. To see what is running now, list the machine’s processes.

​
Limits

  • A command’s timeout is 60 seconds by default and 600 seconds at most. A background command has no time limit.
  • Without streaming, each of stdout and stderr is cut at 1 MiB, and the result’s truncated field says so.
  • A background job writes stdout and stderr to one log, so the SDK returns both in stdout.
  • Over the API, stdin holds up to 1 MiB of UTF-8 text. For more, or for binary data, write a file first and redirect it into the command.
  • The history keeps the newest 200 commands, with the first 64 KiB of each output stream.
  • exec exits with code 65 when a command succeeded but its output was binary. Copy files with instabox pull or instabox cp instead.

CLI reference

Every flag of exec, jobs, run, history, and output.

TypeScript commands

commands.run, streaming, and background handles.