voxal docs

Quickstart

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

Open
View as MarkdownOpen in ChatGPTOpen in Claude

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 20 or newer
  • An SSH client (built into macOS, Linux, and Windows)

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.

npm create voxal-app my-app
pnpm create voxal-app my-app
yarn create voxal-app my-app
bun create voxal-app my-app

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.

cd my-app

Prefer the core SDK?

You can also install the CLI globally and run voxal init my-app. That scaffolds a smaller core-SDK app (plain createApp, no React) and links a project up front.

Preview it locally

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

npm run dev

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

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 with stricter network rules, so a request that works locally may behave differently once deployed. See voxal dev for the details.

Deploy it

Ship the app to voxal.

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.

Connect over SSH

That is it. Your app is live.

ssh my-app@voxal.sh

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

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

Build a UI with React

Lay out a flexbox terminal interface with components and state.

Fetch data from an API

Call external HTTP services from inside your app.

Build a chat app

A complete TUI: transcript, input box, commands, and a fetch.

How voxal works

The model your app runs in, end to end.

Free plan

The free plan includes 3 projects. Manage them with voxal projects, and check your usage any time with voxal whoami.

Introduction

voxal is a platform for interactive terminal apps that anyone can run with a single SSH command, no install required

How voxal works

The host and sandbox split, the lifecycle of an SSH connection, and the model your app runs in

On this page

Create an appPreview it locallyDeploy itConnect over SSHWhat you shippedNext steps