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 concepts around one-off dynos. To learn how to use them, see Working with One-Off-Dynos.

Use Cases

Some uses for one-off dynos are:

• Initializing databases or running database migrations, like rake db:migrate or node migrate.js migrate)
• Running a console or a REPL shell to run arbitrary code or inspect the app’s models against the live database, like rails console, irb, or node.
• One-time scripts committed into the app’s repo, like ruby scripts/fix_bad_records.rb or node tally_results.js.

About One-Off Dynos

After you push your application to Heroku, it can contain many components, including a web server, a console application, and scripts. While the web server gets used by the web dynos defined in your Procfile, the console and script only execute with one-off dynos.

One-off dynos run alongside other dynos, exactly like the app’s web, worker, and other formation dynos. They get all the benefits of dyno isolation. Instead of seeing web, worker or another process type in the logs, one-off dynos appear as run.

One-off dynos can make full use of anything deployed in the application. Each dyno has its own ephemeral file system, not shared with any other dyno. We discard the filesystem as soon as you disconnect from the one-off dyno.

You can schedule tasks to execute periodically using Heroku Scheduler, which uses one-off dynos in its implementation.

Formation Dynos vs. One-Off Dynos

The set of dynos declared in your Procfile and managed by the dyno manager via heroku ps:scale is known as the dyno formation. These dynos do the app’s regular business, such as handling web requests and processing background jobs.

There are some differences between one-off dynos, which execute with heroku run, and formation dynos, which execute with heroku ps:scale:

• By default, one-off dynos run attached to your terminal, with a character-by-character TCP connection for STDIN and STDOUT. You can use interactive processes like a console. Since STDOUT is going to your terminal, the only thing recorded in the app’s logs is the startup and shutdown of the dyno. You can also run detached dynos to run tasks in the background.
• One-off dynos terminate as soon as you press Ctrl+C or otherwise disconnect in your local terminal. One-off dynos never automatically restart, whether the process ends on its own or whether you manually disconnect.
• One-off dynos appear under the process type run.
• One-off dynos can never receive HTTP traffic, as the routers only route traffic to web dynos.
• One-off dynos don’t restart after a new app release.

Other than these differences, the dyno manager makes no distinction between one-off dynos and formation dynos.

Timeouts

Connections to most one-off dynos close after one hour of inactivity in both input and output. One-off dynos in Shield Spaces time out after 15 minutes. When the connection closes, the dyno receives a SIGHUP signal. This idle timeout helps prevent unintended charges from leaving interactive console sessions open and unused.

Detached dynos have no connection, so they have no timeout. However, like all dynos, one-off dynos are cycled every 24 hours. As a result, a one-off dyno will run for a maximum of 24 hours.

One-Off Dyno Size

The default one-off dyno size used depends on your app’s dyno formation:

• Apps using the Eco or Basic dyno types use the corresponding Eco or Basic dyno type in the one-off dyno. Other dyno types are not available.
• Apps using Standard or Performance dyno types use a Standard-1x dyno type in the one-off dyno. Apps using these dyno types can specify a different dyno type for one-off dynos by using the size argument. For example, heroku run --size=standard-2x rake heavy:job or heroku run --size=performance-l rake heavy:job.
• Apps using Private or Shield dyno types default to using Private-M or Shield-M in the one-off dyno.

Limits

See the Default scaling limits section for limits on how many one-off dynos can run concurrently.

Troubleshooting

See Troubleshooting One-Off Dynos Awaiting Process Timeout Issues

Additional Reading

• Working with One-Off Dynos
• Heroku Scheduler
• Dyno Formation