Termcp

⚡ termcp

English | 中文

Introdução

termcp é uma plataforma de terminal nativa para IA: muitos hosts e muitas sessões ao mesmo tempo, totalmente visualizada. Essas sessões são gerenciadas e mantidas por humanos e IA juntos, cada lado livre para assumir ou devolver o controle ao outro a qualquer momento; os perfis de conexão são mantidos de forma independente pela plataforma, para que um Agente possa usar uma conexão sem nunca ler suas credenciais.

• Você (humano) — uma interface Web baseada em navegador para observação ao vivo e assunção instantânea de qualquer sessão;
• Agentes de IA — conduzem os mesmos terminais reais por meio de MCP ou SKILLS;
• Scripts / programas — uma API REST completa, além de canal WebSocket para operações programáticas de sessão, encaminhamento e arquivos.

Na camada da plataforma, sessões de longa duração com replay somente leitura, orquestração paralela de múltiplos hosts / múltiplas sessões e um ciclo de vida completo de conexão SSH mantêm todo o loop observável, programável e fácil de transferir entre humano e IA. Multiplataforma e nativa para nuvem, escrita em Go puro sem CGO: é distribuída como um único binário leve que roda de forma persistente com baixa sobrecarga, e a concorrência por goroutines garante alta taxa de transferência e baixa latência.

Vídeo de Demonstração

introduce1.0.mp4

Por que termcp

Gerenciamento visual de múltiplas sessões

Uma interface Web poderosa gerencia muitos hosts e muitas sessões em um só lugar: inicie localmente com um único comando ou implante o contêiner na nuvem — o navegador obtém a mesma interface de qualquer forma.

• Painel de múltiplas sessões: todas as sessões em execução listadas por nome, alterne ou assuma a qualquer momento.
• Observação em tempo real: assista à exibição ao vivo de htop, ao processo de edição de vim ou aos prompts de um instalador no navegador, como em um terminal local.
• Guias e espaço de trabalho em mosaico: uma sessão SSH pode abrir vários shells, cada um em sua própria guia; as sessões também podem ser dispostas lado a lado e acompanhadas em conjunto.
• Encaminhamento de portas em um relance: portas e protocolos locais/remotos de cada sessão, tudo em um único painel.
• Gerenciamento de arquivos: navegue, envie, baixe, renomeie e crie diretórios pela interface.
• Modelos de conexão centralizados: um armazenamento unificado de configuração SSH; o Agente abre sessões pelo nome do perfil e nunca lê a configuração em si.
• Replay somente leitura de sessões encerradas: a saída permanece navegável após uma sessão ser encerrada, falhar ou sobreviver a uma reinicialização.

Projetado para ser nativo de IA

Interação perfeita entre humano e agente e operação em parceria: o Agente é um usuário permanente do terminal, ao lado de você e de seus scripts.

Um Agente executa nativamente apenas comandos de uma única etapa, enquanto o trabalho real é em grande parte interação de múltiplas etapas — o login SSH precisa de senha primeiro, um REPL Python é depurado linha por linha, um instalador pergunta [Y/n], ferramentas como top / htop /impacket precisam de um terminal. termcp entrega ao Agente um terminal real: uma sessão permanece ativa e é reutilizada, para que TUIs, REPLs, GDB, msfconsole e vim possam ser conduzidos continuamente da mesma forma que um humano faria — por meio de MCP ou da própria Agent Skill da instância via curl simples.

