The project is in a healthy, maintained state
Manage remote servers over ssh with ruby.


~> 3.10
~> 1.12
~> 0.21


~> 3.0
~> 2.0
~> 6.1
 Project Readme

Latest version  Latest version  GitHub repo size 


Kanrisuru (manage) helps you remotely control infrastructure using Ruby. This is done over SSH. I'm working on building up some basic functionality to help quickly provision, deploy and manage a single host or cluster of hosts.

The idea behind this project is not to replace the numerous other projects to manage your infrastrucutre, however, I've found there usually meant to be a standalone project that have their own ecosystem. With Kanrisuru, you essentailly plug the library directly into your ruby project.

At this point, Kanrisuru doesn't use a DSL, or offer idempotency, and while that may be added later on, the goal with this project is to expose helpful ways of managing your remote infrastructure with plain ruby in a procedural manner. The realization I had was when trying to deal with other open source projects, you either had to deal with a different language than ruby, use agents on remote hosts, or deal with a complex library that is meant to act in a declarative manner.

If you want to dynamically interact with a host, eg: If you need to dynamically scale your infrastructure by continually monitoring specific stats from a centralized system, Kanrisuru can help you accomplish this.


Add this line to your application's Gemfile:

gem 'kanrisuru'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install kanrisuru


Run basic commands you would have access to while running on a remote host or on a cluster of hosts.


host = 'host', username: 'ubuntu', keys: ['~/.ssh/id_rsa'])
result = host.whoami   
result.to_s						# => 'ubuntu'

result = host.pwd
result.path 					# => /home/ubuntu 


cluster ={
  host: 'host1', username: 'ubuntu', keys: ['~/.ssh/id_rsa']
}, {
  host: 'host2', username: 'alice', keys: ['~/.ssh/id_rsa']

cluster.whoami   # => {host: 'host1', result: 'ubuntu'}, {host: 'host2', result: 'alice'}
cluster.pwd      # => {host: 'host1', result: '/home/ubuntu'}, {host: 'host2', result: '/home/alice'}

cluster.each do |host|
  host.pwd.path  # => /home/ubuntu

Host or Cluster with underlying command

host = 'host1', username: 'ubuntu', keys: ['~/.ssh/id_rsa'])

command ='uname')

command.success? #=> true
command.to_s  #=> Linux

cluster =, {host: 'host2', username: 'alice', keys: ['~/.ssh/id_rsa']})

cluster.execute('uname') #=> {host: 'host1', result: 'Linux'}, {host: 'host2', result: 'Linux'}

Methods and Testing

