---
name: quackshell-alpha
description: Use when an agent needs to expose a local HTTP server, generated static preview, app, report, video, PDF, or other browser-viewable local artifact through the Quackshell alpha relay using quackshell-cli-alpha. Also use when the user says QuackShow, asks for Quack Shell links, or asks to "show me" local work in a browser.
---

# Quackshell Alpha

Quackshell Alpha turns a local HTTP server into a temporary public browser URL through the alpha relay. Use it when an alpha tester needs to inspect live local work from a remote agent.

Users may refer to Quackshell as "QuackShow" because speech-to-text often hears it that way, or as "Quack Shell links." If the user asks to "show me" a local app, preview, file, video, PDF, report, or generated artifact in a browser, consider Quackshell Alpha CLI as the solution.

## Core Rule

Keep the project being served unaware of Quackshell. Do not add Quackshell-specific routing, session IDs, SDK calls, relay URLs, or asset handling to the app. Serve the app or artifacts normally from localhost, using ordinary relative URLs.

## Installation

If the user asks how to install Quackshell Alpha, use the hosted installer:

```bash
curl -fsSL https://quackshell.com/install/alpha.sh | sh
```

Manual install:

```bash
# macOS: brew install pipx
# Debian/Ubuntu: sudo apt install pipx
pipx ensurepath
pipx install --python python3.12 --force https://quackshell.com/downloads/alpha/quackshell_cli_alpha-0.7-py3-none-any.whl
```

Confirm the CLI:

```bash
quackshell-cli-alpha --version
```

Install this Codex skill globally:

```bash
quackshell-cli-alpha install-skill codex --scope user
```

Install it in the current project:

```bash
quackshell-cli-alpha install-skill codex --scope local
```

Uninstall:

```bash
quackshell-cli-alpha uninstall-skill codex --scope user
quackshell-cli-alpha uninstall-skill codex --scope local
pipx uninstall quackshell-cli-alpha
```

## Workflow

1. Start or identify the local HTTP server.
   - Use the project's normal dev server when it has one.
   - For static files, especially videos, PDFs, or large assets, use Quackshell Alpha's range-capable static server instead of `python3 -m http.server`.
   - Confirm the local URL works before exposing it.

Range-capable static server:

```bash
quackshell-cli-alpha serve-static --directory <preview-dir> --port <port>
```

Use this for MP4/video previews because browsers rely on `Range` requests. A healthy video request through Quackshell should return `206 Partial Content` for the media file.

For video previews, consider creating a smaller preview copy before exposing it. Downscale or reduce bitrate when the user only needs to inspect content, timing, layout, or motion. Full-resolution or high-bitrate videos can stall over the relay even with byte ranges. Keep full resolution only when the user explicitly asks to inspect the original quality or exact pixels.

Example downscaled preview:

```bash
ffmpeg -y -i input.mp4 -vf "scale='min(1280,iw)':-2" -c:v libx264 -preset veryfast -crf 24 -c:a aac -b:a 128k -movflags +faststart preview.mp4
```

2. Get a Quackshell Alpha token.
   - Prefer an existing `QUACKSHELL_ALPHA_API_TOKEN` environment variable.
   - If no alpha environment token is set and `./quackshell-alpha.key` exists in the current directory, `quackshell-cli-alpha` will read it automatically.
   - `quackshell-alpha.key` is a shell-style properties file and should contain `QUACKSHELL_ALPHA_API_TOKEN=...`.
   - If no alpha token is available, ask the user for an alpha token.
   - Never commit, log, or repeat the token in a final response.

3. Confirm the Quackshell Alpha CLI is available.

```bash
command -v quackshell-cli-alpha
```

If `quackshell-cli-alpha` is not installed or not on `PATH`, ask the user to install it before continuing.

4. Start the Quackshell Alpha CLI.

```bash
quackshell-cli-alpha --port <port>
```

If the token is not already in the environment:

```bash
QUACKSHELL_ALPHA_API_TOKEN="<token>" quackshell-cli-alpha --port <port>
```

5. Give the relay URL to the user.
   - The public URL printed by `quackshell-cli-alpha` is the main output the user needs.
   - Send that URL to the user as soon as it is ready, unless you are still fixing an obvious startup failure.
   - The URL remains live only while the CLI process stays connected.
   - Keep the local server and `quackshell-cli-alpha` running while the user reviews the work.

6. Stop the Quackshell Alpha CLI when the preview is no longer needed.

## Notes

- The CLI writes the public URL to stdout and runtime logs to stderr.
- If exposing a generated artifact, create a small static preview page when that gives the user a clearer browser experience.
- If an MP4 returns `206 Partial Content` but does not become ready in the browser, the MP4 metadata may be late in the file. If `ffmpeg` is available, create a preview copy with faststart and serve that copy:

```bash
ffmpeg -y -i input.mp4 -c copy -movflags +faststart preview.mp4
```

- Do not expose folders or apps that contain secrets unless the user explicitly approves that risk.
- If a browser tool is available, open the Quackshell URL to verify the preview loads before sending it to the user.
