Termcp

⚡ termcp

English | 中文

Introducción

termcp es una plataforma de terminal nativa para IA: muchos hosts y muchas sesiones a la vez, totalmente visualizada. Esas sesiones son gestionadas y mantenidas por humanos e IA juntos, y cada parte puede tomar el control o cedérselo a la otra en cualquier momento; los perfiles de conexión se mantienen de forma independiente por la plataforma, por lo que un Agente puede usar una conexión sin leer jamás sus credenciales.

• Tú (humano) — una interfaz web basada en navegador para observación en vivo y toma de control instantánea de cualquier sesión;
• Agentes de IA — manejan los mismos terminales reales a través de MCP o SKILLS;
• Scripts / programas — una API REST completa más un canal WebSocket para operaciones programáticas de sesión, reenvío y archivos.

En la capa de plataforma, sesiones de larga duración con reproducción de solo lectura, orquestación paralela de múltiples hosts / múltiples sesiones, y un ciclo de vida completo de conexión SSH mantienen todo el bucle observable, programable y fácil de transferir entre humano e IA. Multiplataforma y nativo de la nube, escrito en Go puro sin CGO: se distribuye como un único binario ligero que se ejecuta de forma persistente con baja sobrecarga, y la concurrencia con goroutines mantiene un alto rendimiento y baja latencia.

Video de demostración

introduce1.0.mp4

Por qué termcp

Gestión visual de múltiples sesiones

Una potente interfaz web gestiona muchos hosts y muchas sesiones en un solo lugar: iníciala localmente con un solo comando o despliega el contenedor en la nube — el navegador obtiene la misma interfaz en ambos casos.

• Panel de múltiples sesiones: cada sesión en ejecución listada por nombre, cambia o toma el control en cualquier momento.
• Observación en tiempo real: observa la pantalla en vivo de htop, el proceso de edición de vim, o los avisos de un instalador en el navegador, igual que un terminal local.
• Pestañas y espacio de trabajo en mosaico: una sesión SSH puede abrir varias consolas, cada una con su propia pestaña; las sesiones también se pueden colocar en mosaico lado a lado y rastrearse juntas.
• Reenvío de puertos de un vistazo: puertos y protocolos locales/remotos para cada sesión, todo en un solo panel.
• Gestión de archivos: navega, sube, descarga, renombra y crea directorios desde la interfaz.
• Plantillas de conexión centralizadas: un almacén unificado de configuración SSH; el Agente abre sesiones por nombre de perfil y nunca lee la configuración en sí.
• Reproducción de solo lectura de sesiones cerradas: la salida sigue siendo navegable después de que una sesión se cierra, falla o sobrevive a un reinicio.

Diseñado nativamente para IA

Interacción fluida humano-agente y operación en pareja: el Agente es un usuario permanente del terminal, junto a ti y tus scripts.

Un Agente ejecuta nativamente solo comandos de un solo disparo, mientras que el trabajo real es en gran parte interacción de múltiples turnos — el inicio de sesión SSH necesita una contraseña primero, un REPL de Python se depura línea por línea, un instalador pregunta por [Y/n], herramientas como top / htop /impacket necesitan un terminal. termcp entrega al Agente un terminal real: una sesión permanece viva y se reutiliza, por lo que TUIs, REPLs, GDB, msfconsole y vim pueden manejarse de forma continua como lo haría un humano — a través de MCP o mediante la Habilidad de Agente de la propia instancia sobre curl simple.

