Skip to main content

Security sandbox

SkillFlaw uses a sandbox runtime for code-execution scenarios that should not run directly inside the backend process.

In local development, the sandbox is relevant in two main developer-facing paths:

  • Skill runtime execution
  • MCP stdio sandbox execution

For both paths, treat the sandbox as part of the runtime contract of your development environment.

Why the sandbox matters​

SkillFlaw can run user-authored logic, resolve dependencies, create temporary runtime workspaces, and exchange files with runtime environments.

That means local development should not assume unrestricted execution inside the main SkillFlaw server process. Instead, you should validate sandbox connectivity, runtime images, and resource limits explicitly.

Skill sandbox​

Skill execution uses the Skill sandbox service and defaults to the opensandbox backend.

At minimum, local development must align these connection settings with the real OpenSandbox service that the backend can reach:


_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

If you test dependency installation, exported files, or longer-running scripts, make the 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 local verification target. For example, if a Skill must call an external service during debugging, do not assume network access exists by default; configure the sandbox network mode deliberately.

MCP sandbox​

MCP stdio sandbox execution reuses the OpenSandbox connection settings from the Skill sandbox, so the local backend must reach the same OpenSandbox service.

In addition, MCP needs its own sandbox image settings because the runtime image is selected by server language.

You can configure MCP sandbox images in one of these ways:

  • a shared image with SKILLFLAW_MCP_SANDBOX_IMAGE
  • per-language images such as SKILLFLAW_MCP_SANDBOX_PYTHON_IMAGE and SKILLFLAW_MCP_SANDBOX_TYPESCRIPT_IMAGE
  • 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.

Sandbox configuration requirements​

Before testing Skill or MCP behavior locally, confirm all of the following:

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

When sandbox-based capabilities are part of your development scope, use this order:

  1. Start or confirm the OpenSandbox service.
  2. Fill in sandbox-related .env settings before starting make backend.
  3. Verify the target runtime image exists for the language you want to test.
  4. Run Skill or MCP validation only after backend-to-sandbox connectivity is confirmed.
  5. Re-test after every sandbox image or runtime configuration change.