convez.ai
AgenteDevOps & InfraestruturaIntermediário
Mrliuch

Claude Agent

Mrliuch/claude-agent

Controle remoto auditável de Claude Code com aprovação humana integrada

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent remoto em Go que permite controlar Claude Code em uma máquina alvo via WebSocket, com aprovação do usuário no navegador para cada ação sensível. Distribuído como um único binário com console web embutido e zero dependências externas.

Instalação

$npx convez-ai Mrliuch/claude-agent

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
4
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
v1.5.7
Issues abertas
0
Contribuidores
1

Casos de uso

  • Executar Claude Code em servidores de produção remotos com controle local
  • Automatizar tarefas em máquinas atrás de bastion ou VMs isoladas
  • Auditar e aprovar manualmente cada ação perigosa (Bash, file writes) antes da execução

Veredito

Ferramenta especializada e bem-executada para quem precisa rodar Claude Code em infraestrutura remota com segurança. A arquitetura de human-in-the-loop é sólida e o zero-dependency binary elimina fricção de deployment.

README

A tradução para o português deste README ainda está na fila.

claude-agent

English · 简体中文

A tiny, single-binary agent that lets you drive Claude Code on a remote machine from your browser — over WebSocket, with human-in-the-loop approval for every dangerous action.

claude-agent runs on a target server, spawns the locally-installed claude CLI as a subprocess (speaking its stream-json bidirectional control protocol), and exposes a token-authenticated WebSocket endpoint. It ships with a zero-dependency web console embedded in the binary, so you can point a browser at it and start working immediately.

  Browser ──WS──> claude-agent (target host) ──subprocess──> claude code CLI
   web console        token auth                              runs on the box itself

No API keys live in the agent. Credentials, model selection, and any third-party gateway config are entirely owned by the claude CLI on the target machine — the agent just drives it.

claude-agent web console


Why

Sometimes the box you need Claude Code to work on isn't the box in front of you: a production server, a build host, a VM behind a bastion. claude-agent gives that box a thin, auditable remote-control surface:

  • Single static binary, zero runtime dependencies — drop it on the host and run.
  • Embedded web console — no separate frontend to build or host.
  • Permission prompts surface in your browser. The agent runs claude with --permission-mode default, so every privileged tool call (Bash, file writes, …) is forwarded to you as a permission_request and only executes after you click Allow.
  • Fenced file manager — browse / view / download / upload within the working directory, with strict path-jail (no .. escape, no symlink escape).
  • Embeddable — the same WebSocket endpoint can sit behind your own auth-relay backend if you'd rather not expose the agent directly.

Quick start

1. Prerequisites

On the target machine:

  • The claude CLI is installed and works when run manually by the same user that will run the agent (i.e. claude can already authenticate and hold a conversation). The agent inherits whatever credentials/config that user's claude already has.
  • Go 1.25+ (only if you build from source).

2. Build & run

git clone https://github.com/Mrliuch/claude-agent.git
cd claude-agent
go build -o claude-agent .

# pick a long random shared token
AGENT_TOKEN=$(openssl rand -hex 24) ./claude-agent

Then open http://<host>:8765/ in a browser, paste the same token, and hit Connect.

The web console is served at / from the same origin, so there are no CORS hoops. The token you paste in the browser is not baked into the served HTML.


Configuration

All configuration is via environment variables.

VariableDescriptionDefault
AGENT_TOKENRequired. Shared auth token; clients must present it.—
AGENT_LISTEN_ADDRListen address.:8765
AGENT_UISet to off to disable the built-in web console at /.on
CLAUDE_BINPath/command for the Claude Code CLI.claude
CLAUDE_MODELModel to pass to claude; empty = CLI default.(empty)
CLAUDE_WORK_DIRWorking directory for claude (and the file-manager jail root). Empty = the run user's $HOME.(empty)
CLAUDE_PERMISSION_MODEPassed to claude --permission-mode. Keep default so dangerous ops prompt.default
CLAUDE_IDLE_TIMEOUTSeconds of inactivity before the session (and the claude child process) is reaped. 0 = disabled.1800
AGENT_DEBUGSet to any value to log raw bridge traffic.(empty)

⚠️ Never set CLAUDE_PERMISSION_MODE to anything that bypasses prompts on a host you care about. The whole point is that you approve each action.


Deployment

Option A — Run the binary directly (recommended)

Running on the host directly means claude can see the real host filesystem — best for actually troubleshooting that machine.

/etc/systemd/system/claude-agent.service:

[Unit]
Description=claude-agent
After=network.target

[Service]
User=ops
Environment=AGENT_TOKEN=<your-random-token>
Environment=AGENT_LISTEN_ADDR=:8765
Environment=CLAUDE_WORK_DIR=/home/ops
ExecStart=/usr/local/bin/claude-agent
Restart=always

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload && sudo systemctl enable --now claude-agent

Option B — Docker

The provided Dockerfile builds the agent and bundles Node + the Claude Code CLI.

docker build -t claude-agent .
docker run -d --name claude-agent -p 8765:8765 \
  -e AGENT_TOKEN=<your-random-token> \
  claude-agent

⚠️ Inside a container, claude only sees the container's filesystem. To work on the host, prefer Option A, or mount host paths / use --network host and grant access deliberately.


Security model