• Una capa de sesión, entradas pares. MCP, SKILLS y REST/WebSocket se sitúan al mismo nivel que la interfaz web, compartiendo las mismas sesiones reales. Puedes observar cada paso del Agente en el navegador y tomar el control en cualquier momento; el Agente a su vez puede pausar y entregarte un aviso de contraseña/MFA.
• Diseñado para presupuestos de tokens y turnos. Los esquemas de herramientas son compactos y pueden cargarse de forma diferida (ver docs/mcp-tools.md); shell_output pagina con cursores de cola/desplazamiento para que solo los fragmentos que pidas entren en la ventana de contexto; shell_notify envía una señal de activación simple; message obtiene la salida completa solo cuando se solicita.
• Instancias autodescriptivas. Cada termcp en ejecución sirve su propio /api.md y /skills.md (sin necesidad de token) y los registra como recursos MCP más un aviso de learn-api, para que un Agente nuevo pueda manejar esta instancia exacta de inmediato, usando solo estos dos archivos.
• Los secretos permanecen en el servidor. Las contraseñas, claves privadas y frases de paso escritas a través de ssh_config se almacenan solo en el host, y la interfaz de lectura MCP devuelve solo nombres de perfiles; las herramientas de escritura de configuración SSH permanecen desactivadas a menos que el operador opte por activarlas con --mcp-manage-ssh-configs.
• Trabajo tolerante a fallos y reanudable. Una sesión cerrada, bloqueada o reiniciada permanece en la lista de sesiones como un mosaico DEAD de solo lectura con su salida legible, para que un Agente (o tú) pueda retomar desde el estado interrumpido; reconectar el mismo termcp://<entry> inicia una sesión nueva.
• Los humanos siempre mantienen la opción de intervenir. notify_user te llega directamente, los avisos privilegiados están pensados para que los escribas tú en la interfaz web, y las escrituras en una consola se serializan, para que un humano y un Agente puedan escribir en el mismo terminal con sus entradas aplicadas en orden.

Navegación rápida

Características

