voxal

The developer CLI for building and deploying interactive terminal apps that anyone can reach with ssh <app>@<host>. You write a small JavaScript app against @voxal/sdk; voxal deploy bundles it, validates that it boots, and ships it. No shell is ever exposed — each SSH session is wired to your sandboxed app.

Install

npm install -g @gurjas/voxal

This installs the voxal command. Requires Node.js >= 20.

The CLI validates your bundle in a real isolated-vm sandbox before upload — the same boundary the server runs apps in. isolated-vm is a native module and therefore an optional dependency: if it can't be installed or built on your machine, the CLI still installs and works; it just falls back to a lighter, non-executing bundle check and the server does the full validation on deploy.

Quick start

voxal login                 # sign in via your browser (device/polling flow)
voxal init myapp            # scaffold ./myapp (app.js + voxal.json + package.json)
cd myapp && npm i
voxal deploy                # link/create a project, bundle, validate, and ship it
ssh myapp@<host> -p 2222    # reach your running app

Commands

| Command | Description | | --- | --- | | voxal init [name] | Scaffold a new app in ./<name>. | | voxal login [--no-browser] | Log in via the browser. --no-browser prints the URL instead of opening it (handy on headless boxes). | | voxal logout | Log out and revoke this machine's token server-side. | | voxal whoami | Show the signed-in account, plan, and projects. | | voxal deploy [dir] [--name <n>] | Resolve a project, bundle + validate the app, and deploy. | | voxal projects [rm <name>] | List your projects, or delete one. |

Global flags

| Flag | Meaning | | --- | --- | | --dashboard <url> | Control-plane URL (default http://localhost:5173). | | --host <url> | Deploy-server URL (default http://localhost:8787). | | --token <t> | Use a raw token instead of the saved login (skips the account/project flow). |

URLs must be http(s); anything else is rejected before a request is made.

Configuration & security

• Your token is stored in ~/.voxal/config.json. The CLI enforces 0700 on the directory and 0600 on the file (re-applied on every write), so a leaked token isn't world-readable.
• voxal logout revokes the token server-side, so a stolen config can't be reused.
• Every network call is bounded by a timeout, so a stalled server can't hang the CLI.
• voxal deploy sends a sha256 of the bundle; the server and the bundle store both re-verify it, so the bundle can't be tampered with in flight or at rest.
• Bundles are capped at 5 MiB (warning past 4 MiB), matching the server.

License

MIT