# DeskClaw: running AI workers alongside humans on a Kubernetes control plane

> DeskClaw is an Apache-2.0 platform where human operators and AI partners share a Cyber Workspace, delegate tasks to each other and load modular capabilities called Genes from a marketplace. The Team Edition deploys only to Kubernetes, and the compose file is the quicker way to try it locally.

**NoDeskAI/nodeskclaw** — Humans and AI work together ❤️

- Repository: https://github.com/NoDeskAI/nodeskclaw
- Stars: 758 · Forks: 139
- Language: Python
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/nodeskai-nodeskclaw

## The Cyber Workspace is a shared board, not a monitoring panel

DeskClaw describes itself as the operating platform for human and AI co-managed organisations, and its repository description is simply humans and AI work together. The framing is the interesting part of the design.

The README splits the responsibilities explicitly. 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. The Cyber Workspace is where the co-operation happens, described as a shared operations board, task delegation and real-time coordination that fuses the two capabilities into one.

The wording about the workspace is deliberate. It says this is not a monitoring panel but the place where business happens, and the visual metaphor is a hexagonal topology that shows the relationships between the members of the operating team, with the shared blackboard acting as the team's operations dashboard and task publishing letting any partner, human or AI, delegate work to whoever is best suited.

The architecture diagram in the README lays the stack out in four tiers. At the top, co-operators, human and AI, linked by a dotted co-operate edge. Below that, channels, comprising a web portal, DingTalk and an open API, so the same workspace can be reached from a browser, from a Chinese enterprise chat client or from code. Then the co-operation core, holding the Cyber Workspace with its hex topology, shared blackboard and task delegation, plus the Gene System with its marketplace and enterprise library. Then platform services covering instance lifecycle, multi-cluster, elastic scale, LLM routing and channel plugins. At the base sits infrastructure: Kubernetes, the OpenClaw and Hermes runtimes, PostgreSQL and the model providers, listed as OpenAI, Anthropic, Gemini and others.

That layer order is the whole product in one diagram. The interesting engineering is not in the model calls but in the routing, the lifecycle and the multi-cluster orchestration above them.

## Genes are the capability packaging layer

The Gene System is described as investment in AI operating capabilities. Loading a new Gene onto an AI partner opens a new dimension for the business, and the Genes come from a public marketplace or from a private enterprise library, are composable on demand and evolve continuously.

The key phrase is that the business you run determines the Genes you load. A capability package is therefore closer to a business capability than to a library function. That framing has consequences for how you operate it: a marketplace of modules whose value depends on the process you are automating is a catalogue, and the quality of a catalogue depends on how well the entries are described and versioned.

The environment configuration shows where the registry lives. A DeskHub Registry section, labelled in the file as the gene registry, provides DESKHUB_REGISTRY_URL, DESKHUB_API_KEY and DESKHUB_WEB_URL, and the comment notes that leaving it empty sends everything through the local database instead. That is a sensible default for a self-hosted deployment, and it means the marketplace is optional infrastructure rather than a hard dependency of the core.

Elastic scale is the third core concept, and it is the one with the heaviest infrastructure implications. It is instant expansion of operating capacity through one-click deployment of AI operating partners on Kubernetes clusters, with local development supported through a dev.sh script for fast iteration. The Highlights list adds cross-cluster orchestration, health checks and elastic scaling across the footprint, plus SSE real-time progress streaming so a long deployment reports progress rather than appearing to hang.

The release list shows the project is in a pre-1.0 phase with a team edition suffix, v0.9.15-beta.2 dated 2026-06-03, preceded by v0.9.15-beta.1 and v0.9.15-beta in the same week and the day before. The last push was on 2026-10-19.

## Team Edition deploys to Kubernetes and nothing else

The deployment story is the sharpest constraint in the project. The Quick Start states that DeskClaw Team Edition supports Kubernetes as its only product deployment target, that the control plane and all managed instances run on K8s, and that for local development you use dev.sh instead.

The prerequisites are spelled out as a table: a Kubernetes cluster at version 1.24 or newer with an Ingress Controller such as ingress-nginx, any Docker V2 container registry from Docker Hub through AWS ECR to GCR, an external PostgreSQL database such as AWS RDS or GCP Cloud SQL, kubectl configured against the cluster, and Docker for building images locally.

The release sequence is a set of shell scripts under deploy/. The first step writes a git-ignored local environment file with the registry and kubectl context:

```bash
# Create deploy/.env.local (git-ignored)
cat > deploy/.env.local <<'EOF'
REGISTRY="your-registry.example.com/deskclaw"
KUBE_CONTEXT="your-kubectl-context"
EOF

# Login to your container registry
docker login your-registry.example.com
```

The second step prepares the backend environment, and the required variables are named in the file comments:

```bash
cp nodeskclaw-backend/.env.example nodeskclaw-backend/.env
# Edit .env -- fill in DATABASE_URL, JWT_SECRET, ENCRYPTION_KEY, etc.
# Minimum required:
#   DATABASE_URL=postgresql+asyncpg://user:pass@your-rds:5432/nodeskclaw
#   JWT_SECRET=<random-secret>
#   ENCRYPTION_KEY=<32-byte-base64-key>
```

The third step initialises the cluster, creating the namespace, uploading the .env as a Kubernetes Secret and applying the base Deployment and Service manifests, with separate production and staging namespace flags. The fourth runs a release script and a deploy script, each taking a tag, and the deploy script also takes a component argument, so you can deploy the backend on its own.

A subtlety worth noting is the division between the two deploy scripts. A release appears to create something, and the deploy step applies it, which means the release artefact and the deployment of that artefact are separate operations. That is the shape you want for a staged rollout and it is the shape that requires the release to exist before the deploy command will do anything.

## Docker Compose is the faster route to a local look

The repository root carries both docker-compose.yml and docker-compose.ee.yml, and the compose file gives a much quicker picture of the running system than the Kubernetes manifests do.

The compose file starts a postgres service on the postgres:16-alpine image with a named volume, a healthcheck based on pg_isready against the configured user, and restart unless-stopped. The backend service builds from the local context with nodeskclaw-backend/Dockerfile, depends on the postgres service with the service_healthy condition, and mounts the working directory read-only at /host-config alongside a shared files volume. The environment block shows the real wiring: a database URL pointing at the postgres service, a pair of LLM proxy variables with an internal URL that resolves to the llm-proxy service, an attribution secret, and the edition flag set to ce.

The two LLM proxy variables are worth a second look. LLM_PROXY_URL defaults to a localhost address on a port derived from LLM_PROXY_PORT with 4511 as the fallback, while LLM_PROXY_INTERNAL_URL points at http://llm-proxy:8080, which is the service name inside the compose network. That is the classic split between the address a browser or a client uses and the address a container uses to reach a peer, and getting it wrong produces a proxy that works from your laptop and fails from inside the network.

The AGENT_API_BASE_URL variable carries a comment stating that the address where the AI employee connects back to the backend must be an external address reachable by the K8s pod. That is a specific deployment constraint written in the file, and it is the kind of detail that turns into a support ticket if it is missed.

The compose file also references prebuilt images hosted on a Volcengine registry with the version supplied through DESKCLAW_VERSION, so the local path can run against published images rather than only your own build.

## The environment file shows the edition split and the placeholder secrets

The .env.example file is the most informative document in the repository, because it is a complete list of what the platform expects to be told.

The security-relevant entries come first. JWT_SECRET ships with the value change-me-in-production and a comment saying it must be replaced in production, alongside JWT_EXPIRE_HOURS set to 24. ENCRYPTION_KEY is described as a 32-byte base64 key for encrypting KubeConfig and ships with a placeholder value. The default compose file sets NODESKCLAW_EDITION to ce, and the environment example documents a separate EE administrator setting with a comment that it only takes effect in EE mode and must not be the same as the INIT_ADMIN_ACCOUNT value. There is a RESET_EE_ADMIN_PASSWORD flag as well.

The single sign-on section is for Feishu, with an admin application and an optional portal application, each with its own id and secret, plus a redirect URI. The portal and admin applications being separate is what lets an organisation use one Feishu app for staff sign-in to the console and another for the user-facing portal.

The cloud platform section carries a VKE subnet id and an image registry, which points at a Volcano Engine Kubernetes Engine deployment. The file upload section is more detailed than most: the storage backend can be set to s3, and the comment says that when it is s3, missing required values make the storage state unavailable and there is no fallback to local, which is a deliberate fail-loud choice. There are also upload limits for gateway proxy body size, read and send timeouts, chat attachment size and count, retention days, shared file limits, a large file limit of 2048 MB and a chunked upload threshold.

Everything else in the file follows the same pattern of a working default with a comment explaining the production concern, which makes this file worth reading end to end before you deploy anything.

## A multi-language codebase with two editor conventions and a security layer

