# Openstoryline Install

Install, configure, and start FireRed-OpenStoryline from source on a local machine.

- Repository: https://github.com/FireRedTeam/FireRed-OpenStoryline (3606 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-07-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add FireRedTeam/FireRed-OpenStoryline --skill openstoryline-install -g -a claude-code -y`
Codex: `npx skills add FireRedTeam/FireRed-OpenStoryline --skill openstoryline-install -g -a codex -y`
Cursor: `npx skills add FireRedTeam/FireRed-OpenStoryline --skill openstoryline-install -g -a cursor -y`
Gemini CLI: `npx skills add FireRedTeam/FireRed-OpenStoryline --skill openstoryline-install -g -a gemini-cli -y`

## Description

Install, configure, and start FireRed-OpenStoryline from source on a local machine. Use when a user asks to set up OpenStoryline, troubleshoot installation, download required resources, fill config.toml API keys, or launch the MCP and web services, as well as Chinese requests like “安装 OpenStoryline”, “配置 OpenStoryline”, “启动 OpenStoryline”, “把 OpenStoryline 跑起来”, “修复 OpenStoryline 安装问题”, or “排查 OpenStoryline 启动失败”.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# OpenStoryline Install

Use this skill when the task is to install or repair a local source checkout of FireRed-OpenStoryline.

Keep the workflow deterministic:

1. Confirm the repo path and read the current README.md and config.toml.
2. Detect local prerequisites before changing anything.
3. Prefer a local `venv` install unless the user explicitly asks for Docker or `conda`.
4. Download resources only after Python dependencies succeed.
5. Validate imports and config loading before claiming success.
6. This skill assumes macOS, Linux, or WSL with a POSIX shell.

## What This Skill Covers

- Clone the GitHub repo if needed
- Create a Python environment
- Install Python dependencies
- Download `.storyline` models and `resource/` assets
- Fill `config.toml` model settings
- Start MCP and web servers
- Explain common installation/documentation gaps

## Preconditions

Check these first:

- `git`
- Python `>= 3.11`
- `ffmpeg`
- `wget`
- `unzip`

Optional:

- `docker`
- `conda`

If `ffmpeg`, `wget`, or `unzip` are missing, install them through the OS package manager before continuing.

Examples:

- macOS with Homebrew:
  ```bash
  brew install ffmpeg wget unzip
  ```

- Debian/Ubuntu:
  ```bash
  sudo apt-get update
  sudo apt-get install -y ffmpeg wget unzip
  ```

If no supported package manager or permission is available, stop and report the missing system dependency clearly.

## Interpreter selection

First prefer any interpreter that already exists and passes version checks:

1. A system Python `>= 3.11`
2. An already available conda Python `>= 3.11`
3. An already available pyenv Python `>= 3.11`, but only if basic stdlib modules work

Validate candidate interpreters before using them:

```bash
/path/to/python -c "import ssl, sqlite3, venv; print('stdlib_ok')"
```

If no supported interpreter already exists, peferr conda fallback:

The rest: https://github.com/FireRedTeam/FireRed-OpenStoryline/blob/HEAD/.claude/skills/openstoryline-install/SKILL.md