convez.ai
MCP ServerDevOps & InfraestruturaAvançado
ClickerMonkey

udev — Ambientes de Desenvolvimento IA sob Demanda

ClickerMonkey/udev

Workspaces IA isolados por tarefa, browser-first, K8s-ready

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP 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/udev

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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.

PathWhat
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.mjsManifest → supervisord config, nginx gateway routes, MCP config, env.
workspace-image/bin/entrypoint.shBoots a project: git creds → clone → in-repo manifest → setup/build → launch.
workspace-image/bin/{logserver,udev-mcp,approval-*}.mjsLog 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.yamlThe 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)

FlagEnvDefaultEffect
claudeRewriteUDEV_CLAUDE_REWRITE=1offnginx 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.
frontendLogsUDEV_FRONTEND_LOGS=0 to disableonInjects 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).
navUDEV_NAV=0 to disableonInjects a tiny center-top nav bar (your app + CloudCLI).
navInCodeUDEV_NAV_IN_CODE=1offAlso 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 absolute href/src to 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.

ToolWhat it does
describe_workspaceFull config: components, their dirs/repos, run program names, ports, routes, build/setup commands, app ports, feature flags. The place to start.
get_manifestRaw project manifest (project.yaml/udev.yaml).
get_gateway_configThe rendered nginx routing config.
list_processesStatus of every supervised process (claude-ui, code-server, logserver, each component run-*).
app_statusPer-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_processControl a process by program name (e.g. restart after a rebuild).
git_status / git_push / git_pullGit in the workspace (or a component dir); push uses the injected credentials.
build / setupRun a component's build/setup steps in its own dir+env (or all components).
list_logs / tail_log / search_logsList, tail, or regex-search across all process + frontend logs.
clear_logsTruncate 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:

VarPurpose
GIT_TOKEN, GIT_TOKEN_USER, GIT_HOSTHTTPS pull/push for private repos
GIT_SSH_KEYpath to a mounted SSH deploy key (push)
GIT_USER_NAME, GIT_USER_EMAILcommit identity
ANTHROPIC_API_KEYClaude 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 on 127.0.0.1 (that's why UDEV_ROUTE_HOST defaults to loopback on K8s and workspace on 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:

VarDefaultPurpose
UDEV_CLAUDE_PREFIX/__claudePublic 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/__codePublic path for code-server.
UDEV_LOGS_PREFIX/__logsPublic 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_HOST127.0.0.1Host the gateway proxies upstreams to. Loopback in a shared-netns pod; set to workspace in compose (separate containers).
UDEV_CLAUDE_PORT3001Upstream port the CloudCLI UI listens on.
UDEV_CODE_PORT8080Upstream port code-server listens on.
UDEV_LOGS_PORT8090Upstream 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:

VarDefaultPurpose
UDEV_MCP1Register 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:

VarDefaultPurpose
UDEV_MANIFEST/etc/udev/project.yamlThe baked/mounted project manifest.
UDEV_REPO_MANIFEST/workspace/udev.yamlIn-repo manifest checked out with the code; overrides the baked one when present.
UDEV_WORKSPACE/workspaceRoot of the checkout.
UDEV_RUN_DIR/opt/udev/runScratch dir for rendered supervisor config.
UDEV_LOG_DIR/workspace/.udev/logsPer-process + frontend log files.
UDEV_SUPERVISOR_CONF/opt/udev/run/supervisord.confRendered supervisor program list.
UDEV_NGINX_CONF/etc/nginx/dynamic/nginx.confRendered 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.

Ver o original no GitHub

Bom para

Relacionados