• Uma camada de sessão, entradas de mesmo nível. MCP, SKILLS e REST/WebSocket ficam no mesmo nível da interface Web, compartilhando as mesmas sessões reais. Você pode observar cada passo do Agente no navegador e assumir a qualquer momento; o Agente, por sua vez, pode pausar e entregar um prompt de senha/MFA para você.
• Projetado para orçamentos de tokens e etapas. Os esquemas de ferramentas são compactos e podem ser carregados sob demanda (veja docs/mcp-tools.md); shell_output pagina por cursores de cauda/deslocamento para que apenas os trechos solicitados entrem na janela de contexto; shell_notify envia um sinal de ativação simples; message busca a saída completa somente quando solicitado.
• Instâncias autodescritivas. Cada termcp em execução serve seu próprio /api.md e /skills.md (sem necessidade de token) e os registra como recursos MCP, além de um prompt learn-api, para que um Agente novo possa conduzir esta instância exata imediatamente, usando apenas esses dois arquivos.
• Segredos permanecem no servidor. Senhas, chaves privadas e frases-senha escritas por meio de ssh_config são armazenadas apenas no host, e a interface de leitura MCP retorna apenas nomes de perfis; as ferramentas de escrita de configuração SSH permanecem desativadas, a menos que o operador opte por ativá-las com --mcp-manage-ssh-configs.
• Tolerante a falhas, trabalho retomável. Uma sessão encerrada, com falha ou reiniciada permanece na lista de sessões como um bloco DEAD somente leitura, com sua saída legível, para que um Agente (ou você) possa retomar do estado interrompido; reconectar o mesmo termcp://<entry> inicia uma nova sessão.
• Humanos sempre mantêm a opção de intervir. notify_user chega diretamente até você, prompts privilegiados devem ser digitados por você na interface Web, e as escritas em um shell são serializadas, para que um humano e um Agente possam digitar no mesmo terminal com suas entradas aplicadas em ordem.

Navegação Rápida

Recursos

