Skip to main content

Install SkillFlaw

SkillFlaw provides two public installation paths:

  • Docker Compose for a complete local product stack
  • Source installation for development and debugging

Repository clone​

Before using either installation path, clone the repository locally:


_10
git clone https://github.com/cwinux/skillflaw.git
_10
cd skillflaw

Install with Docker Compose​

Use this path for a complete local product stack.

Prerequisites​

  • Docker Engine / Docker Desktop and Docker Compose are installed
  • No separate local PostgreSQL or Redis setup is required for the default compose path
  • The default compose path generates and persists the secret-key file automatically on first startup, so you do not need to prepare SKILLFLAW_SECRET_KEY_FILE separately
  • Create .env only when you want to pass extra runtime variables or local overrides to the backend container

Steps​

  1. Clone the repository if you have not already done so.

    • macOS:


      _10
      git clone https://github.com/cwinux/skillflaw.git
      _10
      cd skillflaw

    • Linux (Ubuntu/Debian):


      _10
      git clone https://github.com/cwinux/skillflaw.git
      _10
      cd skillflaw

  2. Optional: copy the repository-root .env.example (next to README.md and Makefile) to the repository-root .env if you want to provide extra runtime variables or local overrides.

    • macOS:


      _10
      cp .env.example .env

    • Linux (Ubuntu/Debian):


      _10
      cp .env.example .env

  3. Start the stack:


    _10
    docker compose -f docker/docker-compose.yml up -d

    On first startup, Docker Compose runs the one-shot secret_init service, generates a high-entropy secret key file, and persists it in the skillflaw_secret_data volume for backend reuse.

    The repository-root .env (that is, skillflaw/.env, next to README.md and Makefile) is optional in this path. Create it only when you want the backend container to read extra runtime variables or local overrides.

    In this Docker Compose path, you do not need to set SKILLFLAW_SECRET_KEY_FILE, SKILLFLAW_DATABASE_URL, SKILLFLAW_CACHE_TYPE, SKILLFLAW_REDIS_HOST, or SKILLFLAW_REDIS_PORT in .env unless you intentionally override defaults. Compose already wires the backend to bundled PostgreSQL and Redis and provisions the default secret file automatically.

  4. On a fresh PostgreSQL volume, the database container initializes the database in this order:

    This is handled automatically by the bundled PostgreSQL container and does not require a separate manually managed PostgreSQL or Redis setup for the default Compose path.

    1. sql/skillflow.sql
    2. data/postgresql/skillflaw_init_data.sql

  5. Open the services:

    • frontend: http://localhost:3001
    • backend health: http://localhost:7860/health
    • docs: http://localhost:3002

The compose stack starts frontend, backend, doc, redis, pgsql, and the one-shot secret_init bootstrap service. The backend reads /run/secrets/skillflaw_secret_key from the persistent skillflaw_secret_data volume.

Success check​

Docker Compose installation is successful when all of the following are true:

  • docker compose -f docker/docker-compose.yml ps shows pgsql, redis, backend, frontend, and doc running, while secret_init has completed successfully
  • http://localhost:7860/health returns a healthy response
  • http://localhost:3001 opens the SkillFlaw frontend
  • http://localhost:3002 opens the standalone docs site
  • you can sign in with the default admin account shown below

Common questions​

Do I need .env for the default Docker Compose path?​

No. .env is optional in the default compose workflow. Create it only when you want to override runtime variables that the backend container should read. The file location is skillflaw/.env at the repository root, not docker/.env.

Do I need to run make init_db when I use Docker Compose?​

No. make init_db is the source-installation database initialization entry. In the default compose workflow, the pgsql container initializes a fresh PostgreSQL volume automatically with sql/skillflow.sql and data/postgresql/skillflaw_init_data.sql.

Why does docker compose ps show secret_init as exited?​

That is expected. secret_init is a one-shot bootstrap service that runs only to create the default secret-key file inside skillflaw_secret_data on first startup. After it finishes successfully, it remains exited and does not need to stay running.

