# Quickstart

> Scaffold an app, preview it locally, deploy it, and connect over SSH in about five minutes

By the end of this guide you will have a live terminal app that anyone can reach with
`ssh your-app@voxal.sh`. It takes about five minutes.

**Prerequisites:**

- [Node.js](https://nodejs.org) 20 or newer
- An SSH client (built into macOS, Linux, and Windows)

<Steps>

<Step>

### Create an app

The fastest way to start is the project initializer. It scaffolds a polished React starter
and installs everything, including the `voxal` CLI as a local dependency.

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']}>

<Tab value="npm">

```bash
npm create voxal-app my-app
```

</Tab>

<Tab value="pnpm">

```bash
pnpm create voxal-app my-app
```

</Tab>

<Tab value="yarn">

```bash
yarn create voxal-app my-app
```

</Tab>

<Tab value="bun">

```bash
bun create voxal-app my-app
```

</Tab>

</Tabs>

It asks whether you want TypeScript or JavaScript, then creates `./my-app` with a working
app, a `voxal.json` manifest, and `dev`, `build`, and `deploy` scripts ready to run.

```bash
cd my-app
```

<Callout title="Prefer the core SDK?">
You can also install the CLI globally and run [`voxal init my-app`](/cli/init). That
scaffolds a smaller core-SDK app (plain `createApp`, no React) and links a project up front.
</Callout>

</Step>

<Step>

### Preview it locally

Run the app in your own terminal. It reloads every time you save.

```bash
npm run dev
```

Edit `app.jsx` (or `app.tsx`) and watch it update live. Press `q` or `Ctrl-C` to stop.

<Callout>
Local preview runs your code with Node for convenience, so it is not a perfect mirror of
production. Production runs your app in a hardened [sandbox](/platform/security) with stricter
network rules, so a request that works locally may behave differently once deployed. See
[voxal dev](/cli/dev) for the details.
</Callout>

</Step>

<Step>

### Deploy it

Ship the app to voxal.

```bash
npm run deploy
```

The first deploy opens your browser to sign in and link a **project** to your account. After
that, the CLI bundles your app, validates that it boots, and uploads it. When it finishes, it
prints the command to connect.

</Step>

<Step>

### Connect over SSH

That is it. Your app is live.

```bash
ssh my-app@voxal.sh
```

Anyone with an SSH client can run the same command. Every connection gets its own session of
your app.

</Step>

</Steps>

## What you shipped

- The CLI bundled your app and the SDK into a single file and confirmed it boots before
  uploading.
- Your app now runs in its own sandbox on voxal. It scales to zero when idle and boots again
  on the next connection.
- The SSH username (`my-app`) is your app's name, not a Unix account. No shell is ever exposed.

## Next steps

<Cards>
  <Card title="Build a UI with React" href="/guides/building-uis" description="Lay out a flexbox terminal interface with components and state." />
  <Card title="Fetch data from an API" href="/guides/fetching-data" description="Call external HTTP services from inside your app." />
  <Card title="Build a chat app" href="/guides/chat-app" description="A complete TUI: transcript, input box, commands, and a fetch." />
  <Card title="How voxal works" href="/how-it-works" description="The model your app runs in, end to end." />
</Cards>

<Callout title="Free plan">
The free plan includes 3 projects. Manage them with [`voxal projects`](/cli/projects), and
check your usage any time with `voxal whoami`.
</Callout>

---

Source: https://docs.voxal.sh/quickstart