claude-agent gives a browser the ability to run commands on a machine. Treat the token like a production credential and lock the surface down:

  • Firewall the port. Only allow the networks/hosts that should reach it.
  • The token rides in the query string (WebSocket can't carry custom headers easily). Put TLS in front for anything beyond a trusted LAN/VPN — terminate wss:// at a reverse proxy, or tunnel over SSH/VPN.
  • Approval is mandatory by design. With --permission-mode default, no privileged tool runs until you allow it in the browser. Deny is always one click away (or Esc).
  • The file manager is path-jailed to CLAUDE_WORK_DIR: lexical .. is neutralized and symlinks are resolved and re-checked against the jail root before any read/write.
  • Disable the console with AGENT_UI=off if you only want to drive the agent from your own backend relay.

Web console

Served at / (unless AGENT_UI=off). It's a single self-contained HTML file embedded in the binary — no build step, no external fonts or CDNs, works offline.

  • Chat with the remote Claude: streamed assistant text, tool-use cards, and tool output.
  • Native command bar — one click sends /clear, /compact, /context, /usage, /cost, or /init straight to Claude (these run over the same stream-json channel).
  • Authorization overlay for every permission_request — see the exact tool + input before allowing/denying.
  • Files drawer — browse the working directory, view text files, download, all jailed.
  • History sessions — see the current directory's past Claude sessions, read any transcript, and resume one to continue with full context (--resume).
  • Session continuity — the console remembers the session_id and reconnects with --resume; ⌘/Ctrl+K starts a fresh session.
  • Bilingual UI — one-click English ⇄ 中文 toggle in the top-right (remembers your choice).

Every dangerous action stops for your approval:

Authorization overlay

Browse and resume the working directory's Claude history:

History sessions


Using it behind your own backend (relay mode)

The WebSocket endpoint is transport-agnostic: any backend can authenticate its own users however it likes, then transparently relay frames to claude-agent. The agent stays a dumb, token-gated executor; your backend never needs an API key. Set AGENT_UI=off and the agent becomes purely a protocol endpoint.


Protocol reference

WebSocket: GET /agent/chat?token=<AGENT_TOKEN>[&session_id=<id>] Health check: GET /healthz → {"status":"ok"}

Client → server

{ "type": "user_message", "text": "check disk usage" }
{ "type": "user_message", "text": "/context" }   // native slash commands work too
{ "type": "permission_response", "request_id": "...", "allow": true, "tool_input": { } }
{ "type": "close" }

Native Claude slash commands (/clear, /compact, /context, /usage, /cost, /init, …) are just user messages whose text starts with / — Claude interprets them over the same stream-json channel, so the console's command bar simply sends them.

Server → client

typeMeaning
readySession is up. Carries cwd, session_id.
assistantblocks[] of {kind:"text"} / {kind:"tool_use", name, input}.
tool_resultresults[] of {content, is_error}.
permission_requestrequest_id, tool_name, tool_input, title, description.
resultTurn summary: subtype, is_error, duration_ms, total_cost_usd, result.
error{msg}.
closedclaude exited; stderr tail included.

File-manager HTTP API

All require ?token=<AGENT_TOKEN>; all paths are relative to and jailed within CLAUDE_WORK_DIR. Responses use the envelope {code, msg, data} (code:0 = ok).

Method & pathPurpose
GET /agent/fs/list?path=List a directory.
GET /agent/fs/read?path=Read a text file (≤1 MB, truncates).
GET /agent/fs/treeRecursive relative paths (skips .git, node_modules, …).
GET /agent/fs/download?path=Stream any file.
POST /agent/fs/write{path, content}.
POST /agent/fs/upload{path, content_b64} (≤50 MB).
POST /agent/fs/mkdir{path}.
DELETE /agent/fs/delete?path=Remove (cannot delete the jail root).

Session-history HTTP API

Read-only access to the current working directory's Claude session history (stored by the CLI under ~/.claude/projects/<slug>/<id>.jsonl). Token-gated; same {code, msg, data} envelope.

Method & pathPurpose
GET /agent/sessions/listList this directory's sessions (id, title, messages, mtime, size) plus its cwd.
GET /agent/sessions/read?id=<uuid>Parse a session into a read-only transcript (items[] of {role, blocks, ts}).

To resume a session, just open a chat WebSocket with &session_id=<id> — Claude reattaches with --resume and the prior context.


Development

go vet ./...
go test ./...     # includes an end-to-end test against a fake claude (zero API cost)
go build -o claude-agent .

The test suite uses cmd/fakeclaude, a stub that speaks the stream-json control protocol, so the full bridge + WebSocket + permission roundtrip is exercised without calling the real Claude API. cmd/smoke is a one-shot client for verifying a live deployment:

go build -o smoke ./cmd/smoke
./smoke ws://<host>:8765/agent/chat <AGENT_TOKEN> "reply with: hello"

Project layout

main.go        entrypoint
config.go      env-driven config
server.go      HTTP/WebSocket routes, heartbeat, idle reaping
bridge.go      drives the claude CLI subprocess (stream-json)
protocol.go    translates claude messages → browser-friendly events
fs.go          path-jailed file-manager endpoints
sessions.go    read-only Claude session history (list + transcript)
web.go         embeds & serves the console
web/index.html the zero-dependency web console
cmd/fakeclaude a stub claude for tests
cmd/smoke      a one-shot deployment smoke client

License

MIT

This project drives the Claude Code CLI but is not affiliated with or endorsed by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.

Ver o original no GitHub

Bom para

Relacionados