Skip to main content

Local development deployment

This guide describes the source-based local development workflow for SkillFlaw.

Prerequisites​

Before starting, install these tools:

  • git
  • make
  • uv
  • Node.js and npm
  • Docker Desktop or Docker Engine if you also validate the Compose deployment path

1. Prepare the source workspace​

Clone the source tree and enter the workspace:


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

Copy the environment template and fill in required values:


_10
cp .env.example .env

Verify the following mandatory variables before initialization:

  • SKILLFLAW_DATABASE_URL
  • SKILLFLAW_SECRET_KEY_FILE
  • any API keys required by the flows you want to test

Local .env configuration checklist​

Define the core infrastructure settings explicitly in .env to keep the local environment deterministic and reproducible.

PostgreSQL​

PostgreSQL is required for local backend development. Confirm SKILLFLAW_DATABASE_URL points to a reachable local or remote PostgreSQL instance, for example:


_10
SKILLFLAW_DATABASE_URL=postgresql://skillflaw:skillflaw@localhost:5432/skillflaw

If the database named in SKILLFLAW_DATABASE_URL does not exist yet, make init_db will try to create it automatically before loading schema and initialization data. The PostgreSQL user in the URL must have CREATE DATABASE permission.

If you also run backend tests against PostgreSQL, set a dedicated test database as well:


_10
SKILLFLAW_TEST_DATABASE_URL=postgresql://skillflaw_test:123456@localhost:5432/skillflaw_test

Redis​

If your local runtime uses Redis caching, set the cache mode and Redis connection explicitly:


_10
SKILLFLAW_CACHE_TYPE=redis
_10
SKILLFLAW_REDIS_HOST=127.0.0.1
_10
SKILLFLAW_REDIS_PORT=6379
_10
SKILLFLAW_REDIS_DB=0
_10
SKILLFLAW_REDIS_CACHE_EXPIRE=3600
_10
SKILLFLAW_REDIS_PASSWORD=

For environments without Redis, set SKILLFLAW_CACHE_TYPE to a non-Redis mode such as memory and do not configure the backend to connect to a Redis instance.

Store endpoints​

Store-related settings are only needed when you validate store integration or upload/download flows that depend on the remote store service. When those flows are part of your local verification scope, configure at least:


_10
SKILLFLAW_STORE_URL=
_10
SKILLFLAW_DOWNLOAD_WEBHOOK_URL=
_10
SKILLFLAW_LIKE_WEBHOOK_URL=

If you are not testing store features locally, you can leave these values empty.

Local file stores​

For source-based local development, keep the storage engines explicit so workflow files, skill files, pictures, and temporary exports all land in predictable local directories:


_10
SKILLFLAW_FLOW_STORE_TYPE=local
_10
SKILLFLAW_FLOW_STORE_LOCAL_PATH=~/data/skillflow/storage/flow
_10
SKILLFLAW_SKILL_STORE_TYPE=local
_10
SKILLFLAW_SKILL_STORE_LOCAL_PATH=~/data/skillflow/storage/skill
_10
SKILLFLAW_PIC_STORE_TYPE=local
_10
SKILLFLAW_PIC_STORE_LOCAL_PATH=~/data/skillflow/storage/pic
_10
SKILLFLAW_TMP_STORE_TYPE=local
_10
SKILLFLAW_TMP_STORE_LOCAL_PATH=~/data/skillflow/storage/tmp

If you switch one of these stores to S3, you must fill in the matching bucket, endpoint, region, and credential variables for that specific store.

Skill sandbox / OpenSandbox​

If you test Skill execution, AI-assisted Skill workflows, or sandbox-based runtime behavior locally, configure the OpenSandbox connection explicitly:


_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

These values must match the actual OpenSandbox service that your local backend can reach. If your team uses a different OpenSandbox host, protocol, or API key, update the values before starting make backend.

Security sandbox usage in local development​

In local development, both Skill runtime execution and MCP stdio sandbox execution are designed around the sandbox service instead of running untrusted code directly in the SkillFlaw backend process.

  • Skill execution uses the Skill sandbox service and connects to OpenSandbox by default.
  • MCP stdio sandbox execution also uses OpenSandbox, but it resolves its own sandbox image and runtime workspace separately from Skill execution.

When you validate these capabilities locally, treat the sandbox as a required runtime dependency, not as an optional accessory.

How Skills use the sandbox​

Skill execution currently uses the opensandbox backend by default. For local development, you should at least confirm:

  • the SkillFlaw backend can reach the OpenSandbox endpoint configured by SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_DOMAIN
  • the protocol in SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_PROTOCOL matches the actual service
  • the API key in SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_API_KEY is aligned with the target environment when authentication is enabled
  • the request timeout in SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_REQUEST_TIMEOUT_SECONDS is long enough for the Skill you test

