You are viewing main version. Click here to see docs for the latest stable version.

Installation and Setup

An overview of common installation and setup steps when working with Runhouse.

  • Installing the Runhouse library

  • Cloud providers and credentials

  • Cluster lifecycle management

  • Authenticate with Runhouse Den

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

Start by installing the AWS CLI. Follow this Getting Started guide or use pip install "runhouse[aws]" to include it with the Runhouse library.

Next, configure AWS with the following command:

$ aws configure

You’ll be prompted to enter your AWS Access ID. This can be found by logging into the AWS Console. Click on the name of your account in the top-left corner of the screen and then select “Securtiy credentials” from the dropdown.

To verify that credentials are properly set up, run the SkyPilot command again:

$ sky check

For more info: SkyPilot AWS

GCP

Begin by installing Runhouse with GCP:

$ pip install "runhouse[gcp]"

Additionally, you’ll need to install GCP tools. Run the following commands:

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

Your GCP credentials may also need to be set:

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

You’ll be prompted to pick a cloud project to use after running gcloud init. If you don’t have one ready yet, you can connect one later by listing your projects with gcloud projects list and setting one with gcloud config set project <PROJECT_ID>.

For more info: SkyPilot GCP

Azure

If you have an Azure account, use the following commands to install Runhouse and configure your credentials to launch instances on their cloud.

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

For more info: SkyPilot Azure

Other Providers

For a full list of providers and configuration details: SkyPilot documentation. Some additional providers supported by Runhouse via SkyPilot include:

  • Kubernetes

  • Lambda Cloud

  • & more

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()