Túneis Cruma

O que Túneis Cruma faz?

Use esta skill quando o usuário quiser publicar algo de sua máquina, gerenciar o que o Cruma já serve, ou instalar ou parar o Cruma. Qualquer coisa compartilhada é pública: pergunte antes de compartilhar e diga exatamente qual porta ou pasta se torna alcançável. Túneis anônimos não precisam de cadastro.

A conta Cruma do usuário

As funcionalidades da conta, incluindo detalhes do plano, túneis e sites da conta, quadro e memória, vêm com o plugin opcional cruma-cloud. Use a skill cloud dele para essas solicitações. Compartilhar uma porta ou pasta e os agentes em execução do usuário permanecem no servidor cruma local.

Com as ferramentas MCP do Cruma

Este plugin inicia cruma mcp através de seu lançador (mcp/cruma-mcp.mjs), um servidor MCP local chamado cruma que executa o binário cruma instalado. Quando suas ferramentas estiverem em sua lista de ferramentas, use-as, não comandos de shell. O servidor inicia sem nada exposto.

Descubra; não adivinhe

Este arquivo é um mapa, não o manual. Para um compartilhamento simples de uma porta ou pasta, use as ferramentas abaixo. Para qualquer outra coisa (autenticação, filtros, domínios, roteamento, processos, regras, uma configuração que você não usou), primeiro leia o que o Cruma diz sobre si mesmo, depois use a ferramenta que ele indicar:

1. O recurso cruma://about (ou describe_cruma): o que o Cruma pode fazer e qual ferramenta o faz. Depois, get_config_model_reference com uma section (middleware_model para controle de acesso e filtros de requisição, backend_kinds, listener_model, recommended_mcp_usage; a referência completa é grande) e get_cruma_glossary para termos. No próprio agente do usuário (veja abaixo), get_runtime_inventory mostra o que já está configurado. Carregue os esquemas das ferramentas que você chamará.
2. Se isso não cobrir, a documentação em Markdown: https://cruma.io/llms.txt, a lista de capítulos https://cruma.io/book/cruma-tunnels.md, e qualquer capítulo em https://cruma.io/book/cruma-tunnels/<chapter>.md. Eles são escritos para a linha de comando (cruma serve, cruma proxy): pegue o que o Cruma pode fazer a partir deles e aplique através das ferramentas MCP.
3. Para um caminho apenas via CLI, cruma --help e cruma <command> --help.

Atalhos como expose_local_port cobrem o caso comum. O que eles não cobrirem é feito com as ferramentas gerais upsert_*; nunca apresente os limites de um atalho como limites do Cruma. Se a referência e a documentação não suportarem o que o usuário pediu, diga isso; não invente uma configuração ou uma ferramenta.

Nunca sirva coisas você mesmo. Não inicie python3 -m http.server, npx serve ou qualquer outro servidor de arquivos, e não execute cruma serve ou cruma proxy: com o MCP conectado, eles iniciam um segundo agente com seu próprio túnel.

De quem é o Cruma

As ferramentas iniciam anexadas a um agente de sessão temporário: um túnel anônimo que suas janelas compartilham e que não contém nada que o usuário salvou. Não é o próprio Cruma do usuário.

Antes do primeiro compartilhamento em uma sessão, chame list_agents uma vez (ela não lê nada de nenhum agente, então não há problema em ser a primeira). Procure por um agente em execução que não seja o agente de sessão e cujo tunnel_account seja registered (o aplicativo desktop ou um agente headless, logado ou com credenciais de túnel). Um agente em execução com tunnel_account anonymous não é um.

• Um desses agentes está em execução: pergunte uma vez, antes de compartilhar qualquer coisa. Nomeie a escolha com seu tipo, perfil, domínio e o que a outra opção significa, por exemplo: "Usar seu Cruma em execução (desktop, perfil work, acme.tun.example.test) ou um túnel anônimo temporário (endereço aleatório, página de aviso do navegador, tempo limitado, desaparece com a sessão)?" Não compartilhe nada, e não chame nenhuma outra ferramenta que leia ou altere um agente, até que eles respondam. Se vários estiverem em execução, liste-os na mesma pergunta.
  • Eles escolherem o próprio: chame use_agent nesse agente (esta é a confirmação que Pergunte antes de use_agent pede) e faça cada compartilhamento da sessão lá. Mencione o limite conhecido quando aplicável: um compartilhamento feito em um agente de um túnel servido por vários agentes é alcançável apenas através daquele agente.
  • Eles escolherem o túnel temporário: permaneça no agente de sessão.
  • Lembre-se da resposta pelo resto da sessão. Não pergunte novamente para compartilhamentos posteriores, e não chame list_agents novamente para eles. Pergunte novamente apenas se o usuário levantar a questão.