Install and deploy the docs service​

SkillFlaw docs are delivered as a standalone Docusaurus site. Deploy the docs service on a dedicated port, container, or hostname, and keep it mounted at /.

Docs service​

Choose the docs workflow that matches your goal:

  • make docs_dev: start the Docusaurus development server with hot reload while editing docs source
  • make docs_build: build root-based static output into docs/build
  • make docs_serve: rebuild standalone docs output and immediately start the local static docs service
  • make docs_start_only: start an existing built docs directory without rebuilding it first

For hot-reload authoring, use:


_10
make docs_dev docs_port=3001

For a production-style static build, run:


_10
make docs_build

This builds root-based static output into docs/build for standalone hosting.

To rebuild and immediately serve standalone docs output, use:


_10
make docs_serve docs_port=3001

This rebuilds standalone docs output and serves it on the selected port. With docs_port=3001, the local entry is http://localhost:3001/, and the Chinese homepage is http://localhost:3001/zh-CN.

If you already have a valid build and only want to start docs without rebuilding, use:


_10
make docs_start_only docs_port=3001 docs_start_dir=build

Set docs_start_dir to the existing build directory. For example, after make docs_build, use docs/build.

For a dedicated docs domain, route that hostname directly to the standalone docs service and keep the site mounted at /.

For the full standalone docs deployment workflow and command reference, see Build and serve the documentation site.

Default admin account​

After the repository initialization SQL has completed, the default admin account is:

  • username: admin
  • password: Skillflaw@123321

Python package distribution status​

SkillFlaw does not currently provide a public PyPI package for uv pip install skillflaw.

For a runnable environment today, use one of these paths:

  • Docker Compose, when you want the complete local product stack;
  • Source installation, when you want to run, debug, or develop from this repository.

Install from source​

Use this path to contribute to the repository, modify frontend code, update docs, or debug backend logic.

Source-installation prerequisites​

  • OS: macOS or Linux; Windows users should prefer WSL2 or a Dev Container
  • Git: latest stable version
  • make: available in PATH
  • Python: 3.12 recommended, officially supported range >=3.10,<3.14
  • uv: >=0.4
  • Node.js: 22 LTS recommended
  • npm: >=10.9
  • PostgreSQL: required, recommended 16, minimum compatible 14
  • Redis: required only when SKILLFLAW_CACHE_TYPE=redis, recommended 7, minimum compatible 6
  • yarn 1.22.x when you need the local docs workflow

The source-installation path requires a real secret-key file:

  • provide it through SKILLFLAW_SECRET_KEY_FILE
  • keep the file content as one line of high-entropy random text
  • keep it outside the repository
  • do not commit it to version control

The frontend package accepts node >=20.19.0, but repository documentation and docs tooling are aligned with Node.js 22 LTS. For consistent frontend and docs workflows, use Node.js 22 LTS.

Example installation commands for macOS​


_16
# Install Homebrew (if not installed)
_16
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
_16
_16
# Install Git, make, Python, uv, Node.js, PostgreSQL, Redis
_16
brew install git make python@3.12 uv node@22 postgresql@16 redis
_16
_16
# npm is included with node@22
_16
# Check versions
_16
git --version
_16
make --version
_16
python3 --version
_16
uv --version
_16
node --version
_16
npm --version
_16
psql --version
_16
redis-server --version

Example installation commands for Linux (Ubuntu/Debian)​


