nodeskclaw

中文

Discord License

DeskClaw

Co-operate with AI. The open-source platform where humans and AI run businesses together -- from strategy to execution.

DeskClaw is the operating platform for human-AI co-managed organizations. Through Cyber Workspaces, humans and AI operate as partners in a shared digital space -- humans provide strategic judgment, AI delivers relentless execution, and together they build something neither could alone.

Co-operating

We believe the future belongs to organizations where humans and AI co-operate -- not as master and tool, but as partners who each bring irreplaceable value to the business.

• Human operators bring strategic judgment, creative decisions, and value alignment -- deciding what to do and why
• AI operators bring tireless execution, pattern recognition, and rapid iteration -- pushing how to do it to the extreme
• Cyber Workspace is where co-operating happens -- a shared operations board (blackboard), task delegation, and real-time coordination that fuses human and AI capabilities into one

Core Concepts

Cyber Workspace

The digital space where humans and AI co-operate. Hexagonal topology visualizes your operating team's relationships; the shared blackboard serves as the team's operations dashboard; task publishing lets any partner -- human or AI -- delegate work to whoever is best suited. Not a monitoring panel, but the place where business happens.

Gene System

Investment in AI operating capabilities. Loading a new Gene onto an AI partner opens a new dimension for your business -- modular capability packages from a public marketplace or your private enterprise library, composable on demand, continuously evolving. The business you run determines the Genes you load.

Elastic Scale

Instant expansion of operating capacity. One-click deployment of AI operating partners on Kubernetes clusters. Local development supported via dev.sh for rapid iteration.

Highlights

• Cyber Workspace -- Hexagonal topology space where human and AI partners co-operate, share an operations board, and delegate tasks
• Gene System -- Modular capability investment: load new business dimensions onto AI partners from a public or private marketplace
• One-Click Scale -- Expand your operating capacity end-to-end, with SSE real-time progress streaming
• Multi-Cluster Operations -- Cross-cluster orchestration, health checks, and elastic scaling across your business footprint

Architecture

…

Project Layout

DeskClaw/
├── nodeskclaw-portal/             # User Portal -- Vue 3 + Tailwind CSS
├── nodeskclaw-backend/            # API Server -- Python 3.12 + FastAPI + SQLAlchemy
├── nodeskclaw-llm-proxy/          # LLM Proxy -- Python + FastAPI
├── nodeskclaw-artifacts/          # Docker images & deploy manifests
├── openclaw-channel-nodeskclaw/   # Cyber Workspace channel plugin
├── openclaw-channel-dingtalk/     # DingTalk channel plugin (Stream protocol)
├── openclaw/                      # DeskClaw runtime source (external)
└── vibecraft/                     # VibeCraft source (external)

i18n

Full-stack internationalization covering Portal and Backend.

• Language detection: zh* -> zh-CN, en* -> en-US, fallback en-US
• Error display: prefer message_key local translation, fall back to message when missing
• Backend contract: code + error_code + message_key + message + data

Quick Start

Kubernetes

DeskClaw Team Edition supports Kubernetes as its only product deployment target. The control plane and all managed instances run on K8s. For local development, use dev.sh instead (see below).

Requires a K8s cluster, a container registry, and an external PostgreSQL database.

Prerequisites

1. Configure Registry & Context

# Create deploy/.env.local (git-ignored)
cat > deploy/.env.local 
#   ENCRYPTION_KEY=

3. Initialize the Cluster

Creates the namespace, uploads .env as a K8s Secret, and applies base Deployment + Service manifests:

./deploy/init.sh --prod --context      # Production namespace
# Optional temporary validation namespace:
./deploy/init.sh --staging --context 

4. Release & Deploy

./deploy/release.sh create v0.9.0
./deploy/deploy.sh deploy --tag v0.9.0 --prod --context 
./deploy/deploy.sh deploy backend --tag v0.9.0 --prod --context 

5. Configure Ingress

Edit deploy/k8s/ingress.yaml -- replace example.com hosts with your actual domains, then apply:

kubectl --context  -n  apply -f deploy/k8s/ingress.yaml

The Ingress defines two hosts (configure as needed):

See deploy/README.md for full release and deployment workflow details.

Local Development

Prerequisites

1. Configure

cd nodeskclaw-backend
cp .env.example .env
# Edit .env -- fill in DATABASE_URL, JWT_SECRET, etc.

2. One-command Start

./dev.sh              # Start all services (backend + portal)
./dev.sh --docker-pg  # Start a Docker PostgreSQL (no local PG install needed)
./dev.sh --fresh      # Force reinstall all dependencies

The script handles dependency installation, starts all services with colored log prefixes, and cleans up on Ctrl+C. --docker-pg launches a local PostgreSQL container automatically.

Services: backend (4510) + llm-proxy (4511) + portal (4517)

Manual Start (alternative)

Backend:

cd nodeskclaw-backend
uv sync
uv run uvicorn app.main:app --reload --port 4510

API at http://localhost:4510 | Swagger at http://localhost:4510/docs | Auto-migration on first boot.

Frontend (Portal):

cd nodeskclaw-portal
npm install && npm run dev

Portal at http://localhost:4517 | /api auto-proxy to backend.

3. Sign In

On first startup the backend prints the initial admin credentials directly in the terminal output:

========================================
  Initial admin account
  Account: admin
  Password: 
  Please change your password after login
========================================

Open http://localhost:4517 and sign in with the printed credentials. You will be prompted to change the password on first login.

Upgrade

Kubernetes

K8s releases and deployments are managed by separate scripts. The typical workflow is create a release artifact, run local validation, deploy the same tag to production, then run production smoke checks. A temporary staging namespace can still be initialized explicitly when a separate validation environment is needed.

Create release artifacts -- build images, push to registry, tag git, and create a GitHub Pre-release:

./deploy/release.sh create v0.9.0

Optional temporary staging -- reuse the released images and update an explicitly initialized staging namespace:

./deploy/deploy.sh deploy --tag v0.9.0 --staging --context 

Production -- deploy the same images to production, then mark the release as final:

./deploy/deploy.sh deploy --tag v0.9.0 --prod --context 
./deploy/release.sh finalize v0.9.0

Database migrations run automatically when the new backend pod starts. See deploy/README.md for full CLI usage and options.

Build Mirrors

If pulling dependencies (PyPI, npm, Debian/Alpine packages) is slow in your region, use a mirror preset to speed up builds:

# release.sh
./deploy/release.sh create v0.9.0 --mirrors cn

# artifacts (DeskClaw engine images)
./nodeskclaw-artifacts/build.sh openclaw --mirrors cn

Available presets are in deploy/mirrors/. See deploy/mirrors/README.md for details and customization.

Note: Docker Hub base image pulls (FROM python:3.12-slim, etc.) cannot be accelerated this way. Configure a registry mirror in your Docker daemon instead.

Upgrade Notes

• Back up your database before any major version upgrade.
• Check GitHub Releases for release notes and breaking changes.
• If your database was not previously managed by Alembic, you may need to run alembic stamp head once before upgrading. See Backend README for details.
• Docker-type clusters are removed starting with the next release — instance deployment now supports Kubernetes clusters only:
  • Shared files of older self-hosted deployments lived in $NODESKCLAW_DATA_DIR/shared-files (default ~/.nodeskclaw/docker-instances/shared-files). After upgrading, manually migrate them into the new named volume shared_files (mounted at /data/shared-files inside the backend container).
  • Existing Docker cluster/instance records are soft-deleted by the data migration on startup.
  • Any docker-{slug} compose projects still running on the host are no longer managed by the platform — stop them manually with docker compose down.

Documentation

Community

• Discord -- Join the discussion, ask questions, share feedback
• GitHub Issues -- Bug reports and feature requests
• WeChat -- Scan the QR code below to join the developer group; if the WeChat group is full, please use Discord above

Contributing

PRs welcome. See CONTRIBUTING.md for guidelines.

License

Apache License 2.0