Getting Started
API Basics
API Reference
Other Topics
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
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]"
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.
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
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
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
For a full list of providers and configuration details: SkyPilot documentation. Some additional providers supported by Runhouse via SkyPilot include:
Kubernetes
Lambda Cloud
& more
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 status
.
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)
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()