# Getting started

URL: https://heaven.dev/docs/getting-started
Updated: 2026-11-21

Buy capacity and connect your coding agent to Heaven. To work from your own terminal, use the CLI to create a Computer, serve a website at its HTTPS address and open a shell.

## Buy capacity

If you already have access to a running pool, skip to [connecting your agent](https://heaven.dev/docs/getting-started#connect-your-agent) or [installing the CLI](https://heaven.dev/docs/getting-started#install-the-cli).

On the [pricing page](https://heaven.dev/pricing), choose **Monthly** and select **Buy** on the **Tiny block** (Plan 1). Sign up or sign in when prompted, then complete payment. If you don't manage an organization yet, Heaven creates one for you.

To buy from a terminal, [install the CLI and sign in](https://heaven.dev/docs/cli#install-and-sign-in) first. If you don't have an organization yet, use `heaven organization create NAME` with an available name. Run the purchase command with your organization's name in place of `acme`:

```sh
heaven capacity buy --plan 1 --monthly --organization acme
```

Open the payment link from the command to complete the purchase.

The launch offer takes half off the first month of your organization's first monthly purchase. You can get a full refund if you release that purchase within 48 hours. See [Pricing](https://heaven.dev/docs/pricing#monthly-or-hourly) for the terms.

For hourly billing, choose **Pay as you go** on the pricing page, or use `--hourly` in place of `--monthly` with enough prepaid balance to cover the first hour.

Heaven puts the entire purchase into the organization's first pool. For an organization named `acme`, the pool is `acme-pool`. It's ready after payment for a monthly purchase, or immediately when you buy hourly capacity.

## Connect your agent

- **MCP client.** If your client supports Streamable HTTP and OAuth, add `https://heaven.dev/mcp` as its [hosted MCP server](https://heaven.dev/docs/mcp#hosted-server). Sign in through the client to give it your Heaven permissions. To run the server locally, install the CLI and sign in where the client runs. Run `heaven mcp install` to add Heaven to the [supported clients](https://heaven.dev/docs/mcp#local-server) it finds, or [set up another client by hand](https://heaven.dev/docs/mcp#local-server). Restart your client if it's already running.
- **Terminal agent.** [Install the CLI](https://heaven.dev/docs/cli#install-and-sign-in) where the agent runs, even on another machine. Run `heaven login` there and approve the code it shows in your browser. The agent can find commands with `heaven help`.
- **Script, CI job or service.** In [SSH & API keys](https://heaven.dev/dashboard/settings/keys), create an API key with **Read only** access, or **Custom** for the commands it runs, and set it as `HEAVEN_API_KEY` in the process's secret environment. The [CLI](https://heaven.dev/docs/cli#scripts) reads this variable. For the [HTTP API](https://heaven.dev/docs/http-api#authentication), send the key as a bearer token.

Ask your agent to list the Heaven Computers it can access. For a script, use `heaven view` or `GET /v1/computer/` with a key that allows `view`. A successful list, even an empty one, confirms the connection.

## Install the CLI

If you installed the CLI to buy capacity, continue to [signing in and selecting a pool](https://heaven.dev/docs/getting-started#sign-in-and-select-a-pool).

To work from a terminal, install the CLI on your Mac or Linux computer:

```sh
curl -fsSL https://heaven.dev/install | sh
heaven version
```

The [CLI guide](https://heaven.dev/docs/cli#install-and-sign-in) includes Windows installation.

## Sign in and select a pool

If you haven't signed in through the CLI yet, run:

```sh
heaven login
```

When you approve the sign-in in your browser, keep **Add its SSH key** selected so you can open a shell later. List your pools:

```sh
heaven pool view
```

Find the organization and pool names in the list. In the next command, use those names in place of `acme` and `acme-pool`.

## Create a Computer

```sh
heaven create my-site --organization acme --pool acme-pool --image heaven-ubuntu --wait=60s
heaven view my-site
```

Continue when the Computer reaches [`running`](https://heaven.dev/docs/computers#states) and any setup script has finished. If it is still starting after the wait, run `heaven view my-site` again. Its state message reports progress and failures.

On November 19, 2026, nine creates of the [default image](https://heaven.dev/docs/computers#default-image) on heaven.dev took 1.70 to 2.32 seconds from the create request until the Computer was running and reachable. The median was about 1.9 seconds. The client had about 30 ms of round-trip latency, and the first SSH command succeeded about 0.35 seconds after the Computer was ready. Create times vary.

## Serve a website

From your local terminal, write a page and start [nginx](https://heaven.dev/docs/computers#default-image):

```sh
heaven exec my-site 'printf "%s\n" "Hello from Heaven." | sudo tee /var/www/html/index.html >/dev/null'
heaven exec my-site 'sudo systemctl enable --now nginx'
```

Set the website port and access:

```sh
heaven website my-site --port 8000 --access private
```

Open `https://my-site.heaven.dev` and sign in. The page displays **Hello from Heaven.**

## Open a shell

```sh
heaven ssh my-site
```

The shell opens as the [image's login user](https://heaven.dev/docs/computers#default-image).
