Process Management

exec

Execute a command in a running process.

$ convox cloud exec <pid> <command> -a <app> -i <machine>

Example:

$ convox cloud exec web-abc123 bash -a myapp -i production
/app #

Piped standard input is forwarded to the command, and the end of the pipe signals end of input:

$ printf 'hello\n' | convox cloud exec web-abc123 cat -a myapp -i production
hello

Output the command writes to standard error comes back with its standard output over the same connection, so lines from the two can interleave.

Piped input and error output require machine version 3.25.5 or later. A Cloud machine is reached through the Console, and a command that reads standard input with nothing piped in receives end of input and finishes with CLI version 3.25.9 or later. With CLI versions 3.25.5 to 3.25.8 it keeps waiting for input.

ps

List running processes.

$ convox cloud ps -a <app> -i <machine>

Options:

• --release: Specific release
• --service: Filter by service
• --watch: Rerun the command every given number of seconds

Example:

$ convox cloud ps -a myapp -i production
ID            SERVICE  STATUS   RELEASE      STARTED     COMMAND
web-abc123    web      running  RABCDEFGHI   1 hour ago  npm start
worker-def456 worker   running  RABCDEFGHI   1 hour ago  npm run worker

ps info

Get information about a specific process.

$ convox cloud ps info <pid> -a <app> -i <machine>

A finished process adds an Exit row carrying its exit status. The row is absent while the process is still running, absent when no container ever started, and absent on machines before 3.25.5.

ps stop

Stop a running process.

$ convox cloud ps stop <pid> -a <app> -i <machine>

Example:

$ convox cloud ps stop web-abc123 -a myapp -i production
Stopping web-abc123... OK

run

Run a one-off command in a new process.

$ convox cloud run <service> <command> -a <app> -i <machine>

Options:

• --cpu: CPU allocation (millicores)
• --memory: Memory allocation (MB)
• --detach: Run in background
• --entrypoint: Set to false to run the command without the image's entrypoint (default true)
• --id: With --detach, put the process id alone on stdout and all other output on stderr
• --release: Specific release
• --retain: With --detach, seconds to keep the finished process readable by ps info
• --timeout: Seconds before an attached run is abandoned, or before --wait gives up (default 3600)
• --wait: With --detach, wait for the process to finish and exit with its status

An attached run streams the command's own output and exits with its status.

Example:

$ convox cloud run web "rake db:migrate" -a myapp -i production

$ convox cloud run web bash -a myapp -i production
/app #

--wait reads the process record every 5 seconds until it reports complete or failed, then exits with the process's own exit code, so a pipeline step fails when the command does:

$ convox cloud run web "bin/migrate" --detach --wait -a myapp -i production
Running detached process... OK, web-s43xf

--retain keeps the finished process readable by convox cloud ps info after its command exits. The machine caps retention at 600 seconds, and --wait raises it to 60 seconds when the run asks for less. Retention is best effort, so a process the pipeline can no longer find is an unknown outcome and the step must treat it as a failure.

$ pid=$(convox cloud run web "bin/backfill" --detach --id --retain 600 -a myapp -i production)
$ convox cloud ps info "$pid" -a myapp -i production

--wait and --retain require machine version 3.25.5 or later. --id is handled by the CLI and works against any version. See run for the full detached-run reference.