• ⚡ Instalación con un comando, Go puro, sin CGO — go install github.com/open-mcp-ai/termcp@latest; se compila con CGO_ENABLED=0 y no enlaza bibliotecas compartidas del sistema, por lo que un solo binario estático se ejecuta en cualquier lugar y se compila de forma nativa para múltiples plataformas (ConPTY en Windows, PTY POSIX en macOS / Linux — mismo comportamiento en todas partes).
• 🔌 Un puerto, cuatro entradas — Interfaz web (humanos), MCP / SKILLS (Agentes), y REST + WebSocket (scripts) comparten un puerto.
• 🤝 Relevo humano-IA — Tú y el Agente comparten una sesión en vivo y puedes tomar el control o interrumpir en cualquier momento; el Agente se pausa en avisos de sudo / contraseña / MFA para que escribas en la interfaz web; la entrada se serializa para que las pulsaciones de teclas nunca colisionen.
• 🟦 Interacción de múltiples turnos en un terminal real — El proceso sigue ejecutándose, por lo que un Agente maneja TUIs, REPLs, GDB, msfconsole o vim a lo largo de los turnos de conversación; un PTY completo (ConPTY en Windows) se comporta igual en todas las plataformas.
• 🟫 Local o remoto, un solo flujo de trabajo — Acceso sin configuración al host termcp (ssh_config="internal") o a cualquier máquina remota mediante perfiles SSH; comandos, transferencia de archivos (SFTP más URLs HTTP reanudables) y reenvío de puertos (-L / -R / -D) se ejecutan todos sobre esa única conexión.
• 🟧 Gestión visual integrada — Terminales en vivo en el navegador, panel de sesiones, consolas con pestañas, espacio de trabajo en mosaico, reproducción de solo lectura de sesiones cerradas, paneles de archivos y reenvío; /api.html contiene la hoja de referencia de API / MCP / SKILLS.
• 🟨 Múltiples Agentes, sin salida perdida — Los lectores paralelos de una sesión mantienen cursores independientes; una sesión cerrada (cierre explícito, salida, fallo o reinicio) permanece en el registro como un mosaico DEAD de solo lectura con su salida completa intacta, para que puedas reproducirla, paginarla o eliminarla cuando quieras. Después de una caída, abre una sesión nueva desde la misma entrada (termcp://<entry>) y continúa.
• 🟥 Notificaciones proactivas, sin sondeo — shell_notify despierta al Agente al salir del proceso, en silencio o con nueva salida — solo señal, sin carga útil (extrae el texto cuando lo necesites); channel="sampling" envía sampling/createMessage directamente.
• 🔒 Seguro por diseño en cuanto a credenciales — Las contraseñas, claves privadas y frases de paso escritas a través de ssh_config nunca se pueden leer de vuelta, por lo que el texto plano nunca entra en el contexto del Agente; las herramientas de escritura de configuración permanecen desactivadas a menos que se establezca --mcp-manage-ssh-configs.

Inicio rápido

Instalación rápida (se requiere el kit de herramientas Go)

La forma más rápida de instalar — un comando, sin clonar, sin compilar:

go install github.com/open-mcp-ai/termcp@latest

go install resuelve el módulo a través del proxy de Go (usa GOPROXY=https://goproxy.cn,direct en China continental) y coloca el binario termcp en $(go env GOPATH)/bin — asegúrate de que ese directorio esté en tu PATH. termcp está escrito en Go, por lo que la instalación es go install o un binario de Release precompilado: no hay variante npx / uvx, y no necesita runtime de Node ni Python. Al ser un módulo de Go, también admite integración a nivel de código fuente: go get github.com/open-mcp-ai/termcp para incorporarlo como dependencia, o haz un fork y compila un binario personalizado desde el código fuente. Luego ejecuta:

termcp

Descarga

Ve a la página de Releases y descarga el binario precompilado para tu plataforma:

Plataforma	Archivo
Linux (x86_64)	termcp-linux-amd64
Linux (ARM64)	termcp-linux-arm64
macOS (Intel)	termcp-darwin-amd64
macOS (Apple Silicon)	termcp-darwin-arm64
Windows (x86_64)	termcp-windows-amd64.exe
Windows (ARM64)	termcp-windows-arm64.exe

Compilación

# Clone
git clone https://github.com/open-mcp-ai/termcp.git
cd termcp

# Build (pure Go — no CGO needed, cross-compiles to any platform)
CGO_ENABLED=0 go build -o termcp .

# Run (defaults: loopback, port 18765; data goes to ~/.termcp)
./termcp

Abre http://127.0.0.1:18765 en tu navegador para entrar en la interfaz web.

Uso

Línea de comandos

termcp [flags]

Indicador	Predeterminado	Descripción
--host	127.0.0.1	Dirección de enlace HTTP. 0.0.0.0 escucha en todas las interfaces. Un enlace que no sea de bucle local requiere un token/hash de autenticación (el inicio falla de lo contrario).
--port	18765	Puerto HTTP. Compartido por la interfaz web, MCP SSE, MCP HTTP transmisible y los endpoints de documentación/habilidades (/api.md, /skills.md).
--data-dir	~/.termcp	Directorio de persistencia (sesiones, mensajes, configuraciones SSH). Se crea automáticamente. El valor predeterminado se puede sobrescribir mediante $TERMCP_DATA_DIR.
--log-level	info	Nivel de registro: debug / info / warn / error. debug muestra todas las llamadas a herramientas MCP; las llamadas fallidas y los errores de creación de sesión se registran en warn / error independientemente.
--no-internal	false	Deshabilitar el perfil SSH de bucle local integrado.
--mcp-manage-ssh-configs	false	Habilitar que las herramientas MCP creen/editen/eliminen configuraciones SSH (los secretos nunca se exponen).
--auth-token	(sin establecer)	Token estático para autenticación HTTP (o $TERMCP_AUTH_TOKEN). Cada cliente — API, MCP, navegador — debe presentarlo. Mutuamente excluyente con --auth-hash.
--auth-hash	(sin establecer)	Hash SHA-256 con sal del token (sha256-<salt_hex>-<digest_hex>) para que el servidor nunca tenga el texto plano (o $TERMCP_AUTH_HASH). Genérelo con termcp --gen-auth-hash. Mutuamente excluyente con --auth-token.
--disable-auth	false	Desactivar la autenticación HTTP a propósito, incluso en un enlace que no sea de bucle local (o $TERMCP_DISABLE_AUTH_TOKEN=1). Combínelo con un puerto de bucle local para que solo los llamadores locales puedan alcanzar el puerto. Combinarlo con --auth-token / --auth-hash es un error en lugar de un argumento que gana silenciosamente.
--mcp-defer-tools	false	Etiquetar herramientas MCP de baja frecuencia (file_*, forward, shell_resize, …) con defer_loading para que los clientes obtengan sus esquemas bajo demanda, reduciendo el tools/list inicial. Desactivado por defecto: los clientes que ignoran el marcador — o que hablan con termcp a través de una puerta de enlace que lo elimina — nunca verían esas herramientas de lo contrario. Consulte Carga diferida de herramientas.
--gen-auth-hash	(acción)	Generar el hash SHA-256 con sal de un token para --auth-hash, luego salir (token de un argumento, o de stdin sin eco en una terminal).
--version	(acción)	Imprimir versión, commit y fecha de compilación, luego salir. La versión sigue automáticamente la etiqueta git (las compilaciones de lanzamiento la inyectan mediante -ldflags; un go build / go install module@vX.Y.Z simple recurre a la versión del módulo incrustada por la cadena de herramientas Go).

Estos indicadores son sus puertas de capacidad: --no-internal limita los Agentes solo a hosts remotos, y --mcp-manage-ssh-configs es lo que abre el acceso de escritura a configuraciones SSH. Ajuste o afloje lo que los Agentes pueden tocar según el escenario. Consulte Autenticación a continuación.

Ejemplos

# Listen on all interfaces
./termcp --host 0.0.0.0 --auth-token "your-long-random-token"

# Listen on all interfaces with only a salted hash stored server-side
./termcp --host 0.0.0.0 --auth-hash "$(./termcp --gen-auth-hash)"

# Allow AI agents to manage SSH configs
./termcp --mcp-manage-ssh-configs

# Disable the built-in loopback profile (agents may only reach remote hosts)
./termcp --no-internal

Autenticación

Un único token estático protege toda la superficie HTTP — la interfaz web, la API REST, MCP SSE, MCP HTTP transmisible y el WebSocket del navegador. (La documentación de solo lectura /api.md y /skills.md permanece pública, para que un agente pueda obtenerla antes de tener un token.) Configurarlo es opcional para enlaces solo de bucle local (127.0.0.1 mantiene su valor predeterminado sin configuración); exponer un enlace que no sea de bucle local sin un token es un error de inicio.

# Plaintext: flag or env var
./termcp --auth-token "your-long-random-token"
TERMCP_AUTH_TOKEN="your-long-random-token" ./termcp

# Hashed (recommended): the server keeps only sha256-<salt>-<digest>.
# \`termcp --gen-auth-hash\` reads the token from stdin without echo on a terminal,
# so it never lands in shell history:
./termcp --gen-auth-hash
TERMCP_AUTH_HASH='sha256-...' ./termcp

Cómo presenta el token cada cliente:

Cliente	Credencial
API / MCP / curl	Encabezado Authorization: Bearer <token>
Navegador (interfaz web)	Solicitud de inicio de sesión nativa en 401 — el nombre de usuario se ignora (déjelo vacío), el token es la contraseña. Una cookie termcp_token se establece automáticamente para que los handshakes WebSocket del mismo origen también se autentiquen.

Notas de comportamiento:

• --auth-token y --auth-hash son mutuamente excluyentes; un valor de indicador anula la variable de entorno de la misma configuración.
• Un dos puntos dentro del token está bien: el servidor también acepta la cadena completa decodificada user:pass cuando es igual al token, por lo que los clientes que dividen en el primer dos puntos (p. ej., curl -u user:pass) aún se autentican. curl -u :<token> sigue siendo la forma canónica.
• Sin token o hash, el inicio falla en cualquier host que no sea de bucle local (0.0.0.0, una IP LAN o un nombre de host distinto de localhost), por lo que una instancia expuesta accidentalmente nunca puede ejecutarse sin autenticación.
• --disable-auth (o TERMCP_DISABLE_AUTH_TOKEN=1) elimina explícitamente ese requisito. Es la vía de escape para configuraciones solo de bucle local — videos de demostración, grabaciones de pantalla, estaciones de trabajo de un solo usuario — donde el token no protege nada. Debido a que es una anulación deliberada, combinarlo con --auth-token / --auth-hash es un error de inicio en lugar de un argumento que gana silenciosamente, y el registro de inicio cambia de la línea de autenticación informativa a una advertencia.
• Los navegadores usan HTTP Basic, que es Base64, no cifrado. Al servir termcp más allá de su propia máquina, termine TLS en un proxy inverso frente a él — la cookie termcp_token obtiene el indicador Secure automáticamente solo cuando la solicitud llegó a través de TLS.

Conexión a Hosts Remotos

Cero configuración: ssh_config="internal" impulsa el propio host de termcp. Para llegar a una máquina remota, cree un perfil SSH — en el diálogo de nueva conexión de la interfaz web (incluye una plantilla TOML y un botón Probar conexión), o mediante la API REST PUT /api/connections/<name> con un cuerpo TOML:

kind = "remote"
host = "192.168.1.100"
user = "pi"
trust_unknown_host = true  # first connect to an unknown host

# EITHER a password:
password = "..."

# OR the private key's PEM content itself — a path like "~/.ssh/id_ed25519" will NOT work:
private_key = """-----BEGIN OPENSSH PRIVATE KEY-----
<paste the full content of ~/.ssh/id_ed25519>
-----END OPENSSH PRIVATE KEY-----"""
key_passphrase = "..."     # only if the key is passphrase-protected

# Optional bastion (ProxyJump) hop:
[jump]
host = "bastion.example.com"
user = "ops"
password = "..."

Los perfiles viven en data-dir/ssh_configs/<name>/config.toml; lístelos con ssh_config(action=list). Las credenciales escritas de esta manera nunca se pueden leer de vuelta. Los Agentes también pueden crear perfiles, pero solo cuando termcp se inició con --mcp-manage-ssh-configs.

Implementación con Docker

Ejecutar la imagen oficial

La imagen del registro se ejecuta como no root termcp (uid/gid 1000) con /home/termcp declarado como VOLUME — todo el estado (sesiones, configuraciones SSH, historial de mensajes) se predetermina a ~/.termcp. Solo contiene el binario: sin entrypoint integrado ni puerto expuesto, por lo que el comando de ejecución decide la dirección de enlace.

docker run -d --name termcp -p 18765:18765 -v termcp-data:/home/termcp -e TERMCP_AUTH_TOKEN=change-me-to-a-long-random-secret ghcr.io/open-mcp-ai/termcp:latest termcp --no-internal --host 0.0.0.0 --port 18765

Los ejemplos de shell son de una sola línea a propósito: una continuación \ es bash válido pero un error de sintaxis en PowerShell, por lo que cada comando se pega tal cual en bash, zsh y PowerShell.

--host 0.0.0.0 es alcanzable desde fuera del contenedor, por lo que se requiere un token de autenticación. Endpoint MCP: http://localhost:18765/stream. Con un montaje de enlace en lugar de un volumen con nombre, haga chown del directorio del host primero: chown -R 1000:1000 /path/on/host.

Docker sin token (solo bucle local)

Para una demostración desechable, una grabación de pantalla o una estación de trabajo de un solo usuario, el token es fricción sin beneficio. Publique el puerto en el bucle local del host solamente e indique a termcp explícitamente que las credenciales faltantes son intencionales:

docker run -d --name termcp -p 127.0.0.1:18765:18765 -v termcp-data:/home/termcp ghcr.io/open-mcp-ai/termcp:latest termcp --no-internal --host 0.0.0.0 --port 18765 --disable-auth

Dos detalles hacen que esto sea seguro en lugar de meramente conveniente. -p 127.0.0.1:18765:18765 enlaza el puerto publicado al bucle local del host, por lo que el contenedor sigue siendo alcanzable para esta máquina e invisible para la LAN — el contenedor en sí aún escucha en 0.0.0.0 porque esa es la única dirección enrutable desde fuera de su espacio de nombres de red. Y --disable-auth se requiere precisamente porque termcp se niega a iniciar sin autenticación en un enlace que no sea de bucle local: el indicador es el operador asumiendo la responsabilidad, por lo que también degrada el registro de inicio a una advertencia. La forma de entorno equivalente es -e TERMCP_DISABLE_AUTH_TOKEN=1 en lugar del indicador.

Compilación de múltiples etapas: agregue termcp a cualquier contenedor

Coloque este Dockerfile en su proyecto de aplicación: la etapa de compilación instala termcp con go install, luego COPY --from copia el binario en la imagen de destino — no se necesita tiempo de ejecución Go allí.

# syntax=docker/dockerfile:1

ARG GO_IMAGE=golang:1.25-alpine
FROM ${GO_IMAGE} AS termcp-build

# Module proxy; use https://proxy.golang.org,direct outside China
ARG GOPROXY=https://goproxy.cn,direct
ENV GOPROXY=${GOPROXY} GOBIN=/out CGO_ENABLED=0

# Pin to a concrete version in production, e.g. @vX.Y.Z
RUN go install github.com/open-mcp-ai/termcp@latest

# Any target base image
FROM alpine
COPY --from=termcp-build /out/termcp /usr/local/bin/termcp

Cambie GOPROXY o GO_IMAGE por --build-arg si necesita otro proxy de módulos o espejo de imagen base.

Ejemplos de comandos de inicio

Los contenedores deben enlazar 0.0.0.0, y un enlace que no sea de bucle local requiere autenticación (TERMCP_AUTH_TOKEN / TERMCP_AUTH_HASH) o el inicio falla.

docker build --build-arg GOPROXY=https://goproxy.cn,direct -t my-app-with-termcp .
docker run -d --name my-app-termcp -p 18765:18765 -v termcp-data:/data -e TERMCP_AUTH_TOKEN=change-me-to-a-long-random-secret --entrypoint /usr/local/bin/termcp my-app-with-termcp --host 0.0.0.0 --port 18765 --data-dir /data
docker logs -f my-app-termcp

Agregue --mcp-manage-ssh-configs para abrir las herramientas de escritura de configuraciones SSH a los Agentes.

Si termcp debe compartir un contenedor con otro proceso principal, inícielo desde el entrypoint existente o el administrador de procesos; de lo contrario, ejecútelo como un servicio separado y alcáncelo en http://termcp:18765/stream.

Inicio con Docker Compose

services:
  termcp:
    build: .
    entrypoint: ["/usr/local/bin/termcp"]
    command: ["--host", "0.0.0.0", "--port", "18765", "--data-dir", "/data"]
    environment:
      - TERMCP_AUTH_TOKEN=change-me-to-a-long-random-secret
    ports:
      - "18765:18765"
    volumes:
      - termcp-data:/data

volumes:
  termcp-data:

docker compose up -d --build

Conexión de Clientes de IA (MCP)

termcp habla ambos transportes MCP en el mismo puerto (18765). Elija el que admita su cliente — la superficie de herramientas es idéntica.

termcp es un servicio de larga duración: el mismo puerto sirve la interfaz web, cualquier número de clientes MCP y la persistencia de sesiones. Por lo tanto, ofrece solo transportes HTTP — HTTP transmisible y SSE — y no admite stdio (no hay modo de subproceso local).

Alternativa: la Habilidad de Agente impulsa las mismas sesiones a través de curl simple — la instancia la sirve en /skills.md. El servidor MCP es una capa de interfaz de la plataforma, integrable en cualquier host compatible con MCP — Claude Code, Cursor, Codex, Open WebUI o su propio cliente.

Opción A — HTTP transmisible (/stream)

El transporte MCP moderno; un solo endpoint, sin ruta de mensajes separada. Úselo para Claude Code, Open WebUI y la mayoría de los clientes actuales.

{
  "mcpServers": {
    "termcp": {
      "type": "http",
      "url": "http://your-server:18765/stream"
    }
  }
}

claude mcp add --transport http termcp http://localhost:18765/stream

• Misma máquina: http://127.0.0.1:18765/stream.
• Open WebUI en Docker, termcp en el host: http://host.docker.internal:18765/stream (macOS/Windows), o la IP LAN del host.
• Ambos en Docker en la misma red (consulte Implementación con Docker): http://termcp:18765/stream.

Opción B — SSE (/sse)

El transporte heredado. Configure solo /sse; el SDK publica JSON-RPC a /message automáticamente.

{
  "mcpServers": {
    "termcp": {
      "type": "sse",
      "url": "http://your-server:18765/sse"
    }
  }
}

claude mcp add --transport sse termcp http://localhost:18765/sse

Hoja de referencia

• HTTP transmisible → http://<host>:18765/stream
• SSE → http://<host>:18765/sse (JSON-RPC va a POST /message)

La página API / MCP / SKILLS de la interfaz web (/api.html) ofrece configuraciones listas para copiar para ambos transportes, además de las direcciones de documentación de Agente y descarga de habilidades para esta instancia.

Habilidad de Agente (solo curl, sin MCP)

¿No quiere configurar un cliente MCP? La instancia incluye una Habilidad de Agente instalable que enseña a cualquier agente a impulsar termcp con curl solo — incluidos los localizadores termcp:// que los usuarios pegan desde la interfaz web.

# Public endpoint: no token needed for the download itself
curl -fsS http://<host>:18765/skills.md -o /tmp/termcp-SKILL.md

# Claude Code reads ~/.claude/skills/<name>/SKILL.md
mkdir -p ~/.claude/skills/termcp && cp /tmp/termcp-SKILL.md ~/.claude/skills/termcp/SKILL.md

# Other agents that follow the shared convention read ~/.agents/skills/<name>/SKILL.md
mkdir -p ~/.agents/skills/termcp && cp /tmp/termcp-SKILL.md ~/.agents/skills/termcp/SKILL.md

Reinicie la sesión del agente después de instalar (las habilidades se cargan al inicio de la sesión). Claude Code no tiene un comando CLI por habilidad — agregar es "colocar el archivo", eliminar es rm -rf ~/.claude/skills/termcp (o claude plugin install/uninstall cuando la habilidad se envía como complemento).

Una vez instalado, una solicitud tan simple como "abre termcp://rock64 y ejecuta uname -a " funciona de extremo a extremo: la habilidad resuelve el localizador mediante GET /api/resolve?url=..., crea la sesión con ese ssh_config, envía el comando y sondea la salida. La misma habilidad está registrada como el recurso MCP <origin>/skills.md, y /api.html muestra el comando de instalación exacto para la instancia que está viendo.

Conexión de Scripts / Programas (API REST)

Omita MCP y use la misma capa de sesión programáticamente: la API REST completa y el canal WebSocket en vivo.

# List sessions (same --auth-token protection)
curl -H "Authorization: Bearer $TERMCP_AUTH_TOKEN" http://127.0.0.1:18765/api/sessions

# Create a session
curl -X POST http://127.0.0.1:18765/api/sessions -H "Authorization: Bearer $TERMCP_AUTH_TOKEN" -H 'Content-Type: application/json' -d '{"ssh_config":"internal","command":"bash","mode":"pty"}'

# Read output / upload files / port forwards — see docs/api.md

La E/S de terminal en vivo se ejecuta a través de WebSocket /api/ui/ws; los archivos admiten URL HTTP directas con reanudación por Range. Lista completa de endpoints en docs/api.md.

Con autenticación habilitada

Cuando el servidor se ejecuta con --auth-token / --auth-hash, cada solicitud MCP necesita el token como encabezado Authorization: Bearer:

claude mcp add --transport http termcp http://your-server:18765/stream --header "Authorization: Bearer $TERMCP_AUTH_TOKEN"

{
  "mcpServers": {
    "termcp": {
      "type": "http",
      "url": "http://your-server:18765/stream",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Mantenga el token fuera de las URL y fuera de configuraciones/capturas de pantalla compartidas. curl y los scripts usan el mismo encabezado:

curl -H "Authorization: Bearer $TERMCP_AUTH_TOKEN" http://your-server:18765/api/sessions

Referencia de Herramientas

termcp expone 31 herramientas MCP. Los parámetros completos, las formas de retorno y los códigos de error viven en docs/mcp-tools.md.

Área	Herramientas
Sesiones (contenedores de conexión)	session_start, session_list, session_info, session_terminate (cerrar; mantiene la entrada DEAD legible), session_delete (permanente)
Shells (canales de terminal)	shell_open, shell_list, shell_close, shell_input, shell_key, shell_output, shell_resize, shell_reader_register, shell_reader_unregister
Notificaciones	shell_notify (despierta al Agente de IA), notify_user (notifica al humano en la Web UI)
Perfiles SSH	ssh_config (list; create / edit / copy / delete con --mcp-manage-ssh-configs)
Reenvío de puertos	forward (-L / -R / -D / lista / cerrar)
Archivos (SFTP)	file_read, file_write, file_stat, file_delete, file_rename, file_mkdir, file_urls, file_perm, file_link, file_fs, file_getwd
Historial y mensajes	message (lista / obtener)
Descubrimiento de hosts	shell_detect

Ejecuta un comando como shell_input + shell_key(key="enter") + shell_output. Las herramientas fallidas devuelven isError=true con un cuerpo JSON que lleva un error_code estable.

Carga diferida de herramientas

Un cliente MCP obtiene el esquema JSON de cada herramienta en tools/list, por lo que los servidores con muchas herramientas pagan por ello en el presupuesto de contexto. La especificación MCP ofrece una vía de escape: marca las herramientas de baja frecuencia con defer_loading, y un cliente carga su esquema bajo demanda. Las 31 herramientas de termcp se dividen en una ruta rápida de 12 (ciclo de vida de sesión + entrada/salida de shell — siempre listadas) y 19 superficies amplias y de baja frecuencia (las 11 herramientas SFTP file_*, forward, shell_resize / shell_detect / shell_notify, shell_reader_register / shell_reader_unregister, message, ssh_config).

--mcp-defer-tools activa el marcador y está desactivado por defecto, así que:

• Predeterminado — las 31 herramientas se listan de inmediato con esquema completo. Esto es lo que necesita cualquier cliente que no implemente carga diferida — incluido cualquier Codex que hable con termcp a través de una puerta de enlace como AxonHub, que puede eliminar el marcador defer_loading. Con el marcador perdido, esas herramientas no se pueden recargar bajo demanda y simplemente desaparecerían de la vista del modelo.
• --mcp-defer-tools — las 19 herramientas de baja frecuencia llevan defer_loading; las 12 herramientas principales permanecen inmediatas para que el bucle session_start → shell_input → shell_output nunca requiera un viaje de ida y vuelta de búsqueda. Los clientes que admiten carga bajo demanda (clientes basados en mcp-go, Claude Code) pagan solo por los esquemas que realmente usan.

Mismas 31 herramientas en cualquier caso: habilitar la bandera nunca elimina herramientas, solo retiene esquemas del listado inicial.

Limitaciones conocidas y modelo de seguridad

• Las herramientas de archivos y reenvío necesitan una conexión activa. En una sesión cerrada (DEAD) devuelven session_not_running; la lectura de salida aún funciona mediante shell_output, y los reenvíos de puertos de una sesión se cierran automáticamente cuando pasa a DEAD.
• La autenticación básica necesita TLS fuera de localhost. El desafío de inicio de sesión del navegador usa HTTP Basic, cuyas credenciales solo están codificadas en Base64. Coloca un proxy inverso con terminación TLS frente a termcp al exponerlo más allá de una red local confiable; el token estático nunca se registra ni se coloca en una URL.

🚨 Límite de seguridad: termcp no aplica seguridad (es una tubería, no un antivirus)

La línea de defensa pertenece al lado de salida de la IA y a tu puerta de enlace — no en la tubería del terminal. termcp NO es un antivirus, EDR o WAF.

termcp es una tubería transparente de terminal real y sesiones multiplexadas (transporte PTY) con la misma libertad y poder que el terminal de la propia máquina. Por lo tanto, no puede ni debe juzgar la intención de lo que transporta:

1. Por qué una tubería de terminal no puede detectar intenciones maliciosas.
   • La carga y ejecución no se pueden detener aquí. El contenido malicioso llega decodificado en Base64 a través de una tubería, se escribe en fragmentos o se obtiene mediante herramientas legítimas (curl / wget) en múltiples etapas y luego se le da chmod y se ejecuta. termcp es una tubería de datos, no un escáner de malware: inspeccionar cada byte transmitido en busca de un troyano simplemente no es algo que un transporte de bytes pueda hacer.
     • La ofuscación y concatenación son indecidibles en la capa de bytes. Una IA puede dividir un comando peligroso en fragmentos de cadena (a="rm -"; b="rf /"; $a$b), reconstruirlo mediante renombrado de variables, eval dinámico, inyección de printf, costura de variables de entorno, o escribiendo varios archivos parciales y ejecutándolos. Para el PTY, cada carácter es una pulsación legal; el transporte no puede distinguir "carga útil ofuscada" de "script de desarrollo ordinario".
2. La seguridad debe aplicarse aguas arriba.
   • El llamador (aplicación host / marco de Agente) debe proteger la salida de la IA antes de la llamada a la herramienta. Envuelve shell_input / file_write con barreras de salida, una capa de política de cumplimiento de instrucciones, filtros de contenido sensible o un modelo de seguridad que inspeccione el comando generado antes de que llegue a termcp. termcp no aplica listas de permitidos de comandos, jaulas de rutas ni niveles de riesgo basados en políticas.
     • Mantén a los humanos en el bucle para pasos privilegiados o destructivos. La Web UI muestra cada sesión en vivo y te permite tomar el control o interrumpir en cualquier momento. Trata sudo, comandos destructivos o irreversibles como eventos de aprobación humana — y nunca entregues acceso de terminal de alto privilegio sin supervisión a un host de producción que no esté en un entorno aislado.

---

Historial de estrellas

Licencia

Publicado bajo la Licencia MIT. Eres libre de usarlo, modificarlo y distribuirlo, siempre que se conserven el aviso de derechos de autor y el aviso de permiso. Gracias a la comunidad de linux.do por las discusiones y el apoyo.

---