Skip to main content

Install SkillFlaw - TypeScript

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

Use this page when your target runtime is based on:

  • docker/docker-compose-ts.yml
  • make ts_install_backend
  • make ts_init_db
  • make ts_backend
  • make ts_backend_verify
  • make ts_lfx_build / make ts_lfx_test
  • make ts_tool_build / make ts_tool_test

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

Choose the TypeScript runtime when​

  • you want the repository's TypeScript backend workflow
  • you need the TypeScript source-development loop documented in README_TS.md
  • you want the TypeScript Docker Compose stack with backend_ts
  • you need TypeScript package validation for backend, LFX, or tool packages

Install with Docker Compose​

Use this path for a complete local product stack.

Prerequisites​

  • Docker Engine / Docker Desktop and Docker Compose are installed
  • the repository-root .env is optional unless you need TypeScript runtime overrides
  • this path provisions a dedicated TypeScript database through SKILLFLAW_TS_DATABASE_URL

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 TypeScript stack:


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

On first startup, this path bootstraps a dedicated TypeScript database, creates the secret-key file in skillflaw_secret_ts_data, runs db_init_ts, exports TypeScript bootstrap data through db_init_export_ts, and finishes with the one-shot stack_check_ts verification service.

Default access points​

  • frontend: http://localhost:3003
  • backend health: http://localhost:7861/health
  • docs: http://localhost:3004

Success check​

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

  • docker compose -f docker/docker-compose-ts.yml ps shows pgsql, redis, backend_ts, frontend, and doc running, while secret_init, db_init_ts, db_init_export_ts, and stack_check_ts have completed successfully
  • docker compose -f docker/docker-compose-ts.yml logs stack_check_ts ends with [backend_ts] ok, [frontend] ok, and [doc] ok
  • http://localhost:7861/health returns a healthy response
  • http://localhost:3003 opens the SkillFlaw frontend
  • http://localhost:3004 opens the standalone docs site

Install from source​

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

Source-installation prerequisites​

  • Node.js 22 LTS and npm >=10.9
  • PostgreSQL
  • SKILLFLAW_TS_DATABASE_URL
  • SKILLFLAW_SECRET_KEY_FILE
  • SKILLFLAW_TS_TEST_DATABASE_URL only when tests are needed

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_TS_DATABASE_URL
    • SKILLFLAW_SECRET_KEY_FILE
    • SKILLFLAW_TS_TEST_DATABASE_URL only when tests or package validation are in scope

    If you use Redis cache, also configure:

    • SKILLFLAW_CACHE_TYPE=redis
    • SKILLFLAW_REDIS_HOST
    • SKILLFLAW_REDIS_PORT

  4. Install TypeScript backend dependencies:


    _10
    make ts_install_backend

  5. Initialize the TypeScript backend database:


    _10
    make ts_init_db

  6. Start the backend:


    _10
    make ts_backend

  7. Start the frontend:


    _10
    make frontend

Optional package validation:


_10
make ts_backend_verify
_10
make ts_lfx_build
_10
make ts_lfx_test
_10
make ts_tool_build
_10
make ts_tool_test

Success check​

  • make ts_install_backend completes without dependency errors
  • make ts_init_db completes successfully
  • http://localhost:7860/health returns a healthy response after make ts_backend
  • http://localhost:3000 opens the frontend after make frontend
  • the relevant TypeScript validation commands pass when they are in scope

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 TypeScript 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 the repository-local TypeScript backend flow, point them to an address reachable from the host environment where make ts_backend runs.

OpenCode​

  • the TypeScript runtime expects opencode to be available in the same host environment as make ts_backend
  • this documented repository path does not use SKILLFLAW_CONTAINER_OPENCODE_*
  • the TypeScript backend invokes opencode from src/lfx/src

Default admin account​

The default admin account prepared by repository initialization is:

  • username: admin
  • password: Skillflaw@123321

Next steps​