We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

How To Use Tugboat to Manage DigitalOcean Droplets from a Terminal

Posted Sep 12, 2013 19k views API System Tools DigitalOcean Ubuntu


If you are reading this article, then you are probably familiar with how to manage your DigitalOcean droplets from within the Control Panel.

Tugboat is an exciting open source application written by Jack Pearkes and other contributors that can be used to manage your droplets from a command line interface.

In this guide, we will install and configure Tugboat using an Ubuntu 14.04 VPS. This will act as the "control" droplet for our other DigitalOcean droplets.

Table Of Contents

How To Install Tugboat

Log into your new droplet through SSH or by clicking the Console Access button on the droplet page.

Tugboat is a Ruby application, which means that we can install it easily using the RubyGems package manager.

First, we need to install Ruby from Ubuntu's default repositories:

sudo apt-get update
sudo apt-get install ruby ruby-dev build-essential

Now, we can install tugboat using RubyGems. We will also install system_timer to avoid a repeated notification message later:

sudo gem install tugboat
sudo gem install system_timer

We now have Tugboat installed on our system. Let's set it up.

How To Generate an API Key

In order for Tugboat to manage your droplets, you will have to authorize it to access your account through the DigitalOcean API interface. This is a simple procedure.

Log into your account on the DigitalOcean website.

Click on API on the left-hand navigation bar in the Control Panel.

You should see a Client ID pre-populated with a value that references your account.

DigitalOcean Client ID

Below this, if you have not set up an API Key yet, you will be told to generate a key:

DigitalOcean Generate Key

Your API key will be generated. Copy this key to a secure location. It will not be available to you again once you click out of this page. You will need to regenerate the key if you lose it.

You need both the Client ID and the API key to configure Tugboat, so keep this window open.

Initial Tugboat Configuration

Tugboat includes an initial configuration command that can be called by typing:

tugboat authorize

You will be asked a series of questions that are necessary to associate tugboat with your DigitalOcean account.

For the first two questions, copy and paste the values from the API page that you have opened:

Enter your client key: Client_ID_from_API_page
Enter your API key: API_Key_from_API_page

The next three questions involve the SSH authorization details necessary to connect to all of your droplets.

Press Enter to accept the default SSH key path. Depending on how you usually connect to your other droplets, you may wish to change the SSH user to another value (such as root). Press Enter to accept the default SSH port unless you connect to your droplets using a different port.

Enter your SSH key path (optional, defaults to ~/.ssh/id_rsa): 
Enter your SSH user (optional, defaults to demo): root
Enter your SSH port number (optional, defaults to 22):

Next, you will be taken through the default settings that will be used for new droplet creation. For now, we will press Enter through these prompts to accept the default values.

Enter your default region ID (optional, defaults to 1 (New York)): 
Enter your default image ID (optional, defaults to 284203 (Ubuntu 12.04 x64)): 
Enter your default size ID (optional, defaults to 66 (512MB)): 
Enter your default ssh key ID (optional, defaults to none): 

You should receive a reply confirming that your keys were accepted:

Authentication with DigitalOcean was successful.

The selections that we have just made are stored in a hidden file in your home directory called .tugboat:

nano ~/.tugboat

  client_key: xxxxxxxxxxxxxxxxxxxxxx
  api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  ssh_key: ""
  size: "66"
  image: "284203"
  region: "1"
  ssh_port: "22"
  ssh_user: root
  ssh_key_path: /home/demo/.ssh/id_rsa

If you ever need to re-generate your API Key, you will need to change it here after you re-generate it on the DigitalOcean website.

Afterwards, you will want to re-verify that the application can associate correctly by typing:

tugboat verify

The SSH section should be self-explanatory if you choose to modify it.

We will cover how to find the information needed to change the defaults section later.

Connect to a Droplet

We now have enough configured to explore Tugboat.

Every tugboat command begins with tugboat followed by an action.

Let's list the droplets that we have in our account:

tugboat droplets

