Last updated October 16, 2024

One-off dynos allow you to perform administrative or maintenance tasks for your app and are helpful for debugging. This article explains how to work with them. To learn about their concepts, see One-Off-Dynos.

Run a One-Off Dyno

You can start a one-off dyno with the Heroku Dashboard, CLI or API.

With the Heroku Dashboard

In the dashboard, click the app you want to run a one-off dyno in. Click the More button in the upper right of the app’s Overview page. Click Run console. Enter the command to run in the dyno. See Execution Syntax for help.

With the CLI

Execute heroku run <command>. See Execution Syntax for help.

With the API

Use the Dyno Create API call. Pass run as the process type parameter and the command run in the dyno to the command parameter. See Execution Syntax for help.

Execution Syntax

heroku run takes two types of parameters. You can either supply the command to execute, or a process type that is present in your application’s Procfile.

If you supply a command, either a script or other executable available to your application, then it executes as a one-off dyno, together with any additional arguments. For example, to execute the Python interpreter with a file dowork.py supplied as an argument, execute heroku run python dowork.py.

If you instead supply a process type, as declared in a Procfile, then its definition gets substituted and executed together with any additional arguments. For example, given the following Procfile:

myworker:  python dowork.py

Executing heroku run myworker 42 runs python dowork.py 42 as a one-off dyno.

Handling Command Flag Conflicts

If the command to run on the dyno contains flags that conflict with flags that heroku run itself also expects, use -- to tell the CLI to not parse flags and pass them on to the dyno.

For example, if you wanted to run ls -a on a dyno, the -a appears to the CLI as if you were passing in an --app flag for the run command, not a flag for ls. To fix with --:

$ heroku run -a myapp -- ls -a
Running ls -a on ⬢ forker... up, run.4520 (Eco)
.       ..        Procfile               server.js

Shield Private Spaces

To use one-off dynos for apps in Shield Private Spaces, you must first add an SSH key to your user account. See Managing SSH Keys for more info.

Run Tasks in the Background

You can run a dyno in the background using heroku run:detached. Unlike heroku run, these dynos send their output to your logs instead of your console window. You can use heroku logs to view the output from these commands:

$ heroku run:detached rake db:migrate
Running rake db:migrate... up, run.2
Use 'heroku logs --dyno run.2' to view the log output.

Stop a One-Off Dyno

Check your current running dyno’s name using heroku ps:

$ heroku ps
=== run: one-off processes
run.4520: starting 2013/03/13 15:38:08 (~ 1s ago): `bash`

=== web: `bundle exec unicorn -p $PORT -c ./config/unicorn.rb`
web.1: up 2013/03/13 15:08:07 (~ 30m ago)
web.2: up 2013/03/12 17:06:09 (~ 22h ago)

To stop a running one-off dyno, use heroku ps:stop with its name.

$ heroku ps:stop run.4520
Stopping run.4520 process... done

One-off dynos don’t stop when you issue heroku ps:restart on your application. They also don’t restart after a new app release.

Run Tasks Inside an Existing Dyno

While one-off dynos are a great fit for administrative tasks, sometimes you need to debug a service on a production dyno. Unlike one-off dynos, Heroku Exec makes an SSH connection directly to an existing dyno (e.g., web.2). Exec also allows you to copy files off of a dyno, forward traffic on a local port to a dyno, and take advantage of common Java debugging tools.

Examples

Bash

To see one-off dynos in action, execute the bash command, available in all applications deployed to Heroku:

$ heroku run bash
Running bash attached to terminal... up, run.1
~ $

At this point you have a one-off dyno executing the bash command which provides a shell environment for exploring the file system and process environment.

Interact with the shell and list all the files that you deployed:

~ $ ls
Procfile project.clj src bin ...

If you had a batch file in the bin directory, you can simply execute it, just as you can many other Unix commands:

~ $ echo "Hi there"
Hi there
~ $ pwd
/app
~ $ bin/do-work

Remove a few files, and exit:

~ $ rm Procfile project.clj
~ $ exit

Because each dyno has its own ephemeral filesystem, the deleted files won’t change your running application.

Database Migration

Here’s an example database migration:

$ heroku run rake db:migrate
(in /app)
Migrating to CreateWidgets (20110204210157)
==  CreateWidgets: migrating ==================================================
-- create_table(:widgets)
   -> 0.0497s
==  CreateWidgets: migrated (0.0498s) =========================================

Run a Console

Here’s an example of running a rails console:

$ heroku run rails console
Running rails console attached to terminal... up, run.2
Loading production environment (Rails 3.0.3)
irb(main):001:0> Widget.create :name => 'Test'
=> #<Widget id: 1, name: "Test", size: nil, created_at: "2011-05-31 02:37:51", updated_at: "2011-05-31 02:37:51">

Additional Reading

• One-Off Dynos
• Heroku Scheduler
• Heroku Exec