Description Ruby Shell Module Man Debian Ubuntu Fedora Centos RHEL openSUSE SLES
Get CPU Info cpu_info lscpu core [x] [x] [x] [x] [x] [x] [x]
Get CPU architecture lscpu lscpu core [x] [x] [x] [x] [x] [x] [x]
Get kernel stastics kernel_statistics cat /proc/stat core [x] [x] [x] [x] [x] [x] [x]
Get hardware BIOS info dmi dmidecode core [x] [x] [x] [x] [x] [x] [x]
Get open file details for processes lsof lsof core [x] [x] [x] [x] [x] [x] [x]
Get Load Average load_average cat /proc/load_avg core [x] [x] [x] [x] [x] [x] [x]
Get RAM Available free cat /proc/meminfo core [x] [x] [x] [x] [x] [x] [x]
Get list of processes ps ps core [x] [x] [x] [x] [x] [x] [x]
Get Env vars load_env env core [x] [x] [x] [x] [x] [x] [x]
Kill process kill kill core [x] [x] [x] [x] [x] [x] [x]
Get uptime of system uptime cat /proc/uptime core [x] [x] [x] [x] [x] [x] [x]
Get who's logged in w w core [x] [x] [x] [x] [x] [x] [x]
Reboot machine reboot shutdown core [x] [x] [x] [x] [x] [x] [x]
Poweroff machine poweroff shutdown core [x] [x] [x] [x] [x] [x] [x]
Get Disk Space df df core [x] [x] [x] [x] [x] [x] [x]
Get Disk Usage du du core [x] [x] [x] [x] [x] [x] [x]
List block devices lsblk lsblk core [x] [x] [x] [x] [x] [x] [x]
Get block device attributes blkid blikd core [x] [x] [x] [x] [x] [x] [x]
Mount a filesystem mount mount core
Unmount a filesystem umount umount core
Get Group Id get_gid getent group core [x] [x] [x] [x] [x] [x] [x]
Get Group get_group grep /etc/group core [x] [x] [x] [x] [x] [x] [x]
Create Group create_group groupadd core [x] [x] [x] [x] [x] [x] [x]
Update Group update_group groupmod core [x] [x] [x] [x] [x] [x] [x]
Delete Group delete_group groupdel core [x] [x] [x] [x] [x] [x] [x]
Get User Id get_uid id -u core [x] [x] [x] [x] [x] [x] [x]
Get User get_user id core [x] [x] [x] [x] [x] [x] [x]
Create User create_user useradd core [x] [x] [x] [x] [x] [x] [x]
Update User update_user usermod core [x] [x] [x] [x] [x] [x] [x]
Delete User delete_user userdel core [x] [x] [x] [x] [x] [x] [x]
List files and directories ls ls core [x] [x] [x] [x] [x] [x] [x]
Get Current Dir pwd pwd core [x] [x] [x] [x] [x] [x] [x]
Get Current User whoami whoami core [x] [x] [x] [x] [x] [x] [x]
Get Full Path of Shell Command which which core [x] [x] [x] [x] [x] [x] [x]
Real Path realpath realpath core [x] [x] [x] [x] [x] [x] [x]
Read link readlink readlink core [x] [x] [x] [x] [x] [x] [x]
Change Dir cd cd core [x] [x] [x] [x] [x] [x] [x]
"Find file, dir, special file device" find find core [x] [x] [x] [x] [x] [x] [x]
Stat file info stat stat core [x] [x] [x] [x] [x] [x] [x]
Change Permission of file / folder chmod chmod core [x] [x] [x] [x] [x] [x] [x]
Change Ownership of file / folder chown chown core [x] [x] [x] [x] [x] [x] [x]
Hard Link File ln ln core [x] [x] [x] [x] [x] [x] [x]
Soft Link File / Dir ln_s ln core [x] [x] [x] [x] [x] [x] [x]
Create Directory mkdir mkdir core [x] [x] [x] [x] [x] [x] [x]
Remove file / directory rm rm core [x] [x] [x] [x] [x] [x] [x]
Remove Directory rmdir rm core [x] [x] [x] [x] [x] [x] [x]
Touch File touch touch core [x] [x] [x] [x] [x] [x] [x]
Copy file / directory cp cp core [x] [x] [x] [x] [x] [x] [x]
Move file / directory mv mv core [x] [x] [x] [x] [x] [x] [x]
"Get file line, word, and char count" wc wc core [x] [x] [x] [x] [x] [x] [x]
Get content from beginning of file head head core [x] [x] [x] [x] [x] [x] [x]
Get content from end of file tail tail core [x] [x] [x] [x] [x] [x] [x]
Read a chunk from a file by lines reach_file_chunk tail and head core [x] [x] [x] [x] [x] [x] [x]
Echo to stdout or to file echo echo core [x] [x] [x] [x] [x] [x] [x]
Get all content from a file cat cat core [x] [x] [x] [x] [x] [x] [x]
Sed sed sed core [x] [x] [x] [x] [x] [x] [x]
Tar Files tar tar core [x] [x] [x] [x] [x] [x] [x]
Manage network devices ip ip core [x] [x] [x] [x] [x] [x] [x]
Get Socket Details ss ss core [x] [x] [x] [x] [x] [x] [x]
Upload to remote server upload scp core [x] [x] [x] [x] [x] [x] [x]
Download from remote server download scp core [x] [x] [x] [x] [x] [x] [x]
Wget wget wget core [x] [x] [x] [x] [x] [x] [x]
Apt apt apt core [x] [x]
Yum yum yum core [x] [x] [x]
Zypper zypper zypper core [x] [x]


After checking out the repo, run bin/setup to install dependencies.

To test kanrisuru across various linux distros, update your local /etc/hosts file to create an alias to the local virtual machine with that distro type. You can also set the host alias to the localhost machine.

To select which hosts to run rspec across, prepend the command line or export the variable while running rspec.

HOSTS=ubuntu,debian,centos rspec

This will run tests on the ubuntu, debian and centos instances.

Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.


The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Kanrisuru project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.