irssi (ip: xxx.xxx.xxx.xx, status: active, region: 1, id: 3150xx)
tug (ip: xxx.xxx.xxx.xxx, status: active, region: 4, id: 3372xx)
test (ip: xxx.xxx.xxx.xx, status: active, region: 4, id: 3373xx)
DigitalOcean20Dollar (ip: xxx.xxx.xxx.xxx, status: active, region: 4, id: 3520xx)
archtestmail (ip: xxx.xxx.xxx.xx, status: active, region: 4, id: 4328xx)
TugWrite (ip: xxx.xxx.xxx.xxx, status: active, region: 4, id: 4496xx)

This is analogous to your droplet's screen in the web interface. It lists each droplet that we can interact with.

Let's SSH into one of our droplets by using tugboat:

tugboat ssh ourDroplet

Droplet fuzzy name provided. Finding droplet ID...done, 3150xx (ourDroplet)
Executing SSH (ourDroplet)...
Warning: Identity file /home/demo/.ssh/id_rsa not accessible: No such file or directory.
root@xxx.xxx.xxx.xx's password:

As you can see, we are asked for the password to root@ourDroplet. If we had set up SSH keys, we would have been connected without needing any additional interaction.

Exit out of the droplet to get back into the Tugboat droplet.

A feature that is present throughout the Tugboat experience is "Fuzzy name matching". This means that Tugboat will recognize any command that is unambiguous enough.

For instance, we could have reached the same result by typing:

tugboat drop

Tugboat will expand drop to mean droplets and execute it without any additional input.

This works with droplet names as well.

Droplet Management

All of the tasks that you normally accomplish with the Control Panel can be done with Tugboat.

Retrieve Droplet Information

To get more information about a specific droplet, type:

tugboat info droplet_name
Name:             irssi
ID:               3150xx
Status:           active
IP:               xxx.xxx.xxx.xx
Region ID:        1
Image ID:         479972
Size ID:          66
Backups Active:   false

This is mostly the same information that we are given in-line with the droplets command, but there are some additional fields, such as the Image ID, Size ID, and whether backups are enabled.

Droplet Power Management

We can control the power-on state of our droplets by issuing the appropriate commands.

To boot a droplet that is currently down, type:

tugboat start droplet_name

To reboot a droplet, type:

tugboat restart droplet_name

To power down a droplet, type:

tugboat halt droplet_name

Droplet Creation and Destruction

Droplets can be deleted by simply typing:

tugboat destroy droplet_name

Because this has irreversible consequences, you are asked to confirm the action before the droplet is destroyed:

Droplet fuzzy name provided. Finding droplet ID...done, 4530xx (blahblah)
Warning! Potentially destructive action. Please confirm [y/n]:

Type y and Enter to destroy the droplet.

To create a droplet, you can use the following syntax:

tugboat create droplet_name

Without additional arguments, your droplet will be created according to the criteria in the default section of your ~/.tugboat file.

We can modify this behavior by passing some optional flags. Use the "help" command with the "create" action as an additional argument to get the usage details of create:

tugboat help create

  tugboat create NAME

  -k, [--keys=KEYS]  # A comma separated list of SSH key ids to add to the droplet
  -s, [--size=N]     # The size_id of the droplet
  -r, [--region=N]   # The region_id of the droplet
  -i, [--image=N]    # The image_id of the droplet

Create a droplet.

As you can see, we can embed any of the SSH keys that we have uploaded to the site, and specify the size, region, and base image for the creation process.

We will discuss how to find the appropriate values for these parameters below.

Droplet Creation Settings

We can choose the settings that we want to use for droplet creation by querying the site for the available options.

To see the list of sizes and their associated IDs, type:

tugboat sizes

512MB (id: 66)
1GB (id: 63)
2GB (id: 62)
4GB (id: 64)
8GB (id: 65)
16GB (id: 61)
32GB (id: 60)
48GB (id: 70)
64GB (id: 69)
96GB (id: 68)

As you can see, each size is associated with an id, which we use to reference that value.

So if we wanted to create a 2GB droplet, we could issue the following command:

tugboat create -s 62 droplet_name

A similar command is available to see the available regions:

tugboat regions

New York 1 (id: 1)
Amsterdam 1 (id: 2)
San Francisco 1 (id: 3)
New York 2 (id: 4)

Embedding an uploaded SSH key within a new droplet is easy. You can find them by issuing:

tugboat keys

SSH Keys:
Work key (id: 12345)
Home key (id: 56789)