• ⚡ Instalação com um comando, Go puro, sem CGO — go install github.com/open-mcp-ai/termcp@latest; compila com CGO_ENABLED=0 e não vincula bibliotecas compartilhadas do sistema, então um único binário estático roda em qualquer lugar e compila de forma cruzada nativamente (ConPTY no Windows, PTY POSIX no macOS / Linux — mesmo comportamento em todos os lugares).
• 🔌 Uma porta, quatro entradas — Interface Web (humanos), MCP / SKILLS (Agentes) e REST + WebSocket (scripts) compartilham uma porta.
• 🤝 Retransmissão humano–IA — Você e o Agente compartilham uma sessão ao vivo e você pode assumir ou interromper a qualquer momento; o Agente pausa em prompts de sudo / senha / MFA para você digitar na interface Web; a entrada é serializada para que as teclas nunca colidam.
• 🟦 Interação de múltiplas etapas em um terminal real — O processo continua em execução, então um Agente conduz TUIs, REPLs, GDB, msfconsole ou vim entre etapas de conversa; um PTY completo (ConPTY no Windows) se comporta da mesma forma em todas as plataformas.
• 🟫 Local ou remoto, um único fluxo de trabalho — Acesso sem configuração ao host termcp (ssh_config="internal") ou a qualquer máquina remota por perfis SSH; comandos, transferência de arquivos (SFTP além de URLs HTTP retomáveis) e encaminhamento de portas (-L / -R / -D) rodam todos sobre essa única conexão.
• 🟧 Gerenciamento visual integrado — Terminais ao vivo no navegador, painel de sessões, shells em guias, espaço de trabalho em mosaico, replay somente leitura de sessões encerradas, painéis de arquivos e encaminhamento; /api.html contém a folha de referência da API / MCP / SKILLS.
• 🟨 Múltiplos Agentes, sem saída perdida — Leitores paralelos de uma sessão mantêm cursores independentes; uma sessão encerrada (fechamento explícito, saída, falha ou reinicialização) permanece no registro como um bloco DEAD somente leitura com sua saída completa intacta, para que você ainda possa reproduzir, paginar ou excluir quando quiser. Após uma queda, abra uma nova sessão a partir da mesma entrada (termcp://<entry>) e continue.
• 🟥 Notificações proativas, sem polling — shell_notify acorda o Agente na saída do processo, silêncio ou nova saída — apenas sinal, sem carga útil (puxe o texto quando necessário); channel="sampling" envia sampling/createMessage diretamente.
• 🔒 Seguro por design em relação a credenciais — Senhas, chaves privadas e frases-senha escritas por meio de ssh_config nunca podem ser lidas de volta, então o texto simples nunca entra no contexto do Agente; as ferramentas de escrita de configuração permanecem desativadas, a menos que --mcp-manage-ssh-configs esteja definido.

Início Rápido

Instalação Rápida (requer toolchain Go)

A maneira mais rápida de instalar — um comando, sem clone, sem compilação:

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

go install resolve o módulo por meio do proxy Go (use GOPROXY=https://goproxy.cn,direct na China continental) e coloca o binário termcp em $(go env GOPATH)/bin — certifique-se de que esse diretório esteja no seu PATH. termcp é escrito em Go, então a instalação é go install ou um binário pré-compilado do Release: não há variante npx / uvx, e não precisa de runtime Node ou Python. Por ser um módulo Go, também suporta integração em nível de código-fonte: go get github.com/open-mcp-ai/termcp para trazê-lo como dependência, ou faça um fork e compile um binário personalizado a partir do código-fonte. Em seguida, execute:

termcp

Download

Acesse a página de Releases e baixe o binário pré-compilado para sua plataforma:

Plataforma	Arquivo
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

Compilação

# 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

Abra http://127.0.0.1:18765 no seu navegador para entrar na interface Web.

Uso

Linha de Comando

termcp [flags]

Flag	Padrão	Descrição
--host	127.0.0.1	Endereço de bind HTTP. 0.0.0.0 escuta em todas as interfaces. Um bind não-loopback exige um token/hash de autenticação (a inicialização falha caso contrário).
--port	18765	Porta HTTP. Compartilhada pela interface web, MCP SSE, MCP streamable HTTP e os endpoints de docs/skills (/api.md, /skills.md).
--data-dir	~/.termcp	Diretório de persistência (sessões, mensagens, configurações SSH). Criado automaticamente. O padrão pode ser sobrescrito via $TERMCP_DATA_DIR.
--log-level	info	Nível de log: debug / info / warn / error. debug mostra todas as chamadas de ferramentas MCP; chamadas de ferramentas com falha e erros de criação de sessão são registrados em warn / error independentemente.
--no-internal	false	Desativa o perfil SSH loopback integrado.
--mcp-manage-ssh-configs	false	Permite que as ferramentas MCP criem/editem/excluam configurações SSH (segredos nunca são expostos).
--auth-token	(não definido)	Token estático para autenticação HTTP (ou $TERMCP_AUTH_TOKEN). Todo cliente — API, MCP, navegador — deve apresentá-lo. Mutuamente exclusivo com --auth-hash.
--auth-hash	(não definido)	Hash SHA-256 com salt do token (sha256-<salt_hex>-<digest_hex>) para que o servidor nunca armazene o texto simples (ou $TERMCP_AUTH_HASH). Gere com termcp --gen-auth-hash. Mutuamente exclusivo com --auth-token.
--disable-auth	false	Desativa a autenticação HTTP de propósito, inclusive em um bind não-loopback (ou $TERMCP_DISABLE_AUTH_TOKEN=1). Combine com uma porta loopback para que apenas chamadores locais alcancem a porta. Combinar com --auth-token / --auth-hash é um erro, em vez de um argumento silenciosamente vencedor.
--mcp-defer-tools	false	Marca ferramentas MCP de baixa frequência (file_*, forward, shell_resize, …) com defer_loading para que os clientes busquem seus esquemas sob demanda, reduzindo o tools/list inicial. Desativado por padrão: clientes que ignoram o marcador — ou falam com o termcp por meio de um gateway que o remove — nunca veriam essas ferramentas. Veja Carregamento adiado de ferramentas.
--gen-auth-hash	(ação)	Gera o hash SHA-256 com salt de um token para --auth-hash e sai (token de um argumento, ou de stdin sem eco em um terminal).
--version	(ação)	Imprime versão, commit e data de build e sai. A versão segue a tag git automaticamente (builds de release a injetam via -ldflags; go build / go install module@vX.Y.Z simples cai para a versão do módulo embutida pela toolchain Go).

Essas flags são seus portões de capacidade: --no-internal restringe Agents a hosts remotos apenas, e --mcp-manage-ssh-configs é o que abre o acesso de escrita às configurações SSH. Aperte ou afrouxe o que os Agents podem tocar por cenário. Veja Autenticação abaixo.

Exemplos

# 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

Autenticação

Um único token estático protege toda a superfície HTTP — a interface web, a API REST, MCP SSE, MCP streamable HTTP e o WebSocket do navegador. (Os docs somente leitura /api.md e /skills.md permanecem públicos, para que um agente possa buscá-los antes de ter um token.) Configurá-lo é opcional para binds somente-loopback (127.0.0.1 mantém seu padrão sem configuração); expor um bind não-loopback sem token é um erro de inicialização.

# 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

Como cada cliente apresenta o token:

Cliente	Credencial
API / MCP / curl	Cabeçalho Authorization: Bearer <token>
Navegador (interface web)	Prompt de login nativo em 401 — o nome de usuário é ignorado (deixe vazio), o token é a senha. Um cookie termcp_token é então definido automaticamente para que handshakes WebSocket de mesma origem também autentiquem.

Notas de comportamento:

• --auth-token e --auth-hash são mutuamente exclusivos; um valor de flag sobrescreve a variável de ambiente da mesma configuração.
• Dois pontos dentro do token são aceitáveis: o servidor também aceita a string user:pass inteira decodificada quando ela é igual ao token, para que clientes que dividem no primeiro dois pontos (ex.: curl -u user:pass) ainda autentiquem. curl -u :<token> permanece a forma canônica.
• Sem token ou hash, a inicialização falha em qualquer host não-loopback (0.0.0.0, um IP LAN ou um hostname diferente de localhost), para que uma instância exposta acidentalmente nunca rode sem autenticação.
• --disable-auth (ou TERMCP_DISABLE_AUTH_TOKEN=1) remove explicitamente esse requisito. É a saída de emergência para configurações somente-loopback — vídeos de demonstração, gravações de tela, estações de trabalho de usuário único — onde o token não protege nada. Por ser uma sobrescrita deliberada, combiná-lo com --auth-token / --auth-hash é um erro de inicialização, em vez de um argumento silenciosamente vencedor, e o log de inicialização muda da linha informativa de autenticação para um aviso.
• Navegadores usam HTTP Basic, que é Base64, não criptografia. Ao servir o termcp além da sua própria máquina, encerre TLS em um proxy reverso na frente dele — o cookie termcp_token então recebe a flag Secure automaticamente apenas quando a solicitação chegou via TLS.

Conectando a Hosts Remotos

Zero configuração: ssh_config="internal" dirige o próprio host do termcp. Para alcançar uma máquina remota, crie um perfil SSH — no diálogo de nova conexão da interface web (que inclui um template TOML e um botão Testar conexão), ou via API REST PUT /api/connections/<name> com um corpo 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 = "..."

Os perfis ficam em data-dir/ssh_configs/<name>/config.toml; liste-os com ssh_config(action=list). Credenciais escritas dessa forma nunca podem ser lidas de volta. Agents também podem criar perfis, mas apenas quando o termcp foi iniciado com --mcp-manage-ssh-configs.

Implantação com Docker

Execute a imagem oficial

A imagem do registro roda como não-root termcp (uid/gid 1000) com /home/termcp declarado como VOLUME — todo o estado (sessões, configurações SSH, histórico de mensagens) tem como padrão ~/.termcp. Ela carrega apenas o binário: sem entrypoint embutido ou porta exposta, então o comando de execução decide o endereço de bind.

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

Os exemplos de shell são de linha única de propósito: uma continuação \ é bash válido, mas um erro de sintaxe no PowerShell, então todo comando cola como está em bash, zsh e PowerShell.

--host 0.0.0.0 é alcançável de fora do contêiner, então um token de autenticação é necessário. Endpoint MCP: http://localhost:18765/stream. Com um bind mount em vez de um volume nomeado, faça chown do diretório do host primeiro: chown -R 1000:1000 /path/on/host.

Docker sem token (somente loopback)

Para uma demonstração descartável, uma gravação de tela ou uma estação de trabalho de usuário único, o token é atrito sem benefício. Publique a porta somente no loopback do host e diga explicitamente ao termcp que as credenciais ausentes são intencionais:

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

Dois detalhes tornam isso seguro, em vez de meramente conveniente. -p 127.0.0.1:18765:18765 vincula a porta publicada ao loopback do host, então o contêiner permanece alcançável para esta máquina e invisível para a LAN — o contêiner em si ainda escuta em 0.0.0.0 porque esse é o único endereço roteável de fora do seu namespace de rede. E --disable-auth é necessário precisamente porque o termcp se recusa a iniciar sem autenticação em um bind não-loopback: a flag é o operador assumindo responsabilidade, e é por isso que também rebaixa o log de inicialização para um aviso. A forma equivalente de ambiente é -e TERMCP_DISABLE_AUTH_TOKEN=1 em vez da flag.

Build multi-estágio: adicione o termcp a qualquer contêiner

Coloque este Dockerfile no seu projeto de aplicação: o estágio de build instala o termcp com go install, então COPY --from copia o binário para a imagem de destino — sem necessidade de runtime Go lá.

# 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

Troque GOPROXY ou GO_IMAGE por --build-arg se precisar de outro proxy de módulo ou espelho de imagem base.

Exemplos de comando de inicialização

Contêineres devem fazer bind em 0.0.0.0, e um bind não-loopback exige autenticação (TERMCP_AUTH_TOKEN / TERMCP_AUTH_HASH) ou a inicialização falha.

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

Anexe --mcp-manage-ssh-configs para abrir as ferramentas de escrita de configuração SSH para Agents.

Se o termcp precisar compartilhar um contêiner com outro processo principal, inicie-o a partir do entrypoint existente ou do gerenciador de processos; caso contrário, execute-o como um serviço separado e alcance-o em http://termcp:18765/stream.

Inicialização com 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

Conectando Clientes de IA (MCP)

O termcp fala ambos os transportes MCP na mesma porta (18765). Escolha o que seu cliente suporta — a superfície de ferramentas é idêntica.

O termcp é um serviço de longa duração: a mesma porta serve a interface web, qualquer número de clientes MCP e a persistência de sessões. Portanto, ele oferece apenas transportes HTTP — Streamable HTTP e SSE — e não suporta stdio (não há modo de subprocesso local).

Alternativa: a Agent Skill dirige as mesmas sessões via curl simples — a instância a serve em /skills.md. O servidor MCP é uma camada de interface da plataforma, incorporável em qualquer host compatível com MCP — Claude Code, Cursor, Codex, Open WebUI ou seu próprio cliente.

Opção A — Streamable HTTP (/stream)

O transporte MCP moderno; um único endpoint, sem caminho de mensagem separado. Use para Claude Code, Open WebUI e a maioria dos clientes atuais.

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

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

• Mesma máquina: http://127.0.0.1:18765/stream.
• Open WebUI em Docker, termcp no host: http://host.docker.internal:18765/stream (macOS/Windows), ou o IP LAN do host.
• Ambos em Docker na mesma rede (veja Implantação com Docker): http://termcp:18765/stream.

Opção B — SSE (/sse)

O transporte legado. Configure apenas /sse; o SDK posta JSON-RPC para /message automaticamente.

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

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

Folha de referência

• Streamable HTTP → http://<host>:18765/stream
• SSE → http://<host>:18765/sse (JSON-RPC vai para POST /message)

A página API / MCP / SKILLS da interface web (/api.html) oferece configuração pronta para copiar para ambos os transportes, além dos endereços de docs do Agent e download de skills para esta instância.

Agent Skill (somente curl, sem MCP)

Não quer configurar um cliente MCP? A instância inclui uma Agent Skill instalável que ensina qualquer agente a dirigir o termcp com curl sozinho — incluindo os localizadores termcp:// que os usuários colam da interface 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 a sessão do agente após instalar (as skills são carregadas no início da sessão). O Claude Code não tem comando CLI por skill — adicionar é "colocar o arquivo", remover é rm -rf ~/.claude/skills/termcp (ou claude plugin install/uninstall quando a skill é distribuída como plugin).

Uma vez instalada, uma solicitação tão simples quanto "abra termcp://rock64 e execute uname -a " funciona de ponta a ponta: a skill resolve o localizador via GET /api/resolve?url=..., cria a sessão com esse ssh_config, envia o comando e consulta a saída. A mesma skill é registrada como o recurso MCP <origin>/skills.md, e /api.html mostra o comando de instalação exato para a instância que você está vendo.

Conectando Scripts / Programas (API REST)

Pule o MCP e use a mesma camada de sessão programaticamente: a API REST completa e o canal WebSocket ao 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

I/O de terminal ao vivo roda via WebSocket /api/ui/ws; arquivos suportam URLs HTTP diretas com retomada por Range. Lista completa de endpoints em docs/api.md.

Com autenticação habilitada

Quando o servidor roda com --auth-token / --auth-hash, toda solicitação MCP precisa do token como cabeçalho 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>" }
    }
  }
}