• Nenhum desses agentes está em execução (nenhum, ou apenas anônimos como o agente de sessão): sem pergunta. Use o agente de sessão como está e relate as URLs.
• Você não pode perguntar (uma execução não interativa, ou sem como obter uma resposta): use o agente de sessão, e diga na transferência que você o fez, e que um Cruma logado em execução estava disponível quando list_agents mostrou um.
• A pergunta não é necessária quando o usuário já nomeou para onde o compartilhamento vai ("no meu Cruma desktop", "use um túnel temporário"): siga isso.

Os compartilhamentos permanecem pertencentes à sessão e são retirados quando a sessão termina; nunca defina persist para eles.

Quando a solicitação for sobre o deles Cruma (seus app, sites, rotas, domínios, processos ou logs: "por que meu site retorna 502?", "adicione uma senha ao meu site de homologação", "o que está rodando no meu Cruma?"), ou eles quiserem compartilhar através do próprio túnel, um domínio personalizado ou um perfil nomeado, chame list_agents antes de qualquer ferramenta que leia ou altere um agente (describe_cruma, cruma://about, get_config_model_reference e get_cruma_glossary são seguras primeiro). Ler o agente de sessão responde sobre uma configuração que não é deles, então nunca o leia para tal solicitação. Listar ou criar os túneis na conta deles é da conta (veja acima), não de list_agents.

• Pergunte antes de use_agent, nomeando o tipo do agente (desktop, headless), perfil e domínio, e aguarde a resposta. Para um compartilhamento simples, a pergunta acima é essa pergunta; nunca mude sem ela. As ferramentas de compartilhamento então funcionam nesse agente. A mudança retira os compartilhamentos que você fez no anterior.
• Antes da mudança, diga apenas para qual agente você mudaria e pergunte. Não descreva o que cada agente contém (incluindo o do agente de sessão), e não declare ou sugira uma causa, um diagnóstico ou o que está configurado, mesmo quando list_agents mostrar um resumo do processo (uma fase como Failed) ou nomes de site: isso é uma listagem, não um diagnóstico. Nomeie o alvo (tipo, perfil, domínio), pergunte, diga que nada é alterado até que eles respondam, e pare. Diagnostique após a mudança, a partir do agente do usuário.
• use_agent nunca inicia um agente. Se nenhum estiver em execução para o que o usuário quer, diga isso e peça para abrirem o aplicativo desktop, ou executarem cruma --profile <nome> (use o nome que list_agents dá para um perfil parado). Não recorra ao túnel temporário para uma solicitação sobre os próprios sites deles.
• Diga apenas o que uma ferramenta retornou. list_agents lista os agentes que conhece; a partir dela você pode dizer quais agentes estão em execução e seu tipo, perfil e domínio. Não afirme que perfis, sites, configurações ou uma conta existem ou estão faltando a menos que um resultado de ferramenta diga isso (por exemplo, nunca "nenhum perfil salvo apareceu" ou "nada está configurado").
• Nenhum list_agents entre suas ferramentas significa um agente mais antigo: use o túnel temporário para compartilhamentos e diga que um cruma mais recente é necessário para o próprio usuário (Atualizar tem o comando de upgrade).
• Um servidor MCP HTTP do Cruma já no cliente do usuário (por exemplo, cruma-app) é o próprio agente deles. Use suas ferramentas para solicitações sobre o Cruma deles e as deste plugin para compartilhamentos temporários. Se ele falhou ao conectar, diga isso em vez de usar o agente de sessão. list_agents marca o agente que serve HTTP /mcp.

No próprio agente do usuário, depois que eles concordarem com a mudança:

• Um resultado bem-sucedido de use_agent é o estado do agente ao qual você está agora anexado (domínio, frontends, processos, allow_persistent_changes). Trabalhe a partir dele; não chame list_agents novamente apenas para confirmar a mudança.

• Leitura é livre: get_health_summary, get_site_summary, get_proxy_routes, probe_route, get_process_logs, list_recorded_requests.

• Alterações aplicam-se ao agente em execução e desaparecem quando ele reiniciar. Diga isso.

• Alterações permanentes ("configurar um site para sempre") precisam de persist: true, e o agente recusa a menos que o usuário tenha ativado "Permitir que eles salvem alterações" (mcp.local_socket.allow_persistent_changes; página MCP do desktop, "Agentes de Codificação Neste Computador"). Nunca faça silenciosamente uma alteração apenas em memória. Explique a configuração e peça a eles que a ativem, ou para fazer a alteração no app. Uma vez ativada (allow_persistent_changes é true no resultado use_agent, ou em list_agents antes da mudança), não chame uma ferramenta de escrita com persist: true ainda: primeiro descreva a alteração exata (frontend, backend, middleware) como sua resposta e pergunte se deve salvá-la, dizendo claramente que ela seria salva em disco na configuração do agente e permaneceria após uma reinicialização. Passe persist: true apenas depois que o usuário aprovar claramente essa alteração exata: um sim à sua descrição em uma rodada posterior, ou, na mesma mensagem, uma aprovação explícita que nomeie o backend e o frontend por tipo e nome como uma alteração salva ("Eu aprovo exatamente esta alteração salva: ..."). Pedir por um site "permanente" ou "salvo", mesmo com um nome e um caminho, é uma solicitação, não aprovação: descreva a alteração e pergunte. Nunca reenvie uma configuração existente com persist: true para torná-la permanente sem a mesma aprovação. Este é o único uso de persist, e nunca no agente de sessão.

Proteja o que parece privado

Antes de expor algo que parece privado (uma UI de admin, uma ferramenta de banco de dados, documentação interna, uma pasta com credenciais, arquivos .env ou dados pessoais), pergunte se deve proteger, e sugira uma senha. Aguarde a resposta; não exponha primeiro. Se o usuário já pediu proteção, não pergunte novamente.

• Uma senha ou uma lista de permissão de IP: passe access para expose_local_port ou expose_local_directory (o esquema da ferramenta lista os tipos). Uma senha gerada é retornada uma vez. Sem um argumento access no esquema (um agente mais antigo), construa o site com upsert_backend e upsert_frontend e um middleware basic_auth; leia middleware_model para sua forma.
• Login com uma conta ou um provedor (Google, GitHub): access sign_in não está disponível para compartilhamentos ainda. Não tente ou contorne. O login vai através de upsert_frontend com um middleware oauth2 que referencia um provedor que o próprio agente do usuário já possui. Encontre os IDs do provedor nos middlewares oauth2 de frontends existentes (get_runtime_inventory com full: true e sections: ["frontends"]), ou pergunte ao usuário qual provedor usar. Leia middleware_model para a forma do middleware. Se não houver provedor, diga que o login precisa de um configurado primeiro e ofereça uma senha.

O que usar para quê

O usuário quer compartilhar	Faça isso
Arquivos: uma página que você escreveu, uma saída de build, documentação	expose_local_directory com a pasta e um name. Escreva os arquivos primeiro se necessário.
Um servidor de desenvolvimento já em execução	expose_local_port com sua porta e um name.
Um aplicativo que ainda não está em execução	Faça o agente hospedá-lo: upsert_process (o agente aloca PORT; faça o comando escutar nela), depois upsert_frontend em <name>.<assigned_domain> com process_id definido. Os logs vêm através de get_process_logs. Apenas se isso não se encaixar, inicie-o em segundo plano você mesmo e diga isso.
Várias coisas	Uma chamada por compartilhamento. Um agente serve muitos sites e portas ao mesmo tempo, cada um em <name>.<assigned domain>: frontend e API, documentação e app, duas versões lado a lado. Nomeie cada um pelo que é (docs, api, preview-v2).

Se expose_local_directory ou expose_local_port estiver faltando (um agente mais antigo), use upsert_backend (http para uma porta, local-directory para uma pasta) e upsert_frontend em <name>.<assigned_domain>, sem persist. Obtenha assigned_domain de get_runtime_summary; é null por alguns segundos enquanto o túnel conecta, então chame novamente. Não pare em "atualize o cruma".

Depois de expor, chame get_health_summary; status deve ser ok. Use list_shares para relatar cada URL ativa. Uma vez por sessão, também chame get_runtime_summary e leia seu bloco version (veja Versões abaixo).

Transferência

Diga todos estes na mensagem final:

1. Cada URL pública (public_url, ou https://<name>.<assigned_domain>/ no caminho alternativo) e o que cada uma serve, incluindo a porta ou pasta local. Não forneça nenhuma outra URL.
2. Que get_health_summary relatou ok, chamado após a etapa de exposição; caso contrário, o status e os problemas em vez de afirmar sucesso.
3. Qual caminho você usou: expose_local_port, expose_local_directory, upsert_process (o agente hospeda e supervisiona o app, então seus logs estão disponíveis através de get_process_logs), ou upsert_backend/upsert_frontend.
4. Em qual agente você agiu: tipo (desktop, headless ou sessão temporária), perfil e domínio, para que um compartilhamento temporário nunca seja confundido com uma alteração no app do usuário. Quando você usou o agente de sessão porque não pôde perguntar, diga isso.
5. Para o agente de sessão: as URLs terminam com a sessão, um túnel anônimo também termina em seu limite de tempo (item 7), e nada é gravado em disco. Para o próprio agente do usuário: se a alteração é temporária ou salva.
6. Como derrubar um: peça a você, e você chama unexpose com seu nome para um compartilhamento expose_*, ou remove_frontend, remove_backend e remove_process para um upsert_*. Para um compartilhamento de pasta, a edição dos arquivos atualiza o site imediatamente.
7. Para um compartilhamento protegido: o que o protege (senha, redes permitidas ou login), a credencial uma vez se você gerou uma (nome de usuário cruma), e que a proteção termina com o compartilhamento. Um compartilhamento sem proteção é público: diga isso.
8. O aviso de conta, uma vez por sessão, quando o account.state de um resultado de ferramenta for anonymous: o túnel é anônimo e com tempo limitado, com o tempo restante de account.remaining_secs em horas e minutos (ou account.expires_at) quando disponível; para funcionalidades como senhas, nomes personalizados e domínios, veja cruma.io/account. Se o estado for registered, não diga nada.
9. A versão do Cruma do bloco version de get_runtime_summary, da primeira vez que você o obtém na sessão.
10. Depois de verificar a saúde, o número de processos e frontends em execução que você gerenciou.

Resolução de problemas

• Nenhum túnel mostrado: verifique o servidor local (a porta está escutando? localhost:{port} responde?): a ferramenta probe_local lê uma URL local.
• HTTPS relatado como inseguro ou erro de certificado: é o túnel anônimo; o Cruma de produção tem certificados válidos. Veja item 7 acima.
• O site fica cinza após o carregamento: um erro de recurso misto com ativos HTTP carregados de localhost. A ferramenta probe_local pode detectar isso; realce como requested_url termina e sugira uma versão construída.
• Nenhuma ferramenta de exposição encontrada: agente cruma antigo; atualize com o comando e saiba que upsert_backend+upsert_frontend ainda funcionam.
• subtítulo do item 6 com localhost: não; apenas URLs públicas.

Versões

Depois da primeira exposição em cada sessão, leia get_runtime_summary e armazene version como cruma_version. Inclua a versão do Cruma na resposta final (item 9 acima).

Modo observador

Use agent_mode: "observe" quando um use_agent ou qualquer ferramenta de escrita em seus compartilhamentos for chamada. Isso não se aplica a ferramentas que apenas leem, e não é necessário nas leituras de documentação ou nos blocos 1-3 de descoberta antes de você ter um agente.

Por que não apenas comandos de shell

• As ferramentas MCP se fixam a um agente; comandos de shell não.
• As ferramentas MCP usam o binário instalado; cruma no PATH pode ser uma versão diferente.
• As ferramentas retornam dados estruturados; comandos de shell retornam texto.
• As ferramentas não precisam de um terminal ou de lidar com falhas de conexão de saída.