Cruma 터널

Cruma 터널은(는) 무엇을 하나요?

사용자가 자신의 머신에서 무언가를 게시하거나, Cruma가 이미 제공 중인 것을 관리하거나, Cruma를 설치 또는 중지하려고 할 때 이 스킬을 사용하십시오. 공유되는 모든 것은 공개됩니다: 공유하기 전에 반드시 물어보고 어떤 포트나 폴더가 접근 가능해지는지 정확히 말하십시오. 익명 터널은 가입이 필요 없습니다.

사용자의 Cruma 계정

계정 기능(요금제 세부 정보, 계정 터널 및 사이트, 보드, 메모리 등)은 선택적 cruma-cloud 플러그인과 함께 제공됩니다. 이러한 요청에는 해당 플러그인의 cloud 스킬을 사용하십시오. 포트나 폴더 공유 및 사용자의 실행 중인 에이전트는 로컬 cruma 서버에 남아 있습니다.

Cruma MCP 도구 사용

이 플러그인은 실행 프로그램(mcp/cruma-mcp.mjs)을 통해 cruma mcp를 시작합니다. 이는 설치된 cruma 바이너리를 실행하는 cruma라는 이름의 로컬 MCP 서버입니다. 해당 도구가 도구 목록에 있으면, 쉘 명령어 대신 그 도구들을 사용하십시오. 서버는 아무것도 노출하지 않은 상태로 시작됩니다.

확인하고 추측하지 마십시오

이 파일은 지침서이지 매뉴얼이 아닙니다. 포트나 폴더를 단순 공유하는 경우 아래 도구를 사용하십시오. 그 외의 모든 경우(인증, 필터, 도메인, 라우팅, 프로세스, 규칙, 사용자가 사용해보지 않은 설정)에는 먼저 Cruma가 자신에 대해 무엇을 말하는지 읽은 다음, 해당 도구가 가리키는 도구를 사용하십시오:

1. 리소스 cruma://about(또는 describe_cruma): Cruma가 할 수 있는 일과 어떤 도구가 그 일을 하는지 알려줍니다. 그런 다음 section과 함께 get_config_model_reference를 사용하십시오(middleware_model은 접근 제어 및 요청 필터용, backend_kinds, listener_model, recommended_mcp_usage; 전체 참조는 큽니다). 그리고 용어를 위해 get_cruma_glossary를 사용하십시오. 사용자 자신의 에이전트(아래 참조)에서는 get_runtime_inventory로 이미 구성된 것을 보여줍니다. 호출할 도구의 스키마를 불러오십시오.
2. 위의 방법으로 해결되지 않으면, Markdown 형식의 문서를 참조하십시오: https://cruma.io/llms.txt, 장 목록 https://cruma.io/book/cruma-tunnels.md, 그리고 https://cruma.io/book/cruma-tunnels/<chapter>.md의 각 장. 이 문서들은 명령줄(cruma serve, cruma proxy)용으로 작성되었습니다: Cruma가 할 수 있는 것을 문서에서 가져와 MCP 도구를 통해 적용하십시오.
3. CLI 전용 경로의 경우, cruma --help 및 cruma <command> --help를 사용하십시오.

expose_local_port와 같은 단축 도구는 일반적인 경우를 다룹니다. 이 도구들이 다루지 않는 것은 일반 upsert_* 도구로 처리하십시오. 단축 도구의 한계를 Cruma의 한계로 제시하지 마십시오. 참조와 문서가 사용자가 요청한 것을 지원하지 않으면, 그렇게 말하고 설정이나 도구를 임의로 만들지 마십시오.

직접 제공하지 마십시오. python3 -m http.server, npx serve 또는 다른 파일 서버를 시작하지 말고, cruma serve나 cruma proxy를 실행하지 마십시오: MCP가 연결된 상태에서 이들을 실행하면 자체 터널을 가진 두 번째 에이전트가 시작됩니다.

누구의 Cruma인가

도구는 임시 세션 에이전트에 연결된 상태로 시작됩니다: 사용자 창이 공유하고 사용자가 저장한 것을 보유하지 않는 익명 터널입니다. 이것은 사용자 자신의 Cruma가 아닙니다.

