Upload Pier with SFTP

How to Get on Realm by Uploading a Pier with SFTP

This option is for people who want to move their existing ship with all of its apps, subscriptions, and configurations to Holium hosting.

(If you haven't launched a ship yet but you have created a shipname.key file at https://bridge.urbit.org, you can boot a ship locally using the "Boot a Planet" directions and then follow the instructions below.)


  • A ship that is running and up-to-date.

  • A ship that does not serve HTTPS (see step 2 in "Preparatory Instructions").

  • A ship whose pier is 3GB or less when compressed (either .tar.gz or .zip).

  • Planets only, no other classes of ship.


  • 5GB of ID data storage

  • 2GB of S3 data storage and 200GB/month sent data allowance

Overage charges are assessed: Each 0-5GB used over the allowance for ID data or S3 data costs $1/month. Each 0-100GB of data sent over the combined allowance per calendar month costs $1.

Preparatory Instructions

If the following instructions are not followed, we are not responsible for any issues resulting from the upload of your pier, including the sinking of your ship.

  1. To ensure your ship is running on the most current software available, please compare the "base hash ends in:" value when running +vats %base in your ship's terminal/dojo prompt to the end of the hash value for the most current release at https://github.com/urbit/urbit/releases. If it's not the same, you may need to run the |bump command (see https://operators.urbit.org/manual/os/dojo-tools#bump), or possibly even upgrade the urbit binary (see "5. Runtime Upgrades" at https://urbit.org/getting-started/cli).

  2. If your ship has been serving HTTPS directly for its web interface, it will need to be disabled. You can tell it's serving HTTPS directly because there will be a line during your ship boot sequence that begins with https: web interface live on (a line that begins with http: web interface live on (without the "s") does not require any changes). If such a line exists, please run |pass [%e %rule %cert ~] at the terminal/dojo prompt, then restart your ship to confirm that the https: web interface live on boot sequence message is no longer there.

  3. Whether you run ./urbit your_pier_directory or your_pier_directory/.run to start up your ship, it is the directory your_pier_directory that we must archive and compress to form a file named your_pier_directory.zip or your_pier_directory.tar.gz. You should perform the following steps to prepare it.

  4. Shut down your ship.

  5. Run ./urbit chop your_pier_directory (or your_pier_directory/.run chop), and follow the instructions about restarting your ship to confirm that the "chop" event log truncation process has run successfully. Assuming it starts up without problem (confirm this first!), delete the file mentioned after event log backup written to in the "chop" output. (If it will not start up, run the command shown after if you can't, restore your log by running when you first ran the "chop" command.) Shut down your ship again. Unless you wind up aborting this process, you should never run it again.

  6. Archive and compress the your_pier_directory directory using a utility that produces .zip or .tar.gz files (such as macOS's right-click Compress "your_pier_directory" option), or by running the following from the command line (substituting in the correct directory name for your case) one directory above your_pier_directory: tar -czvf your_pier_directory.tar.gz your_pier_directory

  7. Confirm that the size of your newly created compressed pier archive is under 3GB.

Upload Instructions

If you are new to Holium Hosting, go to hosting.holium.com and select "Upload Pier". Complete the account creation step and the purchase of a BYOP subscription, and then proceed to the upload step.

If you already have an account, log in and choose "Upload Pier" from the ID dropdown. Purchase a BYOP subscription and proceed to the upload step.

(If you have an account and have already purchased a BYOP subscription but have not yet performed the upload, log in and select the "BYOP (Pier)" entry from the ID dropdown. Proceed to the upload step.)

As an upload server is being brought online, you'll see the following screen:

When the upload server is ready, you'll see the display change to something like the following (the IP Address and Password will vary):

Now that you have the upload server details, open a terminal window and run the following commands:

  1. cd the-directory/your-pier/is-located-in

  2. touch done.file (this will be used later to indicate file uploading is complete)

  3. sftp pier@qqq.xxx.yyy.zzz (using the IP address provided to you)

  4. When prompted, enter the assigned password provided to you, and wait to be connected

  5. cd files (where files is a subdirectory on the SFTP server where the pier should go)

  6. put your-pier.zip or put your-pier.tar.gz , whichever is appropriate, to start the upload

  7. put done.file to signal that the upload is done

After the pier and done.file have been uploaded to the server, the boot process will start automatically and the screen will display

It may in fact take longer than 5-10 minutes if there are updates that begin to apply. Even if you leave this screen, the ship booting process will continue and if you return to your account later, you can look for your ship in your ID dropdown. As the boot process nears the end, you will see an intermediate message:

When the process completes, the display will show the following:

and then you can click Next to view the details of your uploaded ship.

Last updated