---
title: "Quickstart"
source: "https://browserpod.io/docs/getting-started/quickstart"
---

# Quickstart

Get started with BrowserPod in minutes: get a free BrowserPod Edge key, then start from a template or add BrowserPod to a web app you already have.

Get a Pod running in your browser in a few minutes. Start with a key, then either scaffold a new project from a template, or add BrowserPod to a web app you already have.

## 1. Get a free BrowserPod Edge key

BrowserPod Edge connects your Pods to the internet, so everything works: npm, GitHub and the other [allowed domains](https://browserpod.io/docs/understanding-browserpod/networking.md) without CORS limits, and [Portals](https://browserpod.io/docs/understanding-browserpod/portals.md), which give servers running in your Pod a public URL. It’s free for up to 1,000 connected hours every month.

To get a key, sign in at [https://console.browserpod.io](https://console.browserpod.io/) with your GitHub account and create an API key.

You can also continue without a key: Pods still run, with networking through the browser. See [Networking](https://browserpod.io/docs/understanding-browserpod/networking.md) for the differences.

## 2. Start from a template

Scaffold a project:

```bash
npm create browserpod-quickstart@latest
```

The CLI asks you to pick a template, name your project, and paste your API key. You can add or change the key later in `.env`.

| Template       | What it runs                                                                    |
| -------------- | ------------------------------------------------------------------------------- |
| **Basic**      | The Node.js REPL                                                                |
| **Bash shell** | An interactive bash shell                                                       |
| **Web server** | An Express server, with a live preview through a Portal (needs BrowserPod Edge) |

Install the dependencies and start the dev server:

```bash
cd <your-project-name>
npm install
npm run dev
```

Open the address it prints, for example <http://localhost:5173/>:

![Output of the basic template](https://browserpod.io/docs/assets/bp-quickstart.png)

Your Pod is running. Edit `src/main.js` to change what it runs; the dev server reloads the page as you save.

### Skip the prompts

Pass options to the command. npm needs a `--` before them:

```bash
npm create browserpod-quickstart@latest -- my-app -t vite-basic -k <your-key>
```

| Option                    | Description                                  |
| ------------------------- | -------------------------------------------- |
| `<project-name>`          | Name of the project folder                   |
| `-t`, `--template <name>` | Template: `vite-basic`, `bash` or `vite-web` |
| `-k`, `--api-key <key>`   | API key to save in `.env`                    |
| `--non-interactive`       | Fail instead of prompting for missing values |
| `-h`, `--help`            | Show all options                             |

## Or add BrowserPod to an existing app

### 1. Install the package

```bash
npm i @leaningtech/browserpod
```

### 2. Serve the page cross-origin isolated

BrowserPod needs the page to be [cross-origin isolated](https://browserpod.io/docs/understanding-browserpod/cross-origin-isolation.md). With Vite, add the two headers to `vite.config.js`:

`vite.config.js`

```js
import { defineConfig } from "vite";


export default defineConfig({
  server: {
    headers: {
      "Cross-Origin-Embedder-Policy": "require-corp",
      "Cross-Origin-Opener-Policy": "same-origin",
    },
  },
});
```

For other servers and for production, see [Serve your page cross-origin isolated](https://browserpod.io/docs/guides/hosting.md).

### 3. Boot a Pod and start a shell

Add an element for the terminal:

```html
<div id="console" style="height: 400px"></div>
```

Then boot a Pod with your key, and run bash in the terminal:

```js
import { BrowserPod } from "@leaningtech/browserpod";


const pod = await BrowserPod.boot({ apiKey: "your-key" });
const terminal = await pod.createDefaultTerminal(
  document.querySelector("#console")
);
await pod.run("bash", [], { terminal });
```

- [`boot`](https://browserpod.io/docs/reference/BrowserPod/boot.md) starts a Pod. With an API key it boots on the Edge network; without one, on the browser’s `fetch()`.
- [`createDefaultTerminal`](https://browserpod.io/docs/reference/BrowserPod/createDefaultTerminal.md) shows a terminal in the element you pass.
- [`run`](https://browserpod.io/docs/reference/BrowserPod/run.md) runs a program in the Pod, here an interactive bash shell.

Keep the key out of your source code: see [where to store the API key](https://browserpod.io/docs/understanding-browserpod/api-key.md#where-to-store-the-api-key).

## Next steps

- **Run code an agent writes:** [Write files to the Pod](https://browserpod.io/docs/guides/write-files-to-pod.md) and [Run programs in a Pod](https://browserpod.io/docs/guides/run-programs-in-a-pod.md).
- **Build an in-browser IDE or playground:** the [npm project tutorial](https://browserpod.io/docs/getting-started/expressjs.md) installs a project’s dependencies, starts its server and previews it through a Portal.
- **Run your own compiled programs:** [Installing the Rust toolchain](https://browserpod.io/docs/guides/installing-rust-toolchain.md).
- **Look up an API:** the [API reference](https://browserpod.io/docs/reference.md).

If something doesn’t work, see [Debugging BrowserPod](https://browserpod.io/docs/guides/common-errors.md), the [FAQ](https://browserpod.io/docs/more/FAQ.md), or ask on [Discord](https://discord.leaningtech.com/).
