Skip to main content

Install SkillFlaw - Python

This guide covers the formal installation paths for the SkillFlaw Python backend runtime.

Use this page when your target runtime is based on:

  • docker/docker-compose-py.yml
  • make init
  • make init_db
  • make backend
  • make run_cli / make run_clic

If you need the TypeScript backend runtime instead, use Install SkillFlaw - TypeScript.

Choose the Python runtime when​

  • you want the repository's Python backend workflow
  • you need the Python source-development loop documented in README_PY.md
  • you want the Python Docker Compose stack with backend_py
  • you need the current Python-side local validation flow with make run_cli

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
  • create .env only when you want to pass extra runtime variables or local overrides to the backend container

Steps​

  1. Clone the repository:


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

  2. Optional: copy .env.example to .env when you need runtime overrides:


    _10
    cp .env.example .env

  3. Start the Python stack:


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

The Python compose path starts frontend, backend_py, doc, redis, pgsql, and the one-shot secret_init bootstrap service.

Default access points​

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

Success check​

Treat the installation as successful when all of the following are true:

  • docker compose -f docker/docker-compose-py.yml ps shows pgsql, redis, backend_py, 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

Install from source​

Use source installation for Python-backend development, debugging, frontend customization, or repository-based customization.

Source-installation prerequisites​

  • Python >=3.10,<3.14 (recommended 3.12)
  • uv >=0.4
  • Node.js 22 LTS and npm >=10.9
  • PostgreSQL
  • Redis only when SKILLFLAW_CACHE_TYPE=redis
  • SKILLFLAW_SECRET_KEY_FILE

Steps​

  1. Clone the repository:


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

  2. Copy .env.example to .env:


    _10
    cp .env.example .env

  3. Configure at least:

    • SKILLFLAW_DATABASE_URL
    • SKILLFLAW_SECRET_KEY_FILE

    If you use Redis cache, also configure:

    • SKILLFLAW_CACHE_TYPE=redis
    • SKILLFLAW_REDIS_HOST
    • SKILLFLAW_REDIS_PORT

  4. Install dependencies:


    _10
    make init

  5. Initialize the database:


    _10
    make init_db

  6. Start the backend:


    _10
    make backend

  7. Start the frontend:


    _10
    make frontend

Optional production-style local validation:


_10
make run_cli
_10
make run_clic

Success check​

  • make init completes without dependency errors
  • make init_db completes and initializes the default admin account
  • http://localhost:7860/health returns a healthy response after make backend
  • http://localhost:3000 opens the frontend after make frontend
  • http://localhost:7860 opens the application after make run_cli or make run_clic

Optional runtime dependencies​

OpenSandbox and OpenCode are optional for base platform startup. Prepare them only when you need Skill sandbox execution or AI-assisted workflows.

OpenSandbox​

Configure these repository-root .env settings when the Python backend needs OpenSandbox:

  • 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

For containerized installation, make sure the configured domain is reachable from inside backend_py.

OpenCode​

  • the Python source-install path expects opencode to be available in the same host environment as make backend
  • the Python Docker path uses docker/backend/Dockerfile, which already bundles opencode
  • SKILLFLAW_CONTAINER_OPENCODE_* is only intended for the containerized Python backend path

Default admin account​

The default admin account prepared by repository initialization is:

  • username: admin
  • password: Skillflaw@123321

Next steps​