porterminal v1.0.6

컴퓨터를 에이전트에게 넘기고, 완전한 제어권을 주고, 지켜보세요.
명령어 하나, URL 하나. (내 폰을 위한 멋진 터미널이기도 합니다.)

1. uvx ptn
2. URL을 AI 에이전트에게 넘기거나, 직접 QR을 스캔하세요
3. 어떤 브라우저에서든 작업을 지켜보고, 언제든 직접 제어하세요

[!WARNING] 해당 전체 URL은 이 컴퓨터에 대한 완전한 접근 권한입니다. 여기에는 실행할 때마다 생성되는 무작위 접근 코드가 포함되어 있으며, 이 URL을 전달받은 사람(또는 AI 에이전트)은 누구든 여러분의 머신에서 실제 셸을 얻습니다. URL과 QR 코드를 비밀처럼 취급하고, 신뢰하는 사람과 에이전트에게만 공유하세요. Porterminal을 중요한 대상에 사용하기 전에 보안 섹션을 읽어보세요.

왜 만들었나

컴퓨터에 원격 접속할 수 있는, 위험할 정도로 쉬운 무언가가 필요했습니다.

ngrok는 회원가입이 필요하고 무료 티어는 형편없습니다. Cloudflare Tunnel은 훌륭한 파이프라인이지만, 그 자체로는 터널만 제공할 뿐 모바일 친화적인 터미널은 아닙니다. Tailscale은 양쪽 끝을 모두 소유하고 있을 때 훌륭하지만, 여전히 기기를 사설 네트워크에 연결해야 합니다. Termius는 포트 포워딩, 방화벽 규칙, 키 관리 등 복잡한 설정이 필요합니다...

그래서 더 간단한 것을 만들었습니다: 명령어 실행, QR 스캔, 타이핑 시작.

그때 깨달았습니다: 같은 방법(명령어 하나, URL 하나)이 어떤 컴퓨터든 AI 에이전트에게 실제 터미널을 제공하는 가장 쉬운 방법이라는 것을. 작성할 MCP 서버도, SSH 키도, Docker도, 설정도 필요 없습니다. uvx ptn을 실행하고 URL을 넘기면, 에이전트가 그 머신에서 명령어를 실행하고, 화면을 읽고, 프롬프트에 응답합니다. 웹 터미널이기 때문에 같은 세션을 어떤 브라우저에서든 열어 실시간으로 작업을 지켜보거나, 키보드를 잡고 직접 제어할 수도 있습니다.

기능

• 컴퓨터를 에이전트에게 넘기고, 완전한 제어권을 주고, 지켜보세요 - AI 에이전트에게 URL을 주면 MCP 또는 일반 REST를 통해 그 머신에서 실제 터미널을 얻습니다. 같은 세션을 어떤 브라우저에서든 열어 실시간으로 작업을 지켜보고, 원할 때마다 키보드를 잡을 수 있습니다. 키도 Docker도 필요 없습니다. 에이전트는 <url>/llms.txt와 <url>/.well-known/mcp.json에서 사용법을 학습합니다. 에이전트 접근 참조.
• 명령어 하나, 즉시 접근 - uvx ptn을 실행하면 여러분(또는 에이전트)이 이 머신에서 실제 터미널을 얻습니다. SSH도, 포트 포워딩도, 설정 파일도 필요 없습니다. Cloudflare 터널 + QR 코드.
• 모바일에서 실제로 사용 가능 - 관성 스크롤, 핀치 투 줌, 스와이프 제스처, 수정자 키(Ctrl, Alt)를 갖춘 터치 최적화.
• 전체 터미널 앱 지원 - vim, htop, less, tmux 모두 적절한 대체 화면(alt-screen) 버퍼 처리를 통해 정상 작동합니다.
• 지속적인 다중 탭 세션 - 세션은 연결이 끊겨도 유지됩니다. 브라우저를 닫거나, 네트워크를 전환하거나, 다른 기기에서 다시 연결해도 셸과 실행 중인 프로세스는 그대로 있습니다. 여러분과 에이전트가 하나의 세션을 공유할 수 있습니다: 작업을 지켜보거나 직접 제어하세요.
• 크로스 플랫폼 - Windows(PowerShell, CMD, WSL), Linux/macOS(Bash, Zsh, Fish, Nushell 및 $SHELL을 통한 모든 셸). 셸을 자동 감지합니다.
• 기본적으로 추측하기 어려움 - 실행할 때마다 독립적인 128비트 무작위 접근 경로가 추가됩니다. 터널 호스트 이름 자체와 모든 잘못된 경로는 404를 반환합니다. URL은 화면에 숨겨져 있지만 QR에는 완전한 자격 증명이 포함되므로 둘 다 비공개로 유지하세요. c를 눌러 에이전트 지침과 URL을 복사하거나, u를 눌러 URL만 복사하세요.