_36
# Update package manager
_36
sudo apt update
_36
_36
# Install base dependencies
_36
sudo apt install -y git make python3 python3-venv python3-pip curl build-essential ca-certificates gnupg lsb-release
_36
_36
# Install uv (using the official installer)
_36
curl -LsSf https://astral.sh/uv/install.sh | sh
_36
export PATH="$HOME/.local/bin:$PATH"
_36
_36
# Install Node.js 22 LTS (using NodeSource official script)
_36
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
_36
sudo apt install -y nodejs
_36
_36
# Install PostgreSQL 16 (using the official PGDG repository)
_36
sudo install -d /usr/share/postgresql-common/pgdg
_36
sudo curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
_36
sudo sh -c 'echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(. /etc/os-release && echo $VERSION_CODENAME)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
_36
sudo apt update
_36
sudo apt install -y postgresql-16
_36
_36
# Install Redis 7 (using the official Redis repository)
_36
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
_36
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(. /etc/os-release && echo $VERSION_CODENAME) main" | sudo tee /etc/apt/sources.list.d/redis.list > /dev/null
_36
sudo apt update
_36
sudo apt install -y redis
_36
_36
# Check versions
_36
git --version
_36
make --version
_36
python3 --version
_36
uv --version
_36
node --version
_36
npm --version
_36
psql --version
_36
redis-server --version

Steps​

  1. Clone the repository if you have not already done so.

    • macOS:


      _10
      git clone https://github.com/cwinux/skillflaw.git
      _10
      cd skillflaw

    • Linux (Ubuntu/Debian):


      _10
      git clone https://github.com/cwinux/skillflaw.git
      _10
      cd skillflaw

  2. Make sure the local toolchain is ready:

    • Python >=3.10,<3.14 (recommended: 3.12)

    • uv >=0.4

    • Node.js 22 LTS with npm >=10.9

    • make

    • macOS:


      _10
      python3 --version
      _10
      uv --version
      _10
      node --version
      _10
      npm --version
      _10
      make --version

    • Linux (Ubuntu/Debian):


      _10
      python3 --version
      _10
      uv --version
      _10
      node --version
      _10
      npm --version
      _10
      make --version

  3. Copy .env.example to .env.

    • macOS:


      _10
      cp .env.example .env

    • Linux (Ubuntu/Debian):


      _10
      cp .env.example .env

  4. Configure at least:

    • SKILLFLAW_DATABASE_URL
    • SKILLFLAW_SECRET_KEY_FILE

    If you want to use Redis cache, also configure:

    • SKILLFLAW_CACHE_TYPE=redis
    • SKILLFLAW_REDIS_HOST
    • SKILLFLAW_REDIS_PORT

    For the highest source-installation success rate, point SKILLFLAW_DATABASE_URL to a reachable PostgreSQL 16 instance. If Redis cache is enabled, point Redis settings to a reachable Redis 7 instance. PostgreSQL 14 and Redis 6 may work in some environments, but they are not the formally documented baseline.

    • macOS:


      _10
      cat >> .env <<EOF
      _10
      SKILLFLAW_SECRET_KEY_FILE=$HOME/.skillflaw/secret_key
      _10
      SKILLFLAW_DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<database>
      _10
      SKILLFLAW_CACHE_TYPE=redis
      _10
      SKILLFLAW_REDIS_HOST=<redis_host>
      _10
      SKILLFLAW_REDIS_PORT=<redis_port>
      _10
      EOF

    • Linux (Ubuntu/Debian):


      _10
      cat >> .env <<EOF
      _10
      SKILLFLAW_SECRET_KEY_FILE=$HOME/.skillflaw/secret_key
      _10
      SKILLFLAW_DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<database>
      _10
      SKILLFLAW_CACHE_TYPE=redis
      _10
      SKILLFLAW_REDIS_HOST=<redis_host>
      _10
      SKILLFLAW_REDIS_PORT=<redis_port>
      _10
      EOF

  5. Install dependencies:

    • macOS:


      _10
      make init

    • Linux (Ubuntu/Debian):


      _10
      make init

  6. Initialize the database:

    • macOS:


      _10
      make init_db

    • Linux (Ubuntu/Debian):


      _10
      make init_db

    make init installs dependencies and prepares the environment. make init_db creates the target PostgreSQL database when needed, initializes schema, imports exported init data, and prepares the default admin account.

    If the database referenced by SKILLFLAW_DATABASE_URL does not exist yet, make init_db tries to create it automatically before loading schema and init data. The PostgreSQL user in SKILLFLAW_DATABASE_URL must have CREATE DATABASE permission.

    If SKILLFLAW_SECRET_KEY_FILE does not exist in an interactive session, make init_db explains the requirement, can generate the file, and writes the resolved path back into .env.

  7. Choose the startup path that matches your goal:

    Development mode

    • macOS:

      Terminal A:


      _10
      make backend

      Terminal B:


      _10
      make frontend

    • Linux (Ubuntu/Debian):

      Terminal A:


      _10
      make backend

      Terminal B:


      _10
      make frontend

    make frontend starts the frontend development server. The default local development entrypoints are:

    • frontend: http://localhost:3000
    • backend health: http://localhost:7860/health

    Production-style local validation

    If you want to validate a runtime closer to the formal release shape from the source-install path, run this from the repository root:

    • macOS:


      _10
      make run_cli

      If you need a clean frontend rebuild before validation, run:


      _10
      make run_clic

    • Linux (Ubuntu/Debian):


      _10
      make run_cli

      If you need a clean frontend rebuild before validation, run:


      _10
      make run_clic

    In this mode, SkillFlaw builds the frontend static assets first and then serves the application through the backend. The default entrypoint is:

    • application: http://localhost:7860

    If you want to validate a fuller product-grade deployment chain, Docker Compose is still the recommended path.

  8. If you are editing docs, start the docs server as well:

    • macOS:


      _10
      make docs_dev
      _10
      # or
      _10
      make docs_build
      _10
      # or
      _10
      make docs_serve docs_port=3001
      _10
      # or
      _10
      make docs_start_only docs_port=3001 docs_start_dir=build

    • Linux (Ubuntu/Debian):


      _10
      make docs_dev
      _10
      # or
      _10
      make docs_build
      _10
      # or
      _10
      make docs_serve docs_port=3001
      _10
      # or
      _10
      make docs_start_only docs_port=3001 docs_start_dir=build

