Quickstart

This guide walks you through deploying a sample web app to Keelson, opening it in a browser, and confirming that login protection is on by default.

1. Before you start

You will need:

A supported terminal — macOS or Linux with curl and openssl, or Windows 10/11 or Windows Server 2016+ with Windows PowerShell 5.1 or later. Windows PowerShell 5.1 and its CNG cryptography support are included with supported Windows versions.
A Keelson account — sign up at console.keelson.dev if you do not have one.
An AI agent that can use Agent Skills, such as Claude Code or Codex. The agent itself may require Node.js; the Keelson CLI does not.

2. Install the Keelson CLI

On macOS or Linux, run:

curl -fsSL https://keelson.dev/install.sh | sh

On Windows, open PowerShell and run:

irm https://keelson.dev/install.ps1 | iex

Both installers verify the release signature (ECDSA P-256) and the sha256 of the binary before installing it. If verification fails, the existing CLI is left unchanged. The default destination is ~/.keelson/bin/keelson on macOS and Linux, or %USERPROFILE%\.keelson\bin\keelson.exe on Windows. The Windows installer uses the operating system’s CNG cryptography and does not require OpenSSL.

The installer does not modify your PATH. On macOS or Linux, if keelson is not found, have the CLI append it to your shell config:

~/.keelson/bin/keelson doctor --fix-path

This only rewrites the config file, so your current shell is not affected yet. Restart the shell, or run the line doctor prints:

export PATH="$HOME/.keelson/bin:$PATH"

If you would rather not touch your shell config, run just the export — it applies for the current shell only.

On Windows, add %USERPROFILE%\.keelson\bin to your user Path in Edit environment variables for your account, then open a new PowerShell window. To use it only in the current PowerShell session, run:

$env:Path = "$env:USERPROFILE\.keelson\bin;$env:Path"

Once PATH is set, confirm the install:

keelson --version

keelson v0.1.0 (darwin/arm64)

Later updates are done with keelson upgrade.

The installer accepts these environment variables:

Variable	Purpose
`KEELSON_VERSION`	Install a specific version (e.g. `KEELSON_VERSION=v0.1.0`). Defaults to the current release
`KEELSON_INSTALL_DIR`	Change the install destination. Defaults to `~/.keelson/bin` on macOS/Linux and `%USERPROFILE%\.keelson\bin` on Windows
`KEELSON_DOWNLOAD_BASE`	Change the release download origin. Defaults to `https://dl.keelson.dev`

3. Log in to Keelson

Link this machine to your Keelson account:

keelson login

A browser opens with the login screen. Once you are logged in, return to the terminal. On machines without a browser, use keelson login --no-browser.

4. Get the sample app

We provide a small Node (TypeScript) AI chat app for this walkthrough. It contains no authentication or security code of its own.

Download the ZIP from ai-chat (GitHub) and extract it.
In a terminal, change into the extracted folder.

cd ~/Desktop/ai-chat

The sample app requires an API key from at least one supported AI provider: GEMINI_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY. Before deploying, create an env file in the sample app folder with one of those keys:

OPENAI_API_KEY=your-api-key

For the first deployment, the agent will need to run:

keelson deploy --new --secrets-from-env-file .env.keelson

Save the env file as .env.keelson. This command registers its values as Keelson secrets and excludes the file from the uploaded app.

5. Install the Agent Skill

Keelson lets your AI agent handle deploys and deploy status (log inspection) for you. The Skill it uses is bundled with the CLI — there is nothing extra to download.

From inside the sample app folder, run the command for the agent you use:

keelson install-agent claude-code

Target	Destination
`claude-code`	`.claude/skills/keelson/` in the current directory (`--global` installs to `~/.claude/skills/keelson/`)
`codex`	`~/.codex/skills/keelson/`
`cursor`	`~/.cursor/skills/keelson/`

claude-code installs into the current directory by default, so the Skill lands in the sample app folder you just entered. Pass --global to use it in every project instead.

6. Ask your AI agent to deploy

Open the extracted folder in your AI agent (Claude Code, for example).

No long commands are needed. Type one instruction into your agent:

Example: “Use the Skill to deploy this app to Keelson with the first-deployment command shown above.”

The agent reads keelson.yaml and starts the build and deploy. A deploy of this sample usually takes 3–6 minutes; most of that time is the build, including dependency installation. During the health check, the CLI shows whether it is waiting for permissions, routing, or the app to respond. When it finishes, the agent reports a public URL:

https://your-app-name.keelson.run/

You can also view the deployed app in the Keelson console.

A public URL is assigned when the app is created, so seeing the URL alone does not prove that the deployment succeeded. A command running without an interactive terminal can return while the deployment is still in progress, and the deployment may fail afterward. Before opening the URL, check the deployment ID reported by the deploy command:

keelson status <deploy-id>

If the deployment failed, this command shows the reason and the next action.

7. Verify the security

Open the deployed URL in a browser.

Logged-in browser: the app is shown.
Private window: the Keelson login screen is shown instead.

That is Security by Default. Keelson applies login protection without any authentication code in your app.