# Quickstart

> From a new account to your first issue: create a workspace, connect Hetzner, create a project, install the SDK and send a test error.

This guide takes you from a new account to your first issue. Most of it is clicking through the Belvador app; the only code you write is the SDK setup in your own app.

## Before you start

- An email address for your Belvador account.
- An authenticator app on your phone (for example Google Authenticator, 1Password or Authy). Two-factor authentication is required before you connect Hetzner.
- A **Hetzner Cloud** account with a payment method. Hetzner bills the server to you at its hourly rate; Belvador is free during the beta.
- The app you want to monitor, and permission to change its code.

## 1. Create your account

1. On belvador.dev choose **Start free**.
2. Enter your name, email and a password, then confirm the email Belvador sends you (**Check your email**).
3. Sign in. With no workspace yet, Belvador opens **Create your workspace**.

## 2. Create a workspace

A workspace holds your projects, alerts, team and **one node** in your Hetzner account.

1. Enter a **Workspace name**.
2. Check the **Workspace address**: 3–40 characters, lowercase letters, digits and hyphens. It is part of every link and cannot be changed later.
3. Choose **Create workspace**.

## 3. Turn on two-factor authentication

Belvador asks you to **Protect your account** next. Two-factor is needed before you connect Hetzner or change roles, and sensitive actions ask for a fresh code later.

1. Scan the QR code with your authenticator app (or type the secret shown under it).
2. Enter the 6-digit code.
3. Save the **Recovery codes** somewhere safe. Each code works once and they are shown only now.

You can choose **Do this later**, but connecting Hetzner will ask for it. Details: [Account, two-factor and roles](https://belvador.dev/en/docs/account-security).

## 4. Connect Hetzner

In Belvador open **Node → Connect Hetzner**, then in Hetzner Console:

1. **Create a project named “Belvador”.** A separate project means the token can only touch Belvador's machine — keep your other servers elsewhere.
2. **Generate an API token**: in that project open **Security → API Tokens → Generate API token**, with **Read & Write** permission.
3. **Copy it now.** Hetzner shows the token only once.

Paste the token into Belvador and pick a **Token custody** mode:

- **Managed (recommended)** — the vault keeps the token encrypted, so resizing, rebuilding and deleting run automatically.
- **Strict** — the vault deletes the token as soon as the node is ready; later operations ask you for a temporary token. Only owners can choose Strict.

The token goes straight to Belvador's vault; it never passes through the Belvador app or its database. More: [Connect Hetzner and set up your node](https://belvador.dev/en/docs/node/connection).

## 5. Create the node

Choose **Create node**. Belvador picks the cheapest machine that fits — `cx23`, or the ARM `cax11` when `cx23` is sold out — in Falkenstein, Nuremberg or Helsinki, and shows each step: **Check token → Create firewall → Create server → Start server → Enroll agent → Harden host → Connect to edge → Install node software → Health check → Ready**.

In our own tests this took about 90 seconds; it can take longer when Hetzner is busy. You can leave the page — setup continues in the background. If a step fails, the timeline shows which one and offers **Retry from this step**.

The node opens no inbound ports, SSH included. It only connects out.

## 6. Create a project

1. Open **Projects → New project**.
2. Name the app and pick its platform: **JavaScript (browser)**, **React (Vite / SPA)**, **TanStack Start / Lovable**, **Node.js**, **Python** or **Other**.
3. Belvador shows the project's **DSN** and setup code right away.

Use one project per app. See [Projects and DSN](https://belvador.dev/en/docs/projects-and-dsn).

## 7. Install the SDK

Follow the setup shown on the project page, or the guide for your platform — the code is the same:

| Your app | Guide |
|---|---|
| Lovable app or TanStack Start | [TanStack Start and Lovable](https://belvador.dev/en/docs/sdk/tanstack-start) |
| React with Vite or another SPA setup | [React 18 and React 19](https://belvador.dev/en/docs/sdk/react) |
| Other browser JavaScript | [JavaScript in the browser](https://belvador.dev/en/docs/sdk/browser) |
| Cloudflare Worker | [Cloudflare Workers](https://belvador.dev/en/docs/sdk/cloudflare) |
| Node.js server | [Node.js](https://belvador.dev/en/docs/sdk/node) |
| Python | [Python](https://belvador.dev/en/docs/sdk/python) |

Working with an AI coding agent? The project page has **Paste into your AI agent**, and [Guide for AI agents](https://belvador.dev/en/docs/ai-agents) explains what the agent must keep intact.

## 8. Verify the connection

A first issue alone does not prove that every part of your app reports. The last step of **Setup** — and the project's **Connection** tab — show the check for your platform: run it once from each runtime (browser and, for TanStack Start, the server). Each runtime turns **Verified** within seconds; anything wrong shows as a problem with what to fix. See [Verify the connection](https://belvador.dev/en/docs/sdk/verify).

To see a real issue as well, trigger an error in your app, for example from a button handler:

```js
setTimeout(() => {
  throw new Error("Belvador test error");
}, 0);
```

It appears under **Issues** within a few seconds with its stack trace, tags and context.

> [!TIP]
> **Check intake path** on the Connection tab sends one event from your node through the public ingest path. It proves Belvador → node only, not your app. If it never arrives, the node is usually not connected — see [Troubleshooting](https://belvador.dev/en/docs/troubleshooting).

## Next steps

- Invite your team from **Settings → Members** — see [roles](https://belvador.dev/en/docs/account-security#workspace-roles).
- Connect a Telegram bot, Slack or your own email sender in [Alerts](https://belvador.dev/en/docs/alerts).
- Upload [source maps](https://belvador.dev/en/docs/source-maps) from CI so stack traces show your original code.
- Read [Data protection](https://belvador.dev/en/docs/privacy) before sending production data.
- Add [monitors](https://belvador.dev/en/docs/monitors/overview) for scheduled jobs, queues and workers, so a job that never runs is noticed too.