Mantenha o token fora de URLs e de configurações/capturas de tela compartilhadas. curl e scripts usam o mesmo cabeçalho:

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

Referência de Ferramentas

O termcp expõe 31 ferramentas MCP. Parâmetros completos, formatos de retorno e códigos de erro estão em docs/mcp-tools.md.

Área	Ferramentas
Sessões (contêineres de conexão)	session_start, session_list, session_info, session_terminate (fechar; mantém a entrada DEAD legível), session_delete (permanente)
Shells (canais de terminal)	shell_open, shell_list, shell_close, shell_input, shell_key, shell_output, shell_resize, shell_reader_register, shell_reader_unregister
Notificações	shell_notify (acorda o Agente de IA), notify_user (notifica o humano na interface Web)
Perfis SSH	ssh_config (list; create / edit / copy / delete com --mcp-manage-ssh-configs)
Encaminhamento de portas	forward (-L / -R / -D / lista / fechar)
Arquivos (SFTP)	file_read, file_write, file_stat, file_delete, file_rename, file_mkdir, file_urls, file_perm, file_link, file_fs, file_getwd
Histórico e mensagens	message (lista / obter)
Descoberta de hosts	shell_detect

Execute um comando como shell_input + shell_key(key="enter") + shell_output. Ferramentas com falha retornam isError=true com um corpo JSON contendo um error_code estável.