The command to view the available images is slightly more complex, only because by default, it shows the snapshots that you have saved:

tugboat images

My Images:
Ubuntu Basic setup (id: 4799xx, distro: Ubuntu)
Arch default (id: 4811xx, distro: Arch Linux)
LAMP Ubuntu (id: 4908xx, distro: Ubuntu)
LAMP Success (id: 5838xx, distro: CentOS)

You can select any of these to use as a base image by using the associated ID.

To get a more complete list, including all of the pre-configured distro and application images, add the global flag:

tugboat images -g

My Images:
. . .

Global Images:
CentOS 5.8 x64 (id: 1601, distro: CentOS)
CentOS 5.8 x32 (id: 1602, distro: CentOS)
Debian 6.0 x64 (id: 12573, distro: Debian)
Debian 6.0 x32 (id: 12575, distro: Debian)
. . .

You will see a large list of available images. These are referenced by their ID as well, just like the other settings.

These are the pieces of information that we would need to alter the values of the "default" settings in the ~/.tugboat configuration file.

Miscellaneous Administration

To take a snapshot using the snapshot command, type:

tugboat snapshot name_of_snapshot droplet_to_snapshot

To resize a droplet, you need to supply the new size criteria to the resize command. Your droplet must be powered on to run this successfully:

tugboat resize droplet_name -s size_ID

To reset the root password on a droplet, simply issue the password-reset command:

tugboat password-reset droplet_name

You will receive an email with the new password that has been set for the droplet.

How To Use the Help System

Tugboat includes a great help system. You can access the general help at any time by typing:

tugboat help

This will give you a list of every command that you can use.

To get more fine-grained help, specify a command name after help.

For instance, to get help with the authorize command, type:

tugboat help authorize

Other Considerations

How To Set Up SSH Keys

Like most applications that utilize SSH, Tugboat benefits from properly configured SSH keys.

If you have already created a public and private key pair and uploaded the public key to your DigitalOcean page to use for droplet creation, you can copy the private key to your Tugboat droplet.

To do this, log into the computer that you use to access your DigitalOcean droplets. Change to your ssh configuration directory:

cd ~/.ssh

Use scp to copy the private key to the Tugboat droplet:

scp id_rsa tugboat_username@tugboat_droplet_ip:/home/tugboat_username/.ssh/

Log into your Tugboat droplet. Change the ownership of the id_rsa file to match the username you are using with Tugboat.

sudo chown tugboat_username:tugboat_username ~/.ssh/id_rsa

You should now be able to connect to droplets that have been created with that key without a password:

tugboat ssh example_droplet

Remember to alter your configuration file to use this key for new droplet creation!

If you have not already done so, follow this article to set up key pairs and uploaded a public key to your DigitalOcean page.

How To Use Screen with Tugboat

One tool that is incredibly useful with Tugboat is screen, a terminal multiplexer.

Put simply, this tool allows you to manage multiple terminal sessions from a single window. You can create and switch between several "windows", each of which is an independent shell session.

This is especially handy when dealing with multiple SSH sessions, which is exactly what Tugboat allows you to do.

Install screen on Ubuntu by typing:

sudo apt-get update
sudo apt-get install screen

Start the application by typing:


You now are using a terminal session that is actually operating within screen.

You can connect to a droplet here by typing:

tugboat ssh droplet1

Now, create a new window by typing:

Ctrl-a c

That is, hold the control key, and hit the a key, followed by the c key. This creates a new window.

Connect to a new droplet in this window by typing:

tugboat ssh droplet2

You can switch between the windows by typing:

Ctrl-a n

You can destroy windows by typing:

Ctrl-a k

To learn more about how to use screen, click here. To learn how to use tmux, a similar terminal multiplexer, click here.


Tugboat is a great tool for managing your droplets without ever having to leave a terminal environment. It provides a unified interface to keep track of your droplets and manage your sessions.

Configuring Tugboat correctly eliminates the hassle of having to either perform continuous maintenance on a hosts file or flip back and forth between terminal and browser windows.

If you find any issues with the software or wish to contribute to the project, please visit the Tugboat page on Github.

Thank you Jack Pearkes and the Tugboat team for providing the DigitalOcean community with such a valuable tool!

By Justin Ellingwood


Creative Commons License