One-off Commands

Convox allows you to execute individual commands on your containers in several different contexts.

To run a command on a container in your Convox rack…

  • in a new container: convox run [service] [command]
  • in a running container: convox exec [container ID] [command]

To run a command in a local container…

  • in a new container: convox start [service] [command]
  • in a running container: There is no convox command for this. Use docker exec instead.

We’ll go into more detail about each of these commands below.

convox run

Syntax: convox run [service] [command]
Use: Spawns a new container in your Convox rack to run the desired command.


$ convox run web ls
Dockerfile  assets  bin  requirements.txt  templates

You can spawn an interactive shell:

$ convox run web bash

Or run one-off administrative tasks:

$ convox run web bin/migrate
Migrating database... Done

Detached processes

By default, convox run processes are run interactively (“attached”). This means you can interact with the running process via the terminal (stdin and stdout). Attached processes have a timeout of 1 hour.

If you don’t need to run a process interactively, you can add the --detach option to your convox run command:

$ convox run web --detach bin/long_running_process

Detached processes have no timeout and their output is available in the application logs.

convox exec

Syntax: convox exec [container ID] [command]
Use: Attaches to and executes the command in an existing container on your Convox rack.

Use convox ps to get the container ID:

$ convox ps
310481bf223f  web   RSPZQWVWGOP  256   5 days ago  bin/web
5e3c8576b942  web   RSPZQWVWGOP  256   4 days ago  bin/web

You can spawn an interactive shell:

$ convox exec 5e3c8576b942 bash
/app #

or run a one-off command:

$ convox exec 0105c73ce736 ps
  PID TTY          TIME CMD
   12 ?        00:00:00 sh
   16 ?        00:00:00 ps
$ convox exec 0105c73ce736 env

convox start

Syntax: convox start [service] [command]
Use: Spawns a new local container to run the desired command.

convox start is roughly analogous to docker run <image> <command> or docker-compose run <service> <command>.

This command lets you interact with your app and its tooling during local development.


$ convox start web 'node -e "console.log(\"Hello\")"'

Note: convox start [service] [command] is not intended to execute commands in already running containers. It will start a single container and then execute the command on that container. If you want to run a command in the container of an app started locally via convox start, use docker exec instead.