Carregamento adiado de ferramentas

Um cliente MCP busca o esquema JSON de cada ferramenta em tools/list, então servidores com muitas ferramentas pagam por isso no orçamento de contexto. A especificação MCP oferece uma saída: marque ferramentas de baixa frequência com defer_loading, e um cliente carrega o esquema delas sob demanda. As 31 ferramentas do termcp se dividem em um caminho quente de 12 (ciclo de vida da sessão + entrada/saída do shell — sempre listadas) e 19 superfícies amplas e de baixa frequência (as 11 ferramentas SFTP file_*, forward, shell_resize / shell_detect / shell_notify, shell_reader_register / shell_reader_unregister, message, ssh_config).

--mcp-defer-tools ativa o marcador e está desativado por padrão, então:

• Padrão — todas as 31 ferramentas são listadas imediatamente com esquema completo. Isso é o que todo cliente que não implementa carregamento adiado precisa — incluindo qualquer Codex que fale com o termcp através de um gateway como AxonHub, que pode descartar o marcador defer_loading. Com o marcador perdido, essas ferramentas não podem ser recarregadas sob demanda e simplesmente desapareceriam da visão do modelo.
• --mcp-defer-tools — as 19 ferramentas de baixa frequência carregam defer_loading; as 12 ferramentas principais permanecem imediatas para que o loop session_start → shell_input → shell_output nunca exija uma viagem de ida e volta de busca. Clientes que suportam carregamento sob demanda (clientes baseados em mcp-go, Claude Code) pagam apenas pelos esquemas que realmente usam.

