OpenStoryline Install

Install, configure, and start FireRed-OpenStoryline from source on a local machine. Use when a user asks to set up OpenStoryline, troubleshoot installation,...

Security Scan

The skill's requests and instructions are coherent with its stated purpose of installing/running FireRed-OpenStoryline from source; nothing in the package indicates misdirection or unexplained access needs.

Purpose & Capability

The name/description match the runtime instructions: cloning a GitHub repo, creating a Python venv, installing dependencies, downloading model/resource archives, filling config.toml, and starting services are all expected for a local install helper.

Instruction Scope

Instructions are focused on installation, configuration, verification, and starting services. They ask the agent to read README.md and config.toml (expected). Two minor issues to note: (1) download.sh pulls large model/resource archives from the network but the SKILL.md does not mention verifying checksums or sources; (2) it instructs filling API keys into config.toml — this is expected but users should avoid pasting secrets into public places. Otherwise there is no scope creep (no instruction to read unrelated system files or exfiltrate data).

Install Mechanism

This is an instruction-only skill with no install spec, which is lowest-risk. The included code files are zero-length placeholders and there is no binary download/install declared by the skill itself.

Credentials

The skill does not declare or require environment variables or credentials in its metadata. The instructions do ask users to provide LLM/VLM/TTS API keys in config.toml (expected for a local app that integrates external services). No unrelated secrets or service credentials are requested.

Persistence & Privilege

The skill is not always-enabled and does not request elevated platform privileges. It instructs running local servers as part of the app workflow, which is expected for this purpose.

Assessment

This skill appears to do what it says, but exercise normal caution before running installers and downloads: 1) Verify the GitHub repository URL and review scripts (especially download.sh) before running them; 2) Run installs in an isolated environment (repo-local .venv or container) and avoid running as root; 3) Be cautious when inserting API keys—store secrets securely and do not commit them to source control; 4) Prefer verifying checksums or trusted release sources for large model/resource downloads; 5) The included code files in the package are empty placeholders—inspect the real repo's scripts before executing. If you need higher assurance, ask for the download.sh contents and checksums or run the steps manually with supervision.

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:

  brew install ffmpeg wget unzip
  

• Debian/Ubuntu:

  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:

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

If no supported interpreter already exists, peferr conda fallback:

conda create -y -n openstoryline-py311 python=3.11
conda run -n openstoryline-py311 python --version
conda run -n openstoryline-py311 python -m venv .venv

After a supported interpreter is found, always create a repo-local .venv and continue using .venv/bin/python for install, config validation, and service startup.

Do not duplicate the rest of the workflow for pyenv or conda unless the user explicitly asks to stay inside a conda environment.

Clone repository

If you don't have a local repository yet, clone the repository first.

git clone https://github.com/FireRedTeam/FireRed-OpenStoryline.git
cd FireRed-OpenStoryline

Preferred Install Path

From the repo root:

/path/to/python -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
bash download.sh

Notes:

• download.sh pulls both model weights and a large resource archive. It can take a long time and may resume after network drops.
• The resource download is required for a full local run, not just the Python package install.

Configuration

Before starting the app, update config.toml.

You can use scripts/update_config.py.

At minimum, fill:

.venv/bin/python scripts/update_config.py --config ./config.toml --set llm.model=REPLACE_WITH_REAL_MODEL
.venv/bin/python scripts/update_config.py --config ./config.toml --set llm.base_url=REPLACE_WITH_REAL_URL
.venv/bin/python scripts/update_config.py --config ./config.toml --set llm.api_key=sk-REPLACE_WITH_REAL_KEY

.venv/bin/python scripts/update_config.py --config ./config.toml --set vlm.model=REPLACE_WITH_REAL_MODEL
.venv/bin/python scripts/update_config.py --config ./config.toml --set vlm.base_url=REPLACE_WITH_REAL_URL
.venv/bin/python scripts/update_config.py --config ./config.toml --set vlm.api_key=sk-REPLACE_WITH_REAL_KEY

Optional but common:

• search_media.pexels_api_key for searching media
• TTS provider keys under generate_voiceover.providers.* (choose one provider)

Verification

Run these checks before saying installation is complete:

.venv/bin/pip check
PYTHONPATH=src .venv/bin/python -c "from open_storyline.config import load_settings; load_settings('config.toml'); print('config_ok')"

Also confirm key resources exist:

test -f .storyline/models/transnetv2-pytorch-weights.pth
test -d resource/bgms

Start Services

There are two common paths. These are long-running processes. Do not wait for them to exit normally. Treat successful startup log lines or confirmed listening ports as success, and keep the services running in separate shells/sessions as needed.

Manual start:

PYTHONPATH=src .venv/bin/python -m open_storyline.mcp.server

In a second shell:

PYTHONPATH=src .venv/bin/python -m uvicorn agent_fastapi:app --host 127.0.0.1 --port 8005

Expected Outputs

After a successful install:

• .venv/ exists
• MCP listens on the configured local port (commonly 127.0.0.1:8001)
• Web listens on the configured web port (commonly 127.0.0.1:8005, though run.sh defaults may differ)

Common Problems

download.sh is slow or interrupted

Symptom:

• Large downloads stall or reconnect

Fix:

• Let wget continue; it supports resume behavior here
• Verify extracted outputs instead of trusting the progress meter

Web/MCP server fails to bind

Symptom:

• operation not permitted while binding 127.0.0.1 or 0.0.0.0

Fix:

• In agent sandboxes, request permission to open local listening ports
• Prefer 127.0.0.1 over 0.0.0.0 unless external access is required

Response Pattern

When reporting status to the user, separate:

• what is installed
• what is still downloading
• what config is still missing
• what address the service is listening on

Do not say "installation complete" if only the Python packages are installed but the resource bundle is still missing.