Skip to main content

Install SkillFlaw

This guide covers the supported SkillFlaw installation paths for Docker, source, and local development.

Delivery modes​

  • Docker installation: run the packaged local stack from docker/docker-compose.yml
  • Source installation: run the product directly from the repository
  • Development installation: use the same repository workflow, with make init for dependencies and make init_db for database initialization

Docker installation​

SkillFlaw ships with docker/docker-compose.yml that starts these services:

  • frontend
  • backend
  • doc
  • redis
  • pgsql

The default delivery sources are:

  • frontend: ghcr.io/cwinux/skillflaw_frontend:latest
  • doc: ghcr.io/cwinux/skillflaw_docs:latest
  • backend: built locally from docker/backend/Dockerfile, with the default local tag skillflaw_backend_local:latest

Docker prerequisites​

  • Install Docker Engine or Docker Desktop
  • Install the docker compose CLI plugin
  • The default Docker path does not require a separate local PostgreSQL, Redis, or SKILLFLAW_SECRET_KEY_FILE
  • Create the repository-root .env only when you want to provide extra runtime variables or local overrides to the backend container

Before starting the stack:

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

  2. Run docker compose -f docker/docker-compose.yml up -d.

    On first startup, 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 the default Docker path. Create it only when you want the backend container to read extra runtime variables or local overrides.

    In the default Compose workflow, database and Redis connectivity are already defined in docker/docker-compose.yml, so you normally 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 the bundled services.

The backend container reads the secret-key file from /run/secrets/skillflaw_secret_key in the persistent skillflaw_secret_data volume.

On a fresh PostgreSQL volume, the database container applies these files in order:

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

Default access points:

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

Docker success check​

Treat the default Docker installation as 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

Docker common questions​

Does the default Docker path require .env?​

No. .env is optional in the default compose workflow. Create it only when you want to supply extra runtime variables or local overrides to the backend container. The file location is skillflaw/.env at the repository root, not docker/.env.

Does the default Docker path require make init_db?​

No. make init_db is the source-installation 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 is secret_init exited after startup?​

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

Source installation​

Use source installation when you want to run the product directly from the repository:

Source-installation prerequisites​

  • Prepare SKILLFLAW_DATABASE_URL
  • Prepare SKILLFLAW_SECRET_KEY_FILE
  • Keep the SKILLFLAW_SECRET_KEY_FILE content as a single line of high-entropy random text, outside the repository, and excluded from version control
  • PostgreSQL is required, recommended 16, minimum compatible 14
  • Redis is required when SKILLFLAW_CACHE_TYPE=redis, recommended 7, minimum compatible 6

If the secret-key file does not exist, make init_db explains the requirement and can generate it interactively.

  1. Copy .env.example to .env.
  2. Configure SKILLFLAW_DATABASE_URL.
  3. Configure SKILLFLAW_SECRET_KEY_FILE.
  4. Run make init.
  5. Run make init_db.
  6. Run make backend and make frontend.

If you are updating documentation, choose the docs workflow that matches your goal, such as make docs_dev, make docs_build, make docs_serve docs_port=3001, or make docs_start_only docs_port=3001 docs_start_dir=build.

Database initialization​

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

If the PostgreSQL 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.

When running interactively, make init_db can create a missing secret key file and persists the resolved SKILLFLAW_SECRET_KEY_FILE path back to .env.

The initialized dataset also retains the exported admin source account information in data/postgresql/skillflaw_init_data.sql.

Optional runtime dependencies for Skill execution​

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

OpenSandbox prerequisites​

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

Containerized installation​

  • The backend container reads the repository-root .env, so OpenSandbox endpoint, protocol, and credential settings must be written into skillflaw/.env.
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_DOMAIN must be reachable from inside the backend container. If OpenSandbox runs on the host machine, do not keep localhost:8080 in the containerized path.
  • Docker Desktop setups commonly use host.docker.internal:8080; peer-container and remote-service deployments should use the corresponding service name, IP, or hostname.

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.

Starting a self-hosted OpenSandbox service​

  • For self-hosted OpenSandbox, start the service before starting SkillFlaw.
  • The repository scripts and notes explicitly reference opensandbox-server as the service process name. If you change ~/.sandbox.toml or execd_image, restart that service before testing again.

_10
opensandbox-server

OpenCode prerequisites​

SkillFlaw invokes opencode run --pure --format json directly inside the backend runtime.

Containerized installation​

  • The default Compose backend 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.

Configuration note​

  • OpenCode does not require a separate daemon; SkillFlaw invokes the CLI on demand.
  • 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.

Default admin account​

The default admin account prepared by repository initialization is:

  • username: admin
  • password: Skillflaw@123321

When make init_db runs, the admin password is recalculated with the current SKILLFLAW_SECRET_KEY_FILE, so password hashes from another environment are never reused directly.

Initialization data export​

Run make export_db_init_data to regenerate data/postgresql/skillflaw_init_data.sql.

The export intentionally excludes operational or sensitive tables such as:

  • sf_job
  • sf_message
  • sf_transaction
  • sf_vertex_build
  • sf_config
  • sf_variable
  • sf_apikey
  • sf_user_chat_session

Only the admin row is preserved in sf_user, and sensitive JSON/configuration fields are scrubbed before writing SQL.