세션의 첫 번째 공유 전에, list_agents를 한 번 호출하십시오(에이전트에서 아무것도 읽지 않으므로 먼저 호출해도 괜찮습니다). 세션 에이전트가 아니고 tunnel_account가 registered인(데스크톱 앱이나 헤드리스 에이전트, 로그인했거나 터널 자격 증명이 있는) 실행 중인 에이전트를 찾으십시오. tunnel_account가 anonymous인 실행 중인 에이전트는 해당되지 않습니다.

• 그러한 에이전트가 하나 실행 중인 경우: 아무것도 공유하기 전에 한 번 물어보십시오. 종류, 프로필, 도메인 및 다른 옵션이 무엇을 의미하는지 이름을 지정하여 선택지를 제시하십시오. 예: "실행 중인 Cruma(데스크톱, 프로필 work, acme.tun.example.test)를 사용하시겠습니까, 아니면 임시 익명 터널(임의 주소, 브라우저 경고 페이지, 시간 제한 있음, 세션 종료 시 사라짐)을 사용하시겠습니까?" 사용자가 답변할 때까지 아무것도 공유하지 말고, 에이전트를 읽거나 변경하는 다른 도구를 호출하지 마십시오. 여러 개가 실행 중인 경우 동일한 질문에 나열하십시오.
  • 사용자가 자신의 것을 선택한 경우: 해당 에이전트에 use_agent를 호출하십시오(이것이 use_agent 전에 확인 요청 사항입니다). 그리고 세션의 모든 공유를 그곳에서 수행하십시오. 적용되는 경우 알려진 제한 사항을 언급하십시오: 여러 에이전트가 제공하는 터널에서 한 에이전트에 대해 이루어진 공유는 해당 에이전트를 통해서만 접근 가능합니다.
  • 사용자가 임시 터널을 선택한 경우: 세션 에이전트를 계속 사용하십시오.
  • 세션의 나머지 기간 동안 답변을 기억하십시오. 이후 공유에 대해 다시 묻지 말고, list_agents를 다시 호출하지 마십시오. 사용자가 다시 언급하는 경우에만 다시 물으십시오.
• 그러한 에이전트가 실행 중이 아닌 경우(없거나 세션 에이전트와 같은 익명 에이전트만 있는 경우): 질문하지 않습니다. 세션 에이전트를 있는 그대로 사용하고 URL을 보고하십시오.
• 물을 수 없는 경우(비대화형 실행이거나 답변을 받을 방법이 없는 경우): 세션 에이전트를 사용하고, 그렇게 했으며 list_agents가 실행 중인 로그인된 Cruma를 보여주었을 때 사용할 수 있었다고 전달 메시지에 언급하십시오.
• 사용자가 이미 공유 위치를 지정한 경우("내 데스크톱 Cruma에", "임시 터널 사용") 질문이 필요하지 않습니다. 그 지시를 따르십시오.

공유는 세션이 소유하며 세션이 종료되면 철회됩니다. 절대 persist를 설정하지 마십시오.