Success check​

Source installation is successful when all of the following are true:

  • make init finishes without dependency errors
  • make init_db completes and initializes the admin account
  • http://localhost:7860/health returns a healthy response after make backend
  • in development mode, http://localhost:3000 opens the SkillFlaw frontend after make frontend
  • in production-style local validation mode, http://localhost:7860 opens the application after make run_cli or make run_clic
  • you can sign in with the default admin account shown above

For deployment-oriented details on initialization, exported init data, and compose behavior, see SkillFlaw deployment installation.

Optional runtime dependencies for Skill execution​

OpenSandbox and OpenCode are not required to start the base frontend/backend platform. Prepare them before using Skill sandbox execution or AI-assisted features that depend on them:

  • OpenSandbox is the default backend for Skill sandbox execution in SkillFlaw.
  • OpenCode must be available on the server hosting the SkillFlaw backend when AI-assisted capability depends on opencode.

OpenSandbox prerequisites​

OpenSandbox can be either:

  • a self-hosted OpenSandbox server that you operate yourself, or
  • a SaaS OpenSandbox endpoint provided to your deployment.

In either form, the SkillFlaw backend must be able to reach it. SkillFlaw connects to OpenSandbox with these .env settings:

  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_DOMAIN
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_API_KEY
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_PROTOCOL
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_USE_SERVER_PROXY
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_REQUEST_TIMEOUT_SECONDS

When you also need to align the runtime images used for Skill execution, check:

  • SKILLFLAW_SKILL_SANDBOX_PYTHON_IMAGE
  • SKILLFLAW_SKILL_SANDBOX_TYPESCRIPT_IMAGE

Containerized installation​

  • The repository-root .env is read by the backend container, so OpenSandbox access settings must be written into skillflaw/.env.
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_DOMAIN must be an address that is reachable from inside the backend container.
  • If OpenSandbox runs on the host machine, Docker Desktop setups typically need host.docker.internal:8080 or another container-reachable address instead of localhost:8080.
  • If OpenSandbox is provided by a peer container or a remote service, use that service name, routable IP, or hostname.

Example:


_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_DOMAIN=host.docker.internal:8080
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_PROTOCOL=http
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_API_KEY=
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_USE_SERVER_PROXY=false
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_REQUEST_TIMEOUT_SECONDS=600