설치

한 줄 설치 (uv + ptn):

Python 3.12+와 cloudflared가 필요합니다(없으면 자동 설치됨).

사용법

ptn                    # Start in current directory
ptn ~/projects/myapp   # Start in specific folder

실행 중: 터널이 활성화되면 개인정보 보호를 위해 연결 URL이 화면에 숨겨집니다. **c**를 눌러 /mcp, /api/agent/run, /llms.txt를 포함한 에이전트 지침과 URL을 복사하고, **u**를 눌러 URL만 복사하거나, QR을 스캔하여 연결하세요. Ctrl+C로 서버를 중지합니다.

에이전트 접근 (MCP + REST)

같은 URL은 AI 에이전트에서도 작동합니다. MCP를 지원하는 클라이언트는 네이티브 타입 도구를 위해 <url>/mcp(Streamable HTTP)를 사용할 수 있습니다. MCP 서버를 등록할 수 없는 에이전트는 일반 HTTP 요청으로 **<url>/api/agent/run**의 REST 폴백을 사용할 수 있습니다. 두 경로 모두 지속적인 에이전트 셸을 생성하며, 폰에서 지켜보고 직접 제어할 수 있는 🤖 탭으로 표시됩니다.

에이전트에게 접근 코드가 포함된 완전한 생성 URL을 전달하세요. MCP 클라이언트는 <url>/.well-known/mcp.json(MCP server.json 디스크립터)에서 서버를 자동 발견할 수 있으며, 사용법이 포함된 사람/에이전트가 읽을 수 있는 **<url>/llms.txt**도 있습니다. 기본 페이지에는 브라우저를 구동하는 에이전트를 위한 접근성 표시 힌트도 포함되어 있고, 사람용 UI는 간결하게 유지됩니다. 클라이언트 설정 예시:

{
  "mcpServers": {
    "porterminal": { "url": "https://<your-tunnel>.trycloudflare.com/<access-code>/mcp" }
  }
}

MCP 도구: run_command(깨끗한 출력 + 종료 코드), read_screen, send_keys, send_signal(Ctrl-C / EOF).

REST 폴백:

curl -s -X POST https://<your-tunnel>.trycloudflare.com/<access-code>/api/agent/run \
  -H "content-type: application/json" \
  -d '{"command":"echo hello","timeout":30}'

응답에는 session_id가 포함됩니다. 이를 <url>/api/agent/screen, <url>/api/agent/keys, <url>/api/agent/signal 및 DELETE <url>/api/agent/session과 함께 재사용하세요.

폰에서 Porterminal을 열면 오른쪽 상단의 복사 버튼이 동일한 에이전트용 공유 텍스트를 복사합니다. 브라우저 전용 에이전트도 기본 페이지에서 폴백을 사용할 수 있습니다: DOM에서 읽을 수 있는 터미널 화면 미러와 명확하게 표시된 터미널 입력.

보안: <url>은 무작위 접근 코드를 포함한 완전한 생성 URL을 의미합니다. 터널 호스트 이름 자체는 아무것도 노출하지 않지만, 전체 URL을 가진 사람(또는 에이전트)은 완전한 비관리자 셸 접근 권한을 얻습니다. docs/agent-access.md 참조.

모바일 제스처

수정자 키 (Ctrl, Alt, Shift): 한 번 탭하면 스티키(한 번의 키 입력), 두 번 탭하면 잠금.

컴포즈 모드 (▤ 버튼): 입력하거나 받아쓰기할 수 있는 텍스트 입력 필드를 토글하고, 전체 모바일 편집 기능(자동 수정, 추천, 커서 위치 지정)으로 텍스트를 편집한 다음 터미널로 전송합니다. 긴 명령어나 음성 입력에 유용합니다.

설정

ptn --init을 실행하여 시작용 설정을 생성하세요. package.json, pyproject.toml 또는 Makefile에서 프로젝트 스크립트를 자동으로 발견하여 버튼으로 추가합니다:

ptn -i
# Created: .ptn/ptn.yaml
# Discovered 3 project script(s): build, dev, test

또는 ptn.yaml을 직접 생성하세요:

# Terminal settings
terminal:
  default_shell: nu              # Default shell ID
  shells:                        # Custom shell definitions
    - id: nu
      name: Nushell
      command: nu
      args: []

# Custom buttons (appear in toolbar)
# row: 1 = default row, 2+ = additional rows
buttons:
  - label: "claude"
    send:
      - "claude"
      - 100        # delay in ms
      - "\r"
  - label: "build"
    send: "npm run build\r"
    row: 2         # second button row

# Update checker settings
update:
  notify_on_startup: true   # Show update notification
  check_interval: 86400     # Seconds between checks (default: 24h)

# Security settings
security:
  require_password: true    # Always require password at startup
  password_hash: ""         # Saved password hash (use ptn -sp to set)
  max_auth_attempts: 5      # Max failed attempts before disconnect

설정은 다음 순서로 검색됩니다: $PORTERMINAL_CONFIG_PATH, ./ptn.yaml, ./.ptn/ptn.yaml, ~/.ptn/ptn.yaml.

보안

실행할 때마다 https://<tunnel>.trycloudflare.com/<access-code>/와 같은 새로운 128비트 무작위 경로가 생성됩니다. 모든 브라우저, WebSocket, MCP, REST, 상태 확인 및 정적 라우트는 해당 정확한 접두사를 요구하며, 호스트 이름 자체와 잘못된 경로는 404를 반환합니다. 이로 인해 발견된 터널 호스트 이름을 무차별 대입(brute-force)으로 공격하는 것은 사실상 불가능합니다.

완전한 생성 URL은 여전히 베어러 자격 증명입니다: 이를 얻은 사람은 누구든 셸 접근 권한을 가집니다. 코드가 유출된 경우 Porterminal을 다시 시작하여 코드를 교체하세요. 선택적 비밀번호는 브라우저 WebSocket에 인증을 추가하지만, MCP와 REST는 에이전트가 원링크 워크플로우를 사용할 수 있도록 계속 완전한 URL을 신뢰합니다.

브라우저는 성공한 비밀번호를 해당 완전한 실행 URL 범위의 일반 텍스트 저장소에 기억합니다. 같은 오리진의 새 실행에 비밀번호를 저장하면 이전 Porterminal 비밀번호 항목이 폐기됩니다. 기억된 비밀번호를 지우거나 거부하면 다른 브라우저 저장소는 건드리지 않고 모두 제거됩니다. 결과적으로 같은 오리진에서 동시에 여러 실행이 있으면 다시 프롬프트가 표시될 수 있지만, 이미 인증된 연결은 유지됩니다.

UI에서: 설정(기어 아이콘)을 열고 보안 섹션에서 비밀번호를 설정/변경하고 비밀번호 요구 사항을 토글하세요. 변경 사항은 서버를 다시 시작해야 적용됩니다.

CLI에서:

# One-time password (prompt each session)
ptn -p

# Save password to config (no prompt needed)
ptn -sp
# Password: ****
# Confirm password: ****

# Clear saved password (enter empty password)
ptn -sp
# Password: [press Enter]

# Set or toggle password requirement
ptn -tp          # Toggle on/off

자세한 내용은 docs/security.md를 참조하세요.

문제 해결

연결이 실패하나요? 접근 코드가 포함된 완전한 생성 URL을 사용하세요. Cloudflare 터널 문제는 서버를 다시 시작(Ctrl+C, 그 다음 ptn)하여 새 터널과 접근 경로를 얻는 것으로 해결할 수도 있습니다.

uvx ptn이 여전히 이전 버전을 실행하나요? 기존 uv tool 설치가 우선할 수 있습니다. uv tool upgrade ptn을 실행하거나, uvx --isolated ptn@latest로 설치된 도구를 우회하세요.

셸이 감지되지 않나요? $SHELL 환경 변수를 설정하거나 ptn.yaml에서 셸을 구성하세요.

기여

이 프로젝트는 보안상의 이유로 외부 기여(Pull Request 또는 코드 변경)를 받지 않습니다 (CONTRIBUTING.md 참조). AGPL-3.0 하에서 포크하여 직접 사본을 실행하는 것은 환영합니다.

소스에서 실행:

git clone https://github.com/lyehe/porterminal
cd porterminal
uv sync --frozen
uv run --frozen ptn

라이선스

AGPL-3.0