ya-claw-deploy

name

ya-claw-deploy

description

Deploy, configure, operate, and troubleshoot YA Claw, the single-node runtime web service in ya-mono. Use for production and self-hosted Docker deployment, docker-compose, systemd services, SQLite or PostgreSQL storage, Docker workspace provider configuration, profile seeding, execution coordinator setup, health checks, reverse proxy setup, GitHub or Lark bridge deployment, upgrades, backup, restore, and production operations for packages/ya-claw.

YA Claw Deployment

Use this skill when deploying, configuring, operating, or troubleshooting YA Claw.

Recommended Deployment Shape

Use the Docker workspace provider for production-like deployments. Choose the exact shape from the workspace provider matrix.

flowchart LR
    CLIENT["Web/API Client"] --> SVC["YA Claw Service"]
    SVC --> DB[("SQLite or PostgreSQL")]
    SVC --> DATA["Persistent Data Dir"]
    SVC --> PROVIDER["WorkspaceProvider"]
    PROVIDER --> LOCAL["Local shell"]
    PROVIDER --> DOCKER["Docker shell"]
    DOCKER --> WSC["Reusable Workspace Container"]

The Docker shell shapes give agents an isolated workspace container with Python, Node.js, GitHub CLI (gh), lark-cli, and bundled workspace skills.

Start Here

Choose the deployment path:

• Workspace provider matrix: read references/workspace-provider/overview.md
• Service Docker + Docker shell: read references/docker.md and references/workspace-provider/service-docker-docker-shell.md
• Service local + Docker shell: read references/systemd.md and references/workspace-provider/service-local-docker-shell.md
• Service local + local shell: read references/workspace-provider/service-local-local-shell.md
• SQLite or PostgreSQL storage: read references/database.md
• Profile seeding, subscription-backed Codex profiles, shell review policy, and shell sandbox policy: read references/profiles.md
• Third-party capability plugin installation and manifest deployment: read references/plugins.md
• Bridge deployment: read references/bridge/overview.md, references/bridge/github.md, and references/bridge/lark.md
• Schedules and heartbeat: read references/schedules-heartbeat.md
• Session agency: read references/agency.md
• Session/run pruning: read references/operations.md#session-and-run-pruning
• Health checks, backup, restore, upgrades, and troubleshooting: read references/operations.md

Required Baseline

Every deployment needs:

• YA_CLAW_API_TOKEN
• persistent YA_CLAW_DATA_DIR
• persistent YA_CLAW_WORKSPACE_DIR
• selected workspace backend: local or docker
• Docker CLI on PATH plus Docker Engine API access for the YA Claw service process when backend is docker; the official service image bundles the CLI, but custom images and host installs must provide it
• YA_CLAW_WORKSPACE_PROVIDER_DOCKER_HOST_WORKSPACE_DIR when the service runs in Docker and uses Docker shell execution
• model/provider credentials available in the YA Claw service process
• seeded or pre-created execution profile rows
• for capability plugins, trusted distributions installed in the service Python environment plus an administrator-controlled manifest path

Default Runtime Values

• HTTP port: 9042
• runtime data dir: ~/.ya-claw/data
• SQLite path: ~/.ya-claw/ya_claw.sqlite3
• run store: ~/.ya-claw/data/run-store
• workspace dir: ~/.ya-claw/data/workspace
• session agency: disabled by default; when enabled, inactivity scan runs after 600 seconds with 1800-second cooldown
• session prune: disabled by default; safe disk-only mode keeps latest 10 runs per session when enabled
• default profile: default
• profile shell review threshold default: extra_high
• local shell sandbox default: enabled, profile workspace_write, backend auto, network full, env allowlist *, raw host shell escalation requires explicit policy allowance
• Docker workspace image: ghcr.io/wh1isper/ya-claw-workspace:latest
• Docker service host bind: 0.0.0.0
• service build metadata: YA_CLAW_SERVICE_VERSION, YA_CLAW_SERVICE_COMMIT, YA_CLAW_SERVICE_BUILD, and YA_CLAW_SERVICE_IMAGE, exposed through /api/v1/claw/info and the web Overview page

Deployment Checklist

1. Generate a long random YA_CLAW_API_TOKEN.
2. Choose SQLite or PostgreSQL.
3. Mount or create persistent data and workspace directories.
4. Choose one workspace provider shape.
5. Grant the service Docker access when the shape uses Docker shell execution.
6. Configure profile seed when packaged profiles should be loaded at startup.
7. If using capability plugins, install them into the service environment, configure YA_CLAW_CAPABILITY_PLUGIN_MANIFEST, and restart for every package or manifest change.
8. Start the service with ya-claw start.
9. Verify /healthz.
10. Verify authenticated API or web shell access.
11. Start a test session and confirm model credentials, plugin grants, workspace tools, and profile behavior.
12. Enable session agency with YA_CLAW_AGENCY_ENABLED=true for deployments that want proactive agency rollout.

Reference Routing

Topic	File	Read when
Environment variables	references/environment.md	You need exact YA_CLAW_* settings, defaults, or production env shape
Docker deployment	references/docker.md	You deploy the YA Claw server as a Docker service
Workspace provider matrix	references/workspace-provider/overview.md	You choose between service local + Docker shell, service Docker + Docker shell, and service local + local shell
Docker workspace provider	references/workspace-provider/docker.md	You configure Docker Engine access, path mapping, workspace mounts, and container reuse
Host service	references/systemd.md	You run YA Claw as a supervised host service
Database	references/database.md	You choose SQLite or PostgreSQL, migrate, backup, or restore storage
Profiles	references/profiles.md	You seed profiles, manage execution profile configuration, tune shell review, or configure shell sandbox policy
Capability plugins	references/plugins.md	You install trusted plugin packages, deploy the manifest, or build a derived service image
Bridge overview	references/bridge/overview.md	You configure bridge dispatch, adapter enablement, and event-to-run routing

When editing this skill inside the repository, keep scripts/build-skill-zips.py aligned so release artifacts include the canonical skill contents.