Source installation​

  • When the backend runs directly on the host, keep the OpenSandbox settings in the repository-root .env and point them to an address reachable from that host environment.
  • If OpenSandbox runs on the same host, localhost:8080 is a common configuration.
  • If OpenSandbox is remote or reachable through another network path, use the actual reachable host instead of assuming the loopback address will work.

Example:


_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_DOMAIN=localhost:8080
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_PROTOCOL=http
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_API_KEY=
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_USE_SERVER_PROXY=false
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_REQUEST_TIMEOUT_SECONDS=600

Starting a self-hosted OpenSandbox service​

  • If you use a self-hosted OpenSandbox service instead of SaaS, start OpenSandbox before starting SkillFlaw.
  • The repository scripts and notes explicitly reference opensandbox-server as the service process name, so a self-hosted installation must at least expose that command.
  • If you change ~/.sandbox.toml, execd_image, or related runtime-image settings, restart opensandbox-server before testing again.

_10
opensandbox-server

OpenSandbox usage rules in SkillFlaw​

  • Keep the OpenSandbox service reachable from the SkillFlaw backend.
  • Configure the Skill sandbox connection parameters before testing or running Skills.
  • Use a sandbox image and runtime limits that match your Skill language and execution requirements.
  • If you change the OpenSandbox runtime image or execd_image, restart the OpenSandbox server so the new configuration takes effect.

OpenCode prerequisites​

SkillFlaw invokes opencode run --pure --format json directly in the backend runtime. Install OpenCode in the same environment as the SkillFlaw backend, and ensure opencode is available in PATH before enabling AI-assisted Skill, Flow, or component workflows.

Containerized installation​

  • In the current Docker Compose path, the backend image is built locally from docker/backend/Dockerfile, and that image already bundles opencode.
  • The backend service in docker/docker-compose.yml is the only intended consumer of the repository-root .env entries named SKILLFLAW_CONTAINER_OPENCODE_*.
  • On backend container startup, SkillFlaw reads the repository-root .env and renders the container-side OpenCode runtime configuration from the SKILLFLAW_CONTAINER_OPENCODE_* variables.
  • These variables are only for the containerized backend's local OpenCode runtime; they are not outbound API parameters used by SkillFlaw itself.
  • If any derived SKILLFLAW_CONTAINER_OPENCODE_* setting is provided, SKILLFLAW_CONTAINER_OPENCODE_MODEL is required and must use the provider/model format.
  • For a custom provider, you typically also provide SKILLFLAW_CONTAINER_OPENCODE_PROVIDER_ID, SKILLFLAW_CONTAINER_OPENCODE_PROVIDER_NAME, SKILLFLAW_CONTAINER_OPENCODE_PROVIDER_NPM, and SKILLFLAW_CONTAINER_OPENCODE_API_KEY.
  • SkillFlaw invokes opencode from src/lfx/src so the local LFX AGENTS / opencode.json configuration chain is applied consistently.

Source installation​

  • Install opencode in the same host environment where you run make backend.
  • Configure the LLM provider, target model, and API key before starting SkillFlaw.
  • In the source-install path, do not use the SKILLFLAW_CONTAINER_OPENCODE_* variables; configure OpenCode directly in the host environment using OpenCode's own supported mechanism.

OpenCode usage rules in SkillFlaw​

  • Configure your OpenCode model/provider before starting AI-assisted features.
  • Keep OpenCode available in non-interactive CLI mode, because SkillFlaw runs opencode run --pure --format json and expects machine-readable output.
  • Use the same backend environment for SkillFlaw and OpenCode so that permission, model, and network settings stay consistent.
  • When you debug OpenCode prompts in a repository-based workflow, prefer the repository rules in AGENTS.md and use file-based context input for long instructions or reference material.

SkillFlaw does not currently define dedicated OpenCode connection variables in its own .env, so provider, model, and key settings must be supplied through OpenCode's own supported configuration mechanism in the same source or container runtime.