Skip to content
Keelson
Console →
Website →
Asking an AI? Paste this URL https://keelson.dev/llms.txt

Quickstart

Deploy a sample app to Keelson and check that only signed-in users can open it.

  • Time: about 15 minutes, including the build.
  • What you need: a Keelson account and a terminal for running commands. The sample does not need API keys for any external services.
  • What success looks like: you see a greeting after signing in, while a private browser window where you are not signed in shows the login page.

This guide uses Claude Code, Codex, or Cursor to deploy the app. You can also deploy directly with the CLI: skip step 3 and run the CLI command in step 4.

If you do not have a Keelson account, create one in the Keelson console.

1. Install the CLI and sign in

Section titled “1. Install the CLI and sign in”

The Keelson CLI lets you sign in and deploy from your terminal. Select your operating system and run the install command.

Terminal window
curl -fsSL https://keelson.dev/install.sh | sh
If the keelson command is not found

The installer does not change PATH, the list of places your terminal looks for commands. Add this line to ~/.zshrc or ~/.bashrc, then reopen your terminal:

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

Next, run the login command. Your browser opens so you can sign in with your Keelson account.

Terminal window
keelson login

2. Download the sample app

Section titled “2. Download the sample app”
  1. Download the sample app (ZIP).
  2. Extract the ZIP file.
  3. Open the extracted keelson-hello folder in Claude Code, Codex, or Cursor. If you are not using an AI agent, open a terminal in that folder.
See the sample code
main.py
from html import escape


from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse


app = FastAPI()


@app.get("/", response_class=HTMLResponse)
def index(request: Request):
    email = escape(request.headers.get("X-Keelson-User-Email") or "Guest")
    return f"""
    <!doctype html>
    <html lang="en"><body style="font-family: sans-serif; padding: 2rem">
      <h1>Hello, {email}</h1>
      <p>This app is running on Keelson.</p>
    </body></html>
    """
requirements.txt
fastapi
uvicorn
keelson.yaml
slug: hello
runtime: python-slim
command: "uvicorn main:app --host 0.0.0.0 --port $PORT"
db:
  mode: none

The app reads the signed-in user’s email address from a header supplied by Keelson and displays it. It contains no authentication code.

3. Install the Agent Skill

Section titled “3. Install the Agent Skill”

The Agent Skill gives your AI agent Keelson configuration and deployment instructions. It comes with the Keelson CLI. Open a terminal in the extracted keelson-hello folder, select your agent, and run the command.

Terminal window
keelson install-agent claude-code --global

With --global, the skill is available in your other projects too. Without it, the skill is installed only in the current project.
Install the Skill from the public repository

Choose exactly one installation method: keelson install-agent, the Claude Code plugin, or npx skills add. Combining methods can create two copies of the same Skill or cause one installation to overwrite the other.

In Claude Code, add the marketplace and install the plugin:

/plugin marketplace add keelsonhq/skills
/plugin install keelson@keelson-skills

For other agents, use:

Terminal window
npx skills add keelsonhq/skills

These methods install only the Skill. You still need to install the CLI and sign in as described in step 1. A Skill installed as a Claude Code plugin is not updated by keelson login; it follows Claude Code plugin updates instead.

See CLI commands for installation locations and how to update the skill.

4. Ask the agent to deploy

Section titled “4. Ask the agent to deploy”

Send this request in your agent’s chat:

Deploy this app to Keelson.

The agent starts the deployment. The first deployment takes a few minutes. When it starts, you receive a deployment ID and an app URL in this format:

https://<workspace>--hello.keelson.run

If you are not using an AI agent, run this in the keelson-hello folder:

Terminal window
keelson deploy --new

The URL is issued before deployment finishes, so the app may still be building or starting when it appears. Before opening the URL, check the status. Replace <deploy-id> with the ID shown when deployment started.

Terminal window
keelson status <deploy-id>

For example, for ID d1, run keelson status d1. A result of status: completed means the deployment process has finished. Continue to step 5 to check that you can actually open the app.

Statuses such as queued, building_image, or starting mean the deployment is still in progress. Wait a little and run the same command again. failed or rolled_back means it did not succeed: check the reason and suggested next action. See Troubleshooting for help.

5. Check the app and login protection

Section titled “5. Check the app and login protection”
  1. Open the app URL in your browser. Sign in to Keelson if prompted. Check that the page shows “Hello, …” and the text below it.
  2. Open the same URL in a private or incognito window where you are not signed in to Keelson. You should see the Keelson login page instead of the app.

Seeing “Guest” does not mean you are signed out. The sample displays “Guest” when your login method does not provide an email address to the app.

You now have an app at its own URL that only signed-in users can open. It also appears in the Keelson console.

Next steps

Section titled “Next steps”