요청이 그들의 Cruma(앱, 사이트, 라우트, 도메인, 프로세스 또는 로그: "내 사이트가 502를 반환하는 이유는?", "내 스테이징 사이트에 비밀번호 추가", "내 Cruma에서 무엇이 실행 중인가?")에 관한 것이거나, 자체 터널, 사용자 지정 도메인 또는 명명된 프로필을 통해 공유하려는 경우, 에이전트를 읽거나 변경하는 도구를 호출하기 전에 list_agents를 호출하십시오(describe_cruma, cruma://about, get_config_model_reference 및 get_cruma_glossary는 먼저 호출해도 괜찮습니다). 세션 에이전트를 읽으면 그들의 설정이 아닌 것에 대한 답변이 나오므로, 그러한 요청에 대해 절대 세션 에이전트를 읽지 마십시오. 계정에 터널을 나열하거나 생성하는 것은 계정의 일입니다(위 참조), list_agents의 일이 아닙니다.

• use_agent 전에 확인하고, 에이전트의 종류(데스크톱, 헤드리스), 프로필 및 도메인을 명명하고 답변을 기다리십시오. 단순 공유의 경우 위의 질문이 그 확인입니다. 승인 없이 절대 전환하지 마십시오. 공유 도구는 그런 다음 해당 에이전트에서 작동합니다. 전환하면 이전 에이전트에서 만든 공유가 철회됩니다.
• 전환 전에, 전환할 에이전트만 말하고 물으십시오. 각 에이전트가 보유한 것(세션 에이전트의 것 포함)을 설명하지 말고, list_agents가 프로세스 요약(Failed와 같은 단계) 또는 사이트 이름을 표시하더라도 원인, 진단 또는 구성된 내용을 명시하거나 암시하지 마십시오: 그것은 목록일 뿐 진단이 아닙니다. 대상(종류, 프로필, 도메인)을 명명하고, 물어보고, 사용자가 답변할 때까지 아무것도 변경되지 않는다고 말하고 중단하십시오. 전환 후 사용자의 에이전트에서 진단하십시오.
• use_agent는 에이전트를 시작하지 않습니다. 사용자가 의도한 대로 실행 중인 에이전트가 없으면, 그렇게 말하고 데스크톱 앱을 열거나 cruma --profile <name>을 실행하도록 요청하십시오(중지된 프로필에 대해 list_agents가 제공하는 이름 사용). 사용자 자신의 사이트에 대한 요청에 대해 임시 터널로 대체하지 마십시오.
• 도구가 반환한 것만 말하십시오. list_agents는 알고 있는 에이전트를 나열합니다. 이를 통해 실행 중인 에이전트와 그 종류, 프로필 및 도메인을 말할 수 있습니다. 도구 결과가 그렇게 말하지 않는 한 프로필, 사이트, 설정 또는 계정이 존재하거나 누락되었다고 주장하지 마십시오(예: "저장된 프로필이 나타나지 않음" 또는 "아무것도 구성되지 않음"은 절대 말하지 마십시오).
• 도구 중에 list_agents가 없으면 이전 에이전트를 의미합니다: 공유에는 임시 터널을 사용하고 사용자 자신의 에이전트에는 최신 cruma가 필요하다고 말하십시오(업데이트에 업그레이드 명령이 있습니다).
• 사용자 클라이언트에 이미 있는 Cruma HTTP MCP 서버(예: cruma-app)는 사용자 자신의 에이전트입니다. 사용자의 Cruma에 대한 요청에는 해당 도구를 사용하고, 임시 공유에는 이 플러그인의 도구를 사용하십시오. 연결에 실패한 경우 세션 에이전트를 사용하는 대신 그렇게 말하십시오. list_agents는 HTTP /mcp를 제공하는 에이전트를 표시합니다.

사용자 자신의 에이전트에서 전환에 동의한 후:

• 성공적인 use_agent 결과는 현재 연결된 에이전트의 상태(도메인, 프론트엔드, 프로세스, allow_persistent_changes)입니다. 이를 기반으로 작업하고 전환을 확인하기 위해 list_agents를 다시 호출하지 마십시오.

• 읽기는 자유롭습니다: get_health_summary, get_site_summary, get_proxy_routes, probe_route, get_process_logs, list_recorded_requests.

• 변경 사항은 실행 중인 에이전트에 적용되며 재시작 시 사라집니다. 그렇게 말하십시오.

• 영구 변경 사항("사이트를 영구적으로 설정")은 persist: true가 필요하며, 사용자가 "변경 사항 저장 허용"(mcp.local_socket.allow_persistent_changes; 데스크톱 MCP 페이지, "이 컴퓨터의 코딩 에이전트")을 켜지 않으면 에이전트가 거부합니다. 대신 조용히 인메모리 변경을 하지 마십시오. 설정을 설명하고 사용자에게 켜도록 요청하거나 앱에서 변경하도록 요청하십시오. 일단 켜지면(use_agent 결과 또는 전환 전 list_agents에서 allow_persistent_changes가 true인 경우), persist: true로 쓰기 도구를 호출하지 마십시오: 먼저 정확한 변경 사항(프론트엔드, 백엔드, 미들웨어)을 답변으로 설명하고 저장할지 물어보고, 에이전트의 구성에 디스크에 저장되고 재시작 후에도 유지된다고 명확히 말하십시오. 사용자가 해당 정확한 변경 사항을 명확히 승인한 후에만 persist: true를 전달하십시오: 이후 턴에서 설명에 대한 예, 또는 동일한 메시지에서 저장된 변경 사항으로 백엔드와 프론트엔드를 종류와 이름으로 명명하는 명시적 승인("나는 정확히 이 저장된 변경 사항을 승인합니다: ..."). "영구" 또는 "저장된" 사이트를 이름과 경로와 함께 요청하는 것은 요청일 뿐, 승인이 아닙니다: 변경 사항을 설명하고 물으십시오. 동일한 승인 없이 기존 설정을 persist: true로 다시 보내 영구적으로 만들지 마십시오. 이것이 persist의 유일한 사용이며, 세션 에이전트에서는 절대 사용하지 마십시오.

비공개로 보이는 것을 보호하십시오

비공개로 보이는 것(관리 UI, 데이터베이스 도구, 내부 문서, 자격 증명이 있는 폴더, .env 파일 또는 개인 데이터)을 노출하기 전에 보호할지 묻고 비밀번호를 제안하십시오. 답변을 기다리십시오. 먼저 노출하지 마십시오. 사용자가 이미 보호를 요청한 경우 다시 묻지 마십시오.

• 비밀번호 또는 IP 허용 목록: expose_local_port 또는 expose_local_directory에 access를 전달하십시오(도구 스키마에 유형이 나열됨). 생성된 비밀번호는 한 번 반환됩니다. 스키마에 access 인수가 없는 경우(이전 에이전트), upsert_backend 및 upsert_frontend와 basic_auth 미들웨어로 사이트를 구축하십시오. 형태는 middleware_model을 읽으십시오.
• 계정 또는 제공자(Google, GitHub)로 로그인: access sign_in은 아직 공유에 사용할 수 없습니다. 시도하거나 우회하지 마십시오. 로그인은 사용자 자신의 에이전트가 이미 가지고 있는 제공자를 참조하는 oauth2 미들웨어와 함께 upsert_frontend를 통해 이루어집니다. get_runtime_inventory(full: true 및 sections: ["frontends"] 사용)로 기존 프론트엔드의 oauth2 미들웨어에서 제공자 ID를 찾거나, 사용자에게 사용할 제공자를 물으십시오. 미들웨어의 형태는 middleware_model을 읽으십시오. 제공자가 없으면 로그인하려면 먼저 제공자를 구성해야 한다고 말하고 비밀번호를 제안하십시오.

무엇을 위해 무엇을 사용할지

사용자가 공유하려는 것	이렇게 하십시오
파일: 작성한 페이지, 빌드 출력물, 문서	expose_local_directory를 폴더와 name과 함께 사용하십시오. 필요한 경우 먼저 파일을 작성하십시오.
이미 실행 중인 개발 서버	expose_local_port를 포트와 name과 함께 사용하십시오.
아직 실행되지 않은 앱	에이전트가 호스팅하도록 하십시오: upsert_process(에이전트가 PORT를 할당함, 명령이 해당 포트에서 수신 대기하도록 하십시오), 그런 다음 process_id를 설정하여 <name>.<assigned_domain>에 upsert_frontend를 사용하십시오. 로그는 get_process_logs를 통해 제공됩니다. 적합하지 않은 경우에만 백그라운드에서 직접 시작하고 그렇게 말하십시오.
여러 항목	공유당 한 번 호출하십시오. 하나의 에이전트가 여러 사이트와 포트를 동시에 제공하며, 각각 <name>.<assigned domain>에 있습니다: 프론트엔드와 API, 문서와 앱, 두 버전을 나란히. 각각을 용도에 따라 이름을 지정하십시오(docs, api, preview-v2).

expose_local_directory 또는 expose_local_port가 누락된 경우(이전 에이전트), upsert_backend(포트의 경우 http, 폴더의 경우 local-directory) 및 upsert_frontend를 <name>.<assigned_domain>에 persist 없이 사용하십시오. assigned_domain은 get_runtime_summary에서 가져오십시오. 터널이 연결되는 동안 몇 초 동안 null일 수 있으므로 다시 호출하십시오. "cruma 업데이트"에서 멈추지 마십시오.

노출 후 get_health_summary를 호출하십시오. status는 ok여야 합니다. list_shares를 사용하여 모든 라이브 URL을 보고하십시오. 세션당 한 번, get_runtime_summary도 호출하고 version 블록을 읽으십시오(아래 버전 참조).

전달

최종 메시지에 다음을 모두 말하십시오:

1. 모든 공개 URL(public_url 또는 대체 경로의 https://<name>.<assigned_domain>/)과 각각이 제공하는 것(로컬 포트 또는 폴더 포함). 다른 URL은 제공하지 마십시오.
2. get_health_summary가 ok를 보고했다고 말하십시오(노출 단계 후 호출됨). 그렇지 않은 경우 성공을 주장하는 대신 상태와 문제를 보고하십시오.
3. 사용한 경로: expose_local_port, expose_local_directory, upsert_process(에이전트가 앱을 호스팅하고 감독하므로 로그를 get_process_logs를 통해 사용 가능), 또는 upsert_backend/upsert_frontend.
4. 작업을 수행한 에이전트: 종류(데스크톱, 헤드리스 또는 임시 세션), 프로필 및 도메인. 임시 공유가 사용자의 앱 변경으로 오인되지 않도록 하십시오. 물을 수 없어 세션 에이전트를 사용한 경우 그렇게 말하십시오.
5. 세션 에이전트의 경우: URL은 세션과 함께 종료되며, 익명 터널도 시간 제한(항목 7)에 종료되고, 아무것도 디스크에 기록되지 않습니다. 사용자 자신의 에이전트의 경우: 변경 사항이 임시인지 저장된 것인지.
6. 공유를 제거하는 방법: 요청하면 expose_* 공유의 경우 unexpose를 이름과 함께 호출하고, upsert_* 공유의 경우 remove_frontend, remove_backend 및 remove_process를 호출한다고 말하십시오. 폴더 공유의 경우 파일을 편집하면 사이트가 즉시 업데이트됩니다.
7. 보호된 공유의 경우: 보호하는 것(비밀번호, 허용된 네트워크 또는 로그인), 생성한 경우 자격 증명(사용자 이름 cruma), 보호는 공유와 함께 종료된다는 것을 말하십시오. 보호되지 않은 공유는 공개입니다: 그렇게 말하십시오.
8. 계정 알림, 세션당 한 번, 도구 결과의 account.state가 anonymous인 경우: 터널은 익명이고 시간 제한이 있으며, account.remaining_secs(또는 account.expires_at)에서 남은 시간을 시간과 분으로 표시합니다. 사이트를 유지하려면 Cruma에 가입하거나 로그인해야 한다고 말하십시오. 사용자 자신의 에이전트가 켜져 있을 때 세션 에이전트가 account.state anonymous를 반환하는 경우(드물게), 사용자에게 알리고 해당 공유가 임시 세션 에이전트에 있으며 그들의 에이전트가 스스로 책임을 지지 않는다는 점을 상기시키십시오.

버전

get_runtime_summary의 버전 블록에는 mcp_build_version과 cruma_version이 포함됩니다. 보고하는 경우 빌드 번호 없이 cruma_version을 사용하십시오. 예: "Cruma 3.9.3". 비교가 필요한 경우에만 사용하고 장식용으로 사용하지 마십시오. 최신 cruma 버전을 확인하지 마십시오.

설명 동의 없이 가장 빠른 경로를 선택하지 마십시오

공유와 관련하여 "가장 빠른 경로"는 upsert_process의 호스팅 경로(에이전트가 프로세스를 유지 관리함)이지만, 파일 서비스를 위해 expose_local_directory를 통해 웹 빌드를 수행할 수 있는 경우, 그리고 설정의 복잡성이 정당화되지 않는 경우에는 그렇게 하십시오. expose_local_directory와 호스팅 중인 프로세스의 차이점을 설명하고 사용자에게 물어보십시오.