Last updated December 04, 2024

The heroku run:inside command allows you to connect over SSH to one of your app’s existing dynos and run commands inside of it.

Some use cases for heroku run:inside are:

• Accessing an app’s console
• Running migrations
• Debugging production services

Using heroku run:inside

Pre-requisites

• Install the Heroku CLI.
• Ensure you have added an SSH key to your Heroku account.
• Have at least one running dyno to run your command in.

You can check which dynos are currently running in your application with heroku ps.

$ heroku ps
=== web: `bundle exec unicorn -p $PORT -c ./config/unicorn.rb`
web-5f454b8b9-ztwlh: up 2024/11/01 18:04:16 +0000 (~ 19h ago)

Execution Syntax

heroku run:inside accepts two arguments: the name of the dyno you want to connect to, and the command to execute inside that dyno.

$ heroku run:inside <example-dyno-name> launcher <example-command>

For the second argument, heroku run:inside can also accept a process type that is present in your application’s Procfile.

For example, to execute the Python interpreter with a file dowork.py supplied as an argument, execute heroku run:inside <example-dyno-name> python dowork.py.

You can also supply a process type declared in a Procfile. In this case its definition gets substituted and executed together with any additional arguments. For example, given the following Procfile:

myworker: python dowork.py

You can run python dowork.py 42 inside the <example-dyno-name> dyno by executing:

heroku run:inside <example-dyno-name> myworker 42

Handling Flags

Separate any commands or flags that must be run on the dyno from the heroku command and flags with a --.

For example, to run ls -a on a dyno:

heroku run:inside web-5f454b8b9-ztwlh --app your-app -- ls -a
Running ls -a on ⬢ your-app... up, web-5f454b8b9-ztwlh
.       ..        Procfile               server.js

Disconnect From a Dyno

To disconnect from a dyno you connected to with heroku run:inside, type exit. The dyno continues to run as usual after you exit.

$ heroku run:inside web-5f454b8b9-ztwlh launcher bash
Running bash on your-app... up, web-5f454b8b9-ztwlh
~ $ bin/do-work
~ $ exit
$

Timeout

A session times out on its own if there’s no interaction for 15 minutes.

Examples

Bash

To see an existing dyno in action, execute the bash command, available in all applications deployed to Heroku:

$ heroku run:inside web-5f454b8b9-ztwlh launcher bash
Running bash on your-app... up, web-5f454b8b9-ztwlh
~ $

The bash command provides a shell environment for exploring the file system and process environment of your existing web-5f454b8b9-ztwlh dyno. Interact with the shell and list all the files that you deployed:

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

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

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

To exit:

~ $ exit

Run a Console

Run an app console:

$ heroku run:inside web-5f454b8b9-ztwlh launcher rails console
Running rails console on your-app... up, web-5f454b8b9-ztwlh
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">

Database Migration

Perform a database migration:

$ heroku run:inside web-5f454b8b9-ztwlh launcher rake db:migrate
Running rake db:migrate on your-app... up, web-5f454b8b9-ztwlh
Migrating to CreateWidgets (20110204210157)
==  CreateWidgets: migrating ==================================================
-- create_table(:widgets)
   -> 0.0497s
==  CreateWidgets: migrated (0.0498s) =========================================

Additional Reading

• One-Off Dynos
• Working with One-Off Dynos
• Heroku Exec