Skip to content
Run local scripts remotely by SSH
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Jossh - Your SSH Buddy

Gem Version Maintainability

Jossh is

  • a command line utility for running local scripts and commands over SSH.
  • a ruby library for easier and prettier SSH deployment and automation.


Add to your Gemfile

gem 'jossh'

Or install manually

gem install jossh


  1. Allows running one or more commands over SSH.
  2. Allows running local scripts remotely
  3. Allows running a script on multiple hosts.
  4. Has four commands: ssh, ssh!, ssh_script and ssh_script!. The 'bang' versions generate pretty and indented output.
  5. Uses a single SSH connection.
  6. Uses a simple hash for defining hosts.
  7. Allows storing host specifications in a YAML file.
  8. Supports all options available in Net::SSH#start.
  9. Prints output Heroku-style.
  10. Has a command line interface - jossh <host> <script>

Command Line Usage

After installing, you can call jossh from the command line to run arbitrary commands or a local script over SSH.

$ jossh -h


  jossh <host> <script> [-- <arguments>...]
  jossh -m | --make-hostfile
  jossh -e | --edit-hostfile
  jossh -l | --list
  jossh -h | --help 
  jossh -v | --version

    can be:
    - :symbol    : in this case we will look in ./ssh_hosts.yml or ~/ssh_hosts.yml
    - host       : in this case we will use the current logged in user
    - user@host

    can be:
    - a file in the current directory
    - a file in ~/jossh directory
    - one or more direct command

    When specifying a filename as the <script>, you may also pass additional
    arguments to it. 
    Use $1 - $9 in your script file to work with these arguments.
    Use $@ (or $*) to use the entire arguments string

  -m --make-hostfile     Generate a template ssh_hosts.yml 
  -e --edit-hostfile     Open the currently used ssh_hosts.yml file for editing
  -l --list              Show hosts in ./ssh_hosts.yml or ~/ssh_hosts.yml
  -h --help              Show this screen
  -v --version           Show version

  jossh :production "git status"
  jossh "cd ~ && ls -l"
  jossh deploy
  jossh rake -- db:migrate

Library Usage

Example 1: Host specifications in a YAML file

# example.rb
require 'jossh'

ssh! :localhost, ["cd /opt/app", "git pull"]
# ssh_hosts.yml
  :host: 'localhost'
  :user: 'vagrant'

Example 2: Host specifications directly in the code

# example.rb
require 'jossh'

localhost = {
  host: 'localhost',
  user: 'vagrant',
  forward_agent: true,

ssh! localhost, ["cd /opt/app", "git pull"]

Example 3: Run an external local script remotely

# example.rb
require 'jossh'

ssh_script! :production, deploy
# deploy
cd /opt/app
echo "-> Pulling source from origin"
git pull
echo "-> Restarting server"
touch 'tmp/restart.txt'
echo "-> Done"

See also: The examples folder

Host Specification File

When using a :symbol as the host name, Jossh will look for a YAML configuration file named ssh_hosts.yml. The file is expected to be either in the current directory or the user's home directory.

If you wish to use a different filename or location, use the ssh_hostfile method. If you specify only a filename or a relative path, Jossh will still look for this file in both the current directory and user's home directory.

# Specify exact location
ssh_hostfile "/etc/my_hosts.yml"
ssh! :myhost, 'ls'

# Look for ./configs/hosts.yml or ~/configs/hosts.yml
ssh_hostfile "configs/hosts.yml"
ssh! :myhost, 'ls'

You can ask Jossh to create a sample file for you by running:

$ jossh --make-hostfile

Working with Multiple Hosts

Define multiple hosts in the ssh_hosts.yml file by simply providing an array of other keys:

  :user: admin

  :user: admin

  - :web01
  - :web02

See ssh_hosts.example.yml as an example.

Writing Scripts

The scripts you execute with Jossh are simple shell scripts. These variables are available to you inside the script:

$1 - $9 and $@ or $*

When running through the command line and using the jossh <host> <script> -- <arguments> syntax, these variables hold the arguments.

$@ and $* hold the entire arguments string.


# myscript
echo "-> Running requested rake task"
rake $@

And call it with: $ jossh :host myscript -- db:migrate


When this syntax appears in your script, it will be replaced with any key from the host configuration.


echo "-> Migrating database on %{host}"
rake db:migrate
You can’t perform that action at this time.