Mesmas 31 ferramentas de qualquer forma: ativar o sinalizador nunca remove ferramentas, apenas retém esquemas da listagem inicial.

Limitações Conhecidas e Modelo de Segurança

• Ferramentas de arquivo e encaminhamento precisam de uma conexão ativa. Em uma sessão fechada (DEAD), elas retornam session_not_running; a leitura de saída ainda funciona via shell_output, e os encaminhamentos de porta de uma sessão são fechados automaticamente quando ela fica DEAD.
• Autenticação básica precisa de TLS fora do localhost. O desafio de login do navegador usa HTTP Basic, cujas credenciais são apenas codificadas em Base64. Coloque um proxy reverso com terminação TLS na frente do termcp ao expô-lo além de uma rede local confiável; o token estático ainda nunca é registrado em logs ou colocado em uma URL.

🚨 Limite de segurança: o termcp não aplica segurança (é um cano, não um antivírus)

A linha de defesa pertence ao lado de saída da IA e ao seu gateway — não no cano do terminal. O termcp NÃO é um antivírus, EDR ou WAF.

O termcp é um cano transparente de terminal real e sessão multiplexada (transporte PTY) com a mesma liberdade e poder do terminal da própria máquina. Portanto, ele não pode e não deve julgar a intenção do que transporta:

1. Por que um cano de terminal não pode detectar intenção maliciosa.
   • Upload-e-execução não pode ser interrompido aqui. Conteúdo malicioso chega decodificado em Base64 através de um cano, escrito em fragmentos, ou buscado por ferramentas legítimas (curl / wget) em múltiplos estágios e depois chmod'ado e executado. O termcp é um cano de dados, não um scanner de malware: inspecionar cada byte transmitido em busca de um trojan simplesmente não é algo que um transporte de bytes possa fazer.
     • Ofuscação e concatenação são indecidíveis na camada de bytes. Uma IA pode dividir um comando perigoso em fragmentos de string (a="rm -"; b="rf /"; $a$b), reconstruí-lo através de renomeação de variáveis, eval dinâmico, injeção de printf, costura de variáveis de ambiente, ou escrevendo vários arquivos parciais e executando-os. Para o PTY, cada caractere é um pressionamento de tecla legal; o transporte não pode distinguir "payload ofuscado" de "script de desenvolvimento comum".
2. A segurança deve ser aplicada a montante.
   • O chamador (aplicativo host / estrutura do Agente) deve proteger a saída da IA antes da chamada de ferramenta. Envolva shell_input / file_write com proteções de saída, uma camada de política de conformidade de instruções, filtros de conteúdo sensível, ou um modelo de segurança que inspecione o comando gerado antes de chegar ao termcp. O termcp não aplica listas de permissão de comandos, jaulas de caminho, ou níveis de risco baseados em políticas.
     • Mantenha humanos no loop para etapas privilegiadas ou destrutivas. A interface Web mostra cada sessão ao vivo e permite que você assuma o controle ou interrompa a qualquer momento. Trate sudo, comandos destrutivos ou irreversíveis como eventos de aprovação humana — e nunca dê acesso de terminal de alta privilégio sem supervisão a um host de produção que não esteja em sandbox.

---

Histórico de Estrelas

Licença

Lançado sob a Licença MIT. Você é livre para usar, modificar e distribuir, desde que o aviso de direitos autorais e o aviso de permissão sejam mantidos. Agradecemos à comunidade linux.do pelas discussões e apoio.

---