Installation and Setup

Install the Runhouse library

Optionally, begin by setting up a virtual env with Conda or your package and environment management tool of choice. This allows you to maintain an environment with a specific version of Python and installed packages.

$ conda create -n rh_env python=3.9.15
$ conda activate rh_env

For local-only development, the Runhouse base package can be installed with:

$ pip install runhouse

Recommended: To use Runhouse to launch on-demand clusters, please instead run the following command. This additionally installs SkyPilot, which is used for launching fresh VMs through your cloud provider.

$ pip install "runhouse[sky]"

Alternatively, if you plan to use Runhouse with a specific cloud provider, you can install the package with that provider’s CLI included - or choose multiple providers. SkyPilot will also be included with these.

# Cloud-specific installation
$ pip install "runhouse[aws]"
# Include multiple providers
$ pip install "runhouse[aws,gcp]"

Configure Cloud Credentials

Optionally, for on-demand clusters, Runhouse uses SkyPilot to launch and manage virtual machine instances on your cloud providers. These steps are not necessary when using static clusters that can be accessed with SSH credentials.

For each provider, we recommend you begin by checking your configuration with SkyPilot.

$ sky check

This will show a detailed status of which cloud providers have already been configured properly.

$ aws configure

$ sky check

$ pip install "runhouse[gcp]"

$ pip install google-api-python-client
$ conda install -c conda-forge google-cloud-sdk -y

$ gcloud init
# Run this if you don't have a credentials file.
$ gcloud auth application-default login
$ sky check

$ pip install "runhouse[azure]"
# Login
$ az login
# Set the subscription to use
$ az account set -s <subscription_id>
$ sky check

On-Demand Cluster Lifecycle Management

To ensure that you have full control over the availability of on-demand clusters, and the cost associated with maintaining them, you may find the following SkyPilot commands helpful:

• sky status - Displays a list of all your clusters by name.

• sky stop <NAME> - Stops an instance. This will not fully tear down the cluster in case you need to restart it.

• sky down <NAME> - Fully tears down the instance. Best for when you are done using a cluster entirely.

• ssh <NAME> - Easily SSH into your cluster. Here you can further examine Runhouse’s server with runhouse cluster ssh.

Example output from sky status:

Clusters
NAME                     LAUNCHED    RESOURCES                                        STATUS  AUTOSTOP    COMMAND
rh-a10                   4 days ago  1x AWS(g5.2xlarge, {'A10G': 1}, ports=['8080'])  UP      30m (down)  llama3_tgi_ec2.py
sky-3201-matthewkandler  4 days ago  1x AWS(g5.xlarge, {'A10G': 1})                   UP      -           sky launch --gpus A10G:1 ...

Managed jobs
No in-progress managed jobs. (See: sky jobs -h)

Services
No live services. (See: sky serve -h)

Authenticate with Runhouse Den

To enable sharing features through Runhouse Den, you can log in to your Runhouse Den account. Start by creating one via our signup page. You’ll have the option to authenticate with your Google or Github account.

Once you’ve created an account, you’ll be able to access your Runhouse token on your account page.

Login to Runhouse in your terminal with the following command:

$ runhouse login

You’ll be prompted to enter your token and, after your initial login, you will see the following propmts:

• Download your Runhouse config to your local .rh folder? [Y/n]: - Updates your local config file from your settings on the cloud

• Upload your local .rh config to Runhouse? [y/N]: - Use updates to your local config to modify your saved account settings

If you are running Runhouse strictly in code (like in a notebook), you can also login to your account with the Python API:

import runhouse as rh
rh.login()