The project layout shows the scope of the codebase. There is nodeskclaw-portal, a Vue 3 frontend with Tailwind CSS, nodeskclaw-backend, a Python 3.12 API server built on FastAPI and SQLAlchemy, and nodeskclaw-llm-proxy, a separate LLM proxy service also on FastAPI. Then nodeskclaw-artifacts holding Docker images and deployment manifests, and three channel plugins: openclaw-channel-nodeskclaw, openclaw-channel-dingtalk which uses the Stream protocol, and openclaw-channel-learning.

Two of the top-level directories are named after external sources, openclaw and vibecraft, and both are marked as external source. So the runtime that actually executes the AI partners and the tooling called VibeCraft live outside this repository, which is a significant boundary for anyone planning to fork or audit the system.

The rest of the root is process and policy rather than code. There are .cursor/, .claude/, AGENTS.md, CLAUDE.md, CONTRIBUTING.md and CONTRIBUTORS.md, which together suggest the project is developed with more than one AI-assisted editor in the loop and that those conventions are written down. API-USAGE-GUIDE.md documents the API surface, features.yaml looks like a feature flag file, and there is an openclaw-security-layer directory, a hermes-nodeskclaw-bridge directory, a stats_output directory and a scripts directory.

Internationalisation is described as full stack across portal and backend, with a detection rule mapping zh prefixed locales to zh-CN and en prefixed ones to en-US, falling back to en-US. The error contract is a fixed shape of code, error_code, message_key, message and data, and the display rule prefers a local translation of message_key and falls back to the raw message when the key is missing. That contract is the kind of detail that matters when you are integrating a second front end.

The licence is Apache-2.0, and the README carries a Chinese version alongside the English one, with a Discord link for the community.

## Conclusion

DeskClaw is worth evaluating if you are running an organisation where AI agents do real operational work and you need a shared board, delegation and capability packaging around them, because the Cyber Workspace and the Gene system are the parts that turn a set of agent scripts into something a team can operate. It is the wrong tool for a single developer with one agent, since the Kubernetes control plane, the LLM proxy and the multi-cluster layer are real operational surface area for a problem that does not need it. Before you deploy it, verify three things yourself: that your cluster meets the stated requirements of version 1.24 or newer with an Ingress controller, a container registry and an external PostgreSQL, that you replace the placeholder JWT_SECRET and 32-byte ENCRYPTION_KEY before any real deployment, and that you choose between the community edition and the team edition deliberately, because the environment sets a NODESKCLAW_EDITION value and the administrator accounts behave differently between the two.

## FAQ

### What is DeskClaw and what problem does it solve?

DeskClaw is an open source platform where human operators and AI partners run an organisation together. The Cyber Workspace gives them a shared blackboard, a hexagonal topology view and task delegation, so either side can hand work to whoever is best suited to do it.

### What are Genes in DeskClaw?

Genes are modular capability packages that you load onto an AI partner, taken from a public marketplace or a private enterprise library and composable on demand. The registry is configured through DESKHUB_REGISTRY_URL, and leaving that empty routes everything through the local database instead.

### What does deploying DeskClaw require?

The Team Edition supports Kubernetes as its only product deployment target, needing a cluster at 1.24 or newer with an Ingress controller, any Docker V2 registry, an external PostgreSQL, kubectl and Docker. For local work the project ships a dev.sh script and a docker-compose.yml.

### Which secrets must I change before deploying DeskClaw?

The environment example ships placeholder values for JWT_SECRET, described as needing replacement in production, and for ENCRYPTION_KEY, a 32-byte base64 key used to encrypt KubeConfig. The file also sets JWT_EXPIRE_HOURS to 24 and carries the edition flag and administrator account settings.

### What is the difference between the community and team editions of DeskClaw?

The deployment and configuration differ through an edition flag, NODESKCLAW_EDITION, which the compose file sets to ce and the Kubernetes init script sets according to an --ee flag. There is also a separate EE administrator account setting that only takes effect in EE mode and must differ from the INIT_ADMIN_ACCOUNT.

## Sources

- [Issues](https://github.com/NoDeskAI/nodeskclaw/issues)
- [License: Apache-2.0](https://github.com/NoDeskAI/nodeskclaw/blob/main/LICENSE)
- [NoDeskAI/nodeskclaw on GitHub](https://github.com/NoDeskAI/nodeskclaw)
- [README](https://github.com/NoDeskAI/nodeskclaw/blob/main/README.md)
- [Releases](https://github.com/NoDeskAI/nodeskclaw/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nodeskai-nodeskclaw