udev — Ambientes de Desenvolvimento IA sob Demanda
ClickerMonkey/udev
Workspaces IA isolados por tarefa, browser-first, K8s-ready
Ver no GitHubMCP server que cria workspaces de desenvolvimento isolados, acessíveis por navegador e controlados por IA. Cada workspace executa Claude Code, code-server, sua aplicação e busca de logs em uma única URL, escalável em Kubernetes. Perfeito para automação de tarefas de desenvolvimento disparadas por prompts, webhooks GitHub/GitLab/JIRA.
Instalação
npx convez-ai ClickerMonkey/udev1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de desenvolvimento por eventos GitHub/GitLab/JIRA
- Ambientes de desenvolvimento temporários controlados por Claude
- Escalabilidade de workspaces em Kubernetes com controle centralizado
- Debugging e inspeção de código com IA em tempo real
Veredito

Ferramenta sofisticada para equipes que querem automação de desenvolvimento em escala. Requer conhecimento sólido de Kubernetes, Docker e CI/CD — não é entry-level, mas oferece controle poderoso e reprodutibilidade.
README
A tradução para o português deste README ainda está na fila.
udev — on-demand AI dev workspaces
git + your running app + AI + a browser IDE + searchable logs. An isolated workspace per task — open the link and your repo's checked out, running, and AI-ready; launched from a prompt or a GitHub/GitLab/JIRA event, scaled out on Kubernetes.
Launch isolated, browser-accessible development workspaces on demand — from a prompt, a GitHub/GitLab comment, or a JIRA issue. Each workspace runs Claude Code behind the claudecodeui / CloudCLI web IDE, a browser code-server, your project's processes, and a log search UI — all behind one URL with a per-project config file. Claude can operate it too: inspect config, control processes, build, read/search logs, and run git.
dispatcher (control plane)
prompt ─┐ ┌───────────────────────────┐
GitHub ──┤ POST │ build manifest → K8s objs │ one Deployment +
GitLab ──┼──────► │ server-side apply │ Service + Ingress
JIRA ──┘ └───────────────────────────┘ per workspace
│
▼ <id>.udev.example.com
┌──────────── workspace pod ─────────────────────────┐
│ workspace container nginx gateway (:80) │
│ / your root app ── routes (127.0.0.1) ──┤
│ /__claude CloudCLI (Claude UI, body-rewritten) │
│ /__code/ code-server │
│ /__logs log search │
│ /<svc> your other app(s) │
│ processes → /workspace/.udev/logs/*.log │
│ Claude reads the same files + .mcp.json servers │
└────────────────────────────────────────────────────┘
Repo layout
Three buckets: the engine (reusable product), examples (self-contained, each runnable on its own), and deploy (production templates) — plus docs.
| Path | What |
|---|---|
workspace-image/ | The engine — the per-workspace Docker image (Claude CLI + CloudCLI + code-server + git + toolchain), driven by a manifest. bin/ holds the tooling. |
workspace-image/bin/render.mjs | Manifest → supervisord config, nginx gateway routes, MCP config, env. |
workspace-image/bin/entrypoint.sh | Boots a project: git creds → clone → in-repo manifest → setup/build → launch. |
workspace-image/bin/{logserver,udev-mcp,approval-*}.mjs | Log search + capture, the udev MCP, the Slack approval broker/hook. |
dispatcher/ | The control plane — prompt/webhook → workspace on K8s. src/render.js builds the objects. |
deploy/k8s/, deploy/coder/ | Production templates — namespace, secret.example.yaml, workspace.example.yaml; optional Coder template. |
examples/<name>/ | Self-contained demos — each has its app + project.yaml + a compose.yaml (mounts ./, builds ../../workspace-image). sample-app (single app) and fullstack (REST+WS api, Vue SPA, plain service). |
docs/manifest-reference.yaml | The full manifest schema — every field, annotated. |
The manifest (one config file per project)
Lives either in the repo as udev.yaml (preferred) or supplied at launch.
project: my-api
os: linux # linux | windows -> nodeSelector + base image
repo: git@gitlab.com:me/api.git
branch: main
env: { NODE_ENV: development, PORT: "3000" }
features:
claudeRewrite: true # let YOUR app own /api (moves CloudCLI's REST to /__claude/api)
frontendLogs: true # browser console + errors -> .udev/logs/frontend.log
nav: true # tiny center-top App/Claude/Code/Logs switcher
setup: ["pnpm install"]
build: ["pnpm build"]
run:
- { name: web, cmd: "pnpm start", cwd: "." }
mcp:
- name: gitlab
command: npx
args: ["-y", "@zereight/mcp-gitlab"]
env: { GITLAB_PERSONAL_ACCESS_TOKEN: "${GITLAB_TOKEN}" }
routes:
- { match: "/", port: 8000, label: "App" } # your app at the root
- { match: "/api", port: 5000 } # owns /api (needs features.claudeRewrite)
- { match: "/admin", port: 4000, stripPrefix: true } # https://<host>/admin
The nginx gateway serves your root app at / and CloudCLI at /__claude
(it body-rewrites CloudCLI's absolute asset URLs under the subpath). A route with
match: "/" becomes the root app; omit it and / redirects to /__claude. Per
route: label: names it in the nav, nav: false hides it, frontendLogs: true
captures that app's console too.
Reserved paths (the gateway's own, all under /__): /__claude, /__code,
/__logs, /__udev — so your services can freely use /claude, /code, /logs.
CloudCLI also serves /api, /ws, /shell, /health at the root — unless
features.claudeRewrite, which moves all of them under /__claude, leaving
the entire root (including /api) for your app. (Assets/manifest/sw already live
under /__claude, so /assets, /icons, etc. at the root are yours.)
Monorepos & multiple repos (components:)
A workspace can run several apps — a monorepo's front-end + api, or several
separate repos side by side. Each is a component with its own path,
optional repo, env, setup, build, run, and routes. The top-level
fields are the implicit "root" component (path: "."), so single-app manifests
are unchanged.
features: { claudeRewrite: true } # so the api can own /api
components:
- name: web # monorepo subdir (no repo of its own)
path: apps/web
env: { PORT: "4000" }
setup: ["npm ci"]
run: [{ name: web, cmd: "npm start" }]
routes: [{ match: "/", port: 4000, label: "App" }]
- name: api
path: services/api
env: { PORT: "5000" }
run: [{ name: api, cmd: "npm start" }]
routes: [{ match: "/api", port: 5000 }]
- name: docs # multi-repo: cloned into ./docs
repo: git@github.com:me/docs.git
path: docs
run: [{ name: docs, cmd: "npm run serve" }]
routes: [{ match: "/docs", port: 6000, stripPrefix: true }]
Each component clones into its path (if it has a repo), runs setup/build in
that dir, gets its own per-process env (so PORT never collides), and its
routes are merged into the gateway. Ports are workspace-wide — keep them unique.
A component can opt in to promoting its own Claude config up to the workspace
root with promote: true (or promote: { mcp: true, claudeMd: true }): its
.mcp.json servers merge into the root .mcp.json (namespaced on clash) and its
CLAUDE.md is @imported into the root CLAUDE.md — so a monorepo app's MCP
servers and guidance are available workspace-wide.
Feature flags (features: → UDEV_* env)
| Flag | Env | Default | Effect |
|---|---|---|---|
claudeRewrite | UDEV_CLAUDE_REWRITE=1 | off | nginx sub_filters CloudCLI's JS so its REST + WebSocket calls go to /__claude/api,/__claude/ws,/__claude/shell; frees the whole root (incl. /api) for your app. |
frontendLogs | UDEV_FRONTEND_LOGS=0 to disable | on | Injects a logger into app HTML capturing all console.*, uncaught errors, unhandled rejections, CSP/permission violations, and failed fetch/XHR/resource loads → .udev/logs/frontend.log (viewable at /__logs). |
nav | UDEV_NAV=0 to disable | on | Injects a tiny center-top nav bar (your app + CloudCLI). |
navInCode | UDEV_NAV_IN_CODE=1 | off | Also inject the nav into code-server (forces its assets uncompressed). |
Deploying under a path (UDEV_BASE_PATH)
To run udev behind an environment's own proxy without the two proxies fighting,
set UDEV_BASE_PATH=/udev/123. The gateway then emits every URL with that
prefix (CloudCLI rewrites, code-server, nav, injected capture scripts, the log
UI, redirects), assuming your outer proxy strips the prefix before
forwarding (e.g. nginx location /udev/123/ { proxy_pass http://udev-gateway/; }).
The gateway's own location matchers stay at root, so nothing inside changes.
For your apps, per component pick one (in the component config):
basePathEnv: VITE_BASE— the app is told its base path via that env var (value =UDEV_BASE_PATH+ the component's route prefix) and emits correctly prefixed URLs natively. Cleanest.basePathRewrite: true— the gateway sub_filters the app's absolutehref/srcto inject the prefix. Fallback for apps that can't take a base-path env.
Run it locally (compose)
docker compose -f examples/sample-app/compose.yaml up --build # :8000
docker compose -f examples/fullstack/compose.yaml up --build # :8001 (REST+WS+Vue+service)
docker compose -f examples/sample-app/compose.basepath.yaml up --build # :8002, nested under /udev
- Gateway: http://localhost:8000/ → your app ·
/__claude·/__code/·/__logs·/sample - From a phone on the same Wi-Fi:
http://<your-LAN-IP>:8000/
Deploy to Kubernetes
kubectl apply -f deploy/k8s/namespace.yaml
# cp deploy/k8s/secret.example.yaml -> fill in real secrets, then apply
kubectl apply -f deploy/k8s/workspace.example.yaml
kubectl -n udev port-forward deploy/udev-demo 8000:80 # then curl localhost:8000
For many workspaces, run the dispatcher and POST to it instead of writing YAML by hand:
cd dispatcher && npm install && UDEV_DOMAIN=udev.example.com npm start
curl -X POST localhost:8077/launch -H 'content-type: application/json' \
-d '{"repo":"git@github.com:me/api.git","branch":"main","prompt":"add a /metrics endpoint"}'
# -> { "id": "...", "url": "http://....udev.example.com/" }
Wire …/webhooks/github, …/webhooks/gitlab, …/webhooks/jira to your
providers; a comment "/udev <prompt>" launches a workspace and replies with a URL.
What Claude can do (the udev MCP)
Every workspace registers a udev MCP server (user scope) so the Claude running
inside it can inspect, operate, and debug the workspace — not just read logs.
Logs are also plain files under .udev/logs/, so Claude can grep/read them
directly too.
| Tool | What it does |
|---|---|
describe_workspace | Full config: components, their dirs/repos, run program names, ports, routes, build/setup commands, app ports, feature flags. The place to start. |
get_manifest | Raw project manifest (project.yaml/udev.yaml). |
get_gateway_config | The rendered nginx routing config. |
list_processes | Status of every supervised process (claude-ui, code-server, logserver, each component run-*). |
app_status | Per-app view: each component's process with a normalized state (running/stopped/errored/starting/not-running), port, routes, and log file. |
start_process / stop_process / restart_process | Control a process by program name (e.g. restart after a rebuild). |
git_status / git_push / git_pull | Git in the workspace (or a component dir); push uses the injected credentials. |
build / setup | Run a component's build/setup steps in its own dir+env (or all components). |
list_logs / tail_log / search_logs | List, tail, or regex-search across all process + frontend logs. |
clear_logs | Truncate logs to empty for a clean slate between runs (optionally one file). |
Disable with UDEV_MCP=0. The same frontend.log also captures the browser's
console.*, uncaught errors, unhandled rejections, CSP violations, and failed
fetch/XHR — so Claude can debug front-end issues from the logs too.
Approvals via Slack (optional)
Gate selected tool uses behind a Slack Approve/Deny click. Set
UDEV_APPROVAL_GATE to a comma list — each entry is Tool (gate all uses) or
Tool:substring (gate only when the input contains the substring):
UDEV_APPROVAL_GATE=Write,Bash:git push,Bash:deploy
SLACK_BOT_TOKEN=xoxb-… # chat:write
SLACK_APP_TOKEN=xapp-… # Socket Mode (connections:write) — no public URL needed
UDEV_APPROVAL_CHANNEL=#approvals
UDEV_APPROVAL_TIMEOUT=300 # seconds; on timeout -> UDEV_APPROVAL_DEFAULT (deny)
A gated tool triggers a Claude Code PreToolUse hook (installed into
~/.claude/settings.json) that blocks on a per-workspace broker, which posts
Approve/Deny to Slack and resolves on your click. Without Slack tokens the broker
runs in core mode (POST /decide on 127.0.0.1:8095) — used by the tests and
any other approval UI. Caveat: the hook governs claude CLI sessions
(terminal, the seed prompt); CloudCLI's in-browser agent uses the Agent SDK's own
approval flow, so verify hook coverage there for your version.
Secrets & git (private repos)
Never baked into the image — passed at runtime via env / K8s Secret:
| Var | Purpose |
|---|---|
GIT_TOKEN, GIT_TOKEN_USER, GIT_HOST | HTTPS pull/push for private repos |
GIT_SSH_KEY | path to a mounted SSH deploy key (push) |
GIT_USER_NAME, GIT_USER_EMAIL | commit identity |
ANTHROPIC_API_KEY | Claude auth (or persist claude login on a PVC) |
GITLAB_TOKEN, JIRA_TOKEN, … | referenced by MCP servers in the manifest |
Sidecars & multi-process
- Inside a pod, containers share
localhost+ volumes — the nginx gateway reaches the services on127.0.0.1(that's whyUDEV_ROUTE_HOSTdefaults to loopback on K8s andworkspaceon compose). Add MCP servers or a log shipper as extra containers in the same pod. - Across workspaces, talk over K8s Services.
Mixed Windows + Linux
os: windows in a manifest sets nodeSelector: kubernetes.io/os: windows.
Run a Windows node pool alongside Linux (Windows containers need a Windows
host); the Linux path is the default and untaxed. A Windows variant of the
workspace image is the remaining piece to add when you need it.
Environment variable reference
Every knob, in one place. Most have sane defaults — you typically only set the
feature flags, secrets, and (under a nesting proxy) UDEV_BASE_PATH. The
dispatcher derives most of these from the manifest for you.
Path control & routing — where the built-in services live and how the gateway reaches them:
| Var | Default | Purpose |
|---|---|---|
UDEV_CLAUDE_PREFIX | /__claude | Public path for the CloudCLI UI. Namespaced under /__ so it can't collide with your app's routes; override if even that clashes. |
UDEV_CODE_PREFIX | /__code | Public path for code-server. |
UDEV_LOGS_PREFIX | /__logs | Public path for the log search UI (and its /api). |
UDEV_BASE_PATH | (empty) | Nest the whole workspace under a prefix (e.g. /udev/123); the gateway emits every URL with it and assumes your outer proxy strips it. See Deploying under a path. |
UDEV_ROUTE_HOST | 127.0.0.1 | Host the gateway proxies upstreams to. Loopback in a shared-netns pod; set to workspace in compose (separate containers). |
UDEV_CLAUDE_PORT | 3001 | Upstream port the CloudCLI UI listens on. |
UDEV_CODE_PORT | 8080 | Upstream port code-server listens on. |
UDEV_LOGS_PORT | 8090 | Upstream port the logserver listens on. |
Feature flags — also settable via features: in the manifest (see table above):
UDEV_CLAUDE_REWRITE, UDEV_FRONTEND_LOGS (on), UDEV_NAV (on), UDEV_NAV_IN_CODE.
Behavior toggles:
| Var | Default | Purpose |
|---|---|---|
UDEV_MCP | 1 | Register the udev MCP server for Claude. 0 to disable. |
UDEV_PROMPT | (empty) | A seed prompt to hand the claude CLI on boot (the dispatcher sets this from a launch/webhook). |
UDEV_DOMAIN | (dispatcher) | Base domain the dispatcher builds per-workspace URLs from (<id>.<domain>). |
Approvals (Slack): UDEV_APPROVAL_GATE, SLACK_BOT_TOKEN, SLACK_APP_TOKEN, UDEV_APPROVAL_CHANNEL, UDEV_APPROVAL_TIMEOUT, UDEV_APPROVAL_DEFAULT, and UDEV_APPROVAL_PORT (default 8095, the broker's loopback listen port) — see Approvals via Slack.
Secrets & git: GIT_TOKEN, GIT_TOKEN_USER, GIT_HOST, GIT_SSH_KEY, GIT_USER_NAME, GIT_USER_EMAIL, ANTHROPIC_API_KEY, GITLAB_TOKEN, JIRA_TOKEN, … — see Secrets & git.
Plumbing — paths the entrypoint and renderer use; the image sets these, override only for an unusual layout:
| Var | Default | Purpose |
|---|---|---|
UDEV_MANIFEST | /etc/udev/project.yaml | The baked/mounted project manifest. |
UDEV_REPO_MANIFEST | /workspace/udev.yaml | In-repo manifest checked out with the code; overrides the baked one when present. |
UDEV_WORKSPACE | /workspace | Root of the checkout. |
UDEV_RUN_DIR | /opt/udev/run | Scratch dir for rendered supervisor config. |
UDEV_LOG_DIR | /workspace/.udev/logs | Per-process + frontend log files. |
UDEV_SUPERVISOR_CONF | /opt/udev/run/supervisord.conf | Rendered supervisor program list. |
UDEV_NGINX_CONF | /etc/nginx/dynamic/nginx.conf | Rendered gateway config (compose/k8s point the nginx sidecar here). |
Status
Validated locally (compose + kind): image, manifest render, nginx routing
(root app at /, Claude UI at /__claude, /__code/, /__logs, user routes),
log search, and K8s deploy via the dispatcher. See dispatcher/ for the launch API
and webhooks.