Skip to content

Run a command on a machine

Run a command on a machine without opening a shell, and get its output and its exit code back. It runs as root, so it can install packages, restart services and change anything on the machine.

Open the machine, go to its Commands tab and choose Run a command. Enter the command, and optionally a working directory, a timeout in seconds and environment variables. The dialog follows the command until it finishes and shows its output. Close and leave it running closes the dialog without stopping the command.

There is no shell around the command, so pipes, redirection and cd need one spelled out:

Terminal window
deployport machinery commands run mach_kxpkzlq4qf -- sh -c 'docker ps | wc -l'

If everything worked, the output is the program’s own and the run ends as succeeded. deployport machinery commands list <machine-id> shows the run and how it ended.

Pass the script’s text to sh -c:

Terminal window
deployport machinery commands run mach_kxpkzlq4qf -- sh -c "$(cat deploy.sh)"

The command gets no standard input, so a script that waits for an answer reads nothing and goes on. To run as the login user instead of root, put sudo -u deployport in front of the program.

OptionWhat it does
--workdir <dir>The directory to run in, which takes the place of cd
--env NAME=VALUEAdds a variable to the command’s environment, and can be repeated
--timeout <duration>Stops the command after this long, 5 minutes by default and 1 hour at most
--no-waitQueues the command and prints it without waiting for the result

The CLI exits with the program’s own code when it is between 1 and 255. Its own codes are:

CodeMeaning
0The command succeeded
121The CLI stopped waiting before the result arrived
122The command was cancelled
123The machine refused to run it, for example because the program does not exist
124The command reached its timeout and was stopped
125The command never reached the machine
130You pressed Ctrl+C, and the command keeps running on the machine

A command for a stopped or offline machine waits in the machine’s queue for up to an hour and runs when the machine comes back. The CLI stops waiting after 30 seconds, exits with 125, and prints how to read the result later. Start the machine and let it come online before you run a command you need to wait for.

Terminal window
deployport machinery commands list mach_kxpkzlq4qf
deployport machinery commands get <command-id>

A command and its output stay readable for about an hour after it finishes. The machine’s activity log keeps a line for each run, with the command, who ran it, how it ended and its exit code, for 90 days. It does not keep the output or the environment.

  • A machine runs up to 5 commands at once, and up to 8 more can wait in its queue.
  • Each output stream keeps up to 64 KiB from the machine, and the stored result keeps its first 16 KiB and its last 8 KiB.
  • Running the same command twice runs it twice.
ActionWhat it allows
machinery:RunCommandRun a command as root on a machine
machinery:ListCommandsRead a machine’s commands and their output, which waiting for a result needs too
machinery:CancelCommandCancel a command that has not started yet

A command that has already started cannot be cancelled. It runs until it finishes or reaches its timeout.

A setup step runs once, on each machine created after it is added, from the account’s setup settings. A command runs once, now, on a machine you already have, and nothing is stored. Set what every machine inherits covers the settings, setup included.