If you also validate dependency installation, long-running scripts, or filesystem export behavior, keep the Skill sandbox runtime limits explicit as well:


_10
SKILLFLAW_SKILL_SANDBOX_CPUS=1.0
_10
SKILLFLAW_SKILL_SANDBOX_MEMORY_MB=512
_10
SKILLFLAW_SKILL_SANDBOX_PIDS_LIMIT=256
_10
SKILLFLAW_SKILL_SANDBOX_TIMEOUT_SECONDS=60
_10
SKILLFLAW_SKILL_SANDBOX_NETWORK=none
_10
SKILLFLAW_SKILL_SANDBOX_READ_ONLY_ROOT=true
_10
SKILLFLAW_SKILL_SANDBOX_TMPFS_ENABLED=true
_10
SKILLFLAW_SKILL_SANDBOX_WORKSPACE_ACCESS=rw
_10
SKILLFLAW_SKILL_SANDBOX_ENV_ALLOWLIST=[]

Use values that match your actual verification target. For example, if a Skill must access external services during local debugging, you need to switch SKILLFLAW_SKILL_SANDBOX_NETWORK away from none deliberately instead of assuming network access exists.

How MCP uses the sandbox​

MCP sandbox execution reuses the OpenSandbox connection settings from the Skill sandbox configuration, so the same OpenSandbox endpoint must be reachable from the local backend. In addition, MCP needs its own sandbox image settings because the sandbox image is selected by MCP server language.

For local development, configure at least one of these image strategies:

  • a shared MCP sandbox image with SKILLFLAW_MCP_SANDBOX_IMAGE, or
  • per-language images such as SKILLFLAW_MCP_SANDBOX_PYTHON_IMAGE and SKILLFLAW_MCP_SANDBOX_TYPESCRIPT_IMAGE, or
  • image repository/tag pairs such as SKILLFLAW_MCP_SANDBOX_PYTHON_IMAGE_REPOSITORY with SKILLFLAW_MCP_SANDBOX_PYTHON_IMAGE_TAG

Example:


_10
SKILLFLAW_MCP_SANDBOX_BASE_DIR=~/.skillflaw/mcp-sandboxes
_10
SKILLFLAW_MCP_SANDBOX_PYTHON_IMAGE=ghcr.io/cwinux/skillflow_mcp_python:v1.0.1
_10
SKILLFLAW_MCP_SANDBOX_TYPESCRIPT_IMAGE=ghcr.io/cwinux/skillflow_mcp_ts:v1.0.1

The MCP sandbox image value must be a Docker image reference, not an HTTP URL. If you provide repository and tag separately, keep both values aligned with the runtime image available to your OpenSandbox deployment.

Sandbox configuration requirements​

Before you test Skills or MCP locally, confirm all of the following:

  1. OpenSandbox is deployed and reachable from the SkillFlaw backend.
  2. The OpenSandbox protocol, domain, and API key in .env match the actual service.
  3. The sandbox image matches the runtime language you intend to test.
  4. The CPU, memory, process-count, timeout, filesystem, and network limits match your local verification scope.
  5. Any environment variables that must enter the Skill sandbox are declared explicitly in SKILLFLAW_SKILL_SANDBOX_ENV_ALLOWLIST instead of relying on implicit inheritance.
  6. If you change the sandbox image, runtime image repository/tag, or OpenSandbox execd_image, restart the sandbox service before re-testing.

Misalignment in these settings can produce validation results that do not reflect actual product behavior, including image resolution failures, runtime startup errors, missing dependencies, or sandbox timeouts.

2. Install dependencies​

Use the project wrapper instead of installing pieces manually:


_10
make init

make init performs these steps:

  • make install_backend
  • make install_frontend
  • uvx pre-commit install

3. Initialize the database​

Initialize schema and seed data:


_10
make init_db

Useful facts:

  • this is the supported initialization entry for source-based local environments
  • it creates the target database when needed, then loads schema and exported init data
  • it also prepares the default admin account

4. Start services for development​

Open separate terminals for the services you need.

Backend​


_10
make backend

The backend serves APIs on port 7860 by default.

Frontend​


_10
make frontend

The frontend development server serves the UI on port 3000 by default.

Docs​


_10
make docs docs_port=3001

This starts the standalone docs service and serves all locales at the root path of port 3001.

If you are actively editing docs and need hot reload instead of the standalone served build, use:


_10
make docs_dev docs_port=3001

5. Common developer loops​

Run the packaged application quickly​


_10
make run_cli

Force a fresh frontend rebuild before launch​


_10
make run_clic

Build the project​


_10
make build

Format and lint​


_10
make format
_10
make lint

Run backend unit tests​


_10
make unit_tests

6. When to use Docker instead​

If you want to validate the product-like stack rather than the split development servers, use:


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

This path is better for verifying deployment wiring, service composition, and docs delivery.