Conn 시작하기

Conn을 설치하고 에이전트를 연결해 같은 터미널에서 번갈아 작업하세요. 데스크톱 다운로드에는 에이전트 연결용 CLI가 포함되어 있으므로 Rust·Node.js·개발 서버가 필요하지 않습니다.

1. 설치하고 세션 열기

한 줄로 설치할 수 있습니다.

brew install --cask eggp-dev/tap/conn                                                        # macOS, Apple Silicon
curl -fsSL https://conn.eggp.dev/install.sh | sh     # Linux x86_64

cask는 서명·공증된 DMG를 설치하며 릴리스와 함께 공개된 SHA-256으로 확인합니다. Linux 스크립트는 AppImage를 내려받아 릴리스의 SHA256SUMS와 대조한 뒤 내 계정에만 설치합니다(~/.local/bin, 앱 메뉴 항목, sudo 불필요). 체크섬이 맞지 않으면 설치하지 않습니다. CONN_VERSION=v0.8.3로 버전을 고정할 수 있습니다. AppImage는 FUSE 2가 필요합니다. Ubuntu 24.04 이상에서는 sudo apt install libfuse2t64를 실행하세요. 두 방법 모두 이후에는 앱 안에서 업데이트됩니다. 셸에 넘기기 전에 스크립트를 읽어 보셔도 좋습니다: scripts/install.sh.

직접 파일을 받으려면:

OS와 CPU에 맞는 v0.8.3 프리뷰를 받으세요. 실제 서명 상태와 실행 검증 결과는 릴리스 안내에서 확인할 수 있습니다.

플랫폼	다운로드	설치
Ubuntu x64	`.deb`	아래 명령으로 설치한 뒤 앱 목록에서 Conn을 엽니다.
Ubuntu x64	AppImage	실행 권한을 준 뒤 파일을 엽니다.
macOS Apple Silicon	`.dmg`	DMG를 열고 Conn을 Applications로 옮긴 뒤 그곳에서 실행합니다.
Windows x64	설치 `.exe`	설치 파일을 실행하고 시작 메뉴에서 Conn을 엽니다.

새 릴리스의 Intel Mac 배포는 잠시 중단합니다. 기존 Intel 파일은 이전 릴리스에 유지하며 Intel Mac에 Apple Silicon 파일을 설치하지 마세요.

Ubuntu에서는 다운로드한 폴더에서 실행합니다.

sudo apt install ./conn-v0.8.3-x86_64-unknown-linux-gnu-desktop.deb

AppImage를 선택했다면 다음과 같이 실행합니다.

chmod +x ./conn-v0.8.3-x86_64-unknown-linux-gnu-desktop.AppImage
./conn-v0.8.3-x86_64-unknown-linux-gnu-desktop.AppImage

Linux 빌드 대상은 Ubuntu 24.04·26.04 x64이며 AppImage에도 시스템 라이브러리가 필요합니다. Windows 프리뷰는 의도적으로 무서명 배포하므로 SmartScreen·알 수 없는 배포자 경고가 나올 수 있고 관리되는 PC에서는 설치가 차단될 수 있습니다. Mac 공개 파일은 릴리스의 Developer ID 서명·공증 검사를 통과해야 합니다. 각 대상의 범위는 플랫폼 지원을 참고하세요.

원하면 파일과 함께 SHA256SUMS를 받으세요. Linux는 sha256sum --ignore-missing -c SHA256SUMS, macOS는 shasum -a 256 <파일> 결과와 해당 줄 비교, Windows는 Get-FileHash <파일> -Algorithm SHA256을 사용합니다. 체크섬은 파일 손상을 확인하며 코드 서명과는 별개입니다.

2. 터미널 설정

왼쪽 위 C 아이콘 → 설정을 엽니다.

터미널 프로필에서 로컬 셸, 시작 폴더, 기본 프로필을 고릅니다. **+**로 해당 프로필의 새 탭을 열 수 있으며 기존 탭의 프로필은 유지됩니다.
테마 → 언어에서 English 또는 한국어를 고릅니다. 핸드오프 효과를 끌 수 있으며 아이콘은 OS의 모션 줄이기 설정도 따릅니다.
설정을 닫고 오른쪽 위 제어 상태 표시를 누릅니다. 첫 요청에서는 Autopilot, 제어권 부여 전 확인 켜기, 실행 유예 2초로 설정하세요.

Autopilot은 정책 안에서 에이전트 실행을 허용합니다. Co-pilot에서는 제안된 명령마다 사람이 Enter를 누르며, Observe는 에이전트가 쓰지 않고 읽기만 하게 합니다.

에이전트 연결

설정 → 에이전트 → 에이전트 연결에서 진행합니다.

Codex / ChatGPT 로컬 작업, Claude Code, Cursor, GitHub Copilot(VS Code 또는 CLI)을 고릅니다.
설정하기를 눌러 MCP 서버와 협업 스킬을 등록합니다.
카드의 안내대로 클라이언트를 재시작하거나 다시 연결합니다. Conn을 켜 두고 에이전트에게 현재 터미널을 읽어 달라고 요청하세요.
에이전트가 처음 연결하면 Conn에 참여를 요청합니다 카드가 뜹니다. 허용을 누르면 대기 중이던 에이전트 호출이 그대로 이어집니다. 새 연결마다 한 번 묻습니다. 원하지 않으면 설정 → 에이전트 → 새 에이전트가 참여하기 전에 묻기를 끄세요.

설정 완료는 파일 등록을 뜻하며 실제 접속하면 현재 접속 중으로 표시됩니다. 클라이언트의 신뢰 확인과 명령 승인은 별도로 유지됩니다. 클라이언트별 경로·갱신·해제·문제 해결.

앱에 포함된 CLI의 절대 경로와 현재 연결 주소를 사용합니다. Rust·Cargo·Node.js 설치나 PATH 변경은 필요 없으며 AppImage의 CLI는 유지되는 경로에 복사합니다. 앱을 옮기거나 재설치했다면 설정 갱신을 사용하세요. 기존에 수동으로 등록한 Conn 항목은 덮어쓰지 않고 검토하도록 안내합니다.

다른 클라이언트는 다른 MCP 클라이언트 · 수동 설정을 펼쳐 MCP JSON 또는 Codex TOML을 복사합니다. JSON은 설정 데이터이므로 셸 명령으로 실행하지 않습니다. 이 로컬 연결은 ChatGPT 웹·클라우드 작업용 원격 서버를 제공하지 않습니다.

직접 설정과 연결 주소

CLI를 별도로 설치해 PATH에 등록했다면 Codex CLI에서 다음 명령으로 연결할 수 있습니다.

codex mcp add conn -- conn mcp

기본 주소는 Unix의 ~/.conn/conn.sock, Windows의 로컬 사용자별 Named Pipe입니다. 설정 → 진단에서 현재 주소를 확인하세요. 기본값이 아닌 세션에는 conn --socket <연결주소> mcp 또는 CONN_SOCKET을 사용합니다. 데스크톱에서 복사하는 설정에는 이 값이 자동으로 포함됩니다. 브라우저 테스트 어댑터는 별도 주소를 사용합니다.

3. 제어권 주고받기

에이전트에게 요청하세요.

모든 셸 작업은 Conn으로 해줘. 현재 화면을 읽고 현재 디렉터리를 확인할 제어권을 요청해. 정확한 명령도 포함해 줘. 파일은 변경하지 마. 내가 거절하거나 제어권을 가져오면 멈추고 무슨 일이 있었는지 알려줘.

제어 요청을 검토합니다. 요청 원문 보기에는 인자와 에이전트가 전달한 예정 명령이 표시됩니다.
허용을 선택합니다. 별도의 명령 승인이 뜨면 그것도 검토하세요. 실행 유예 중 Enter는 즉시 실행하고 Esc는 취소합니다.
결과를 함께 읽습니다. Enter가 전달됐다고 성공으로 판단하지 말고 에이전트가 스냅샷을 다시 확인하도록 요청하세요.
직접 명령을 입력해 제어권을 가져와 보세요. 준비가 되면 에이전트에게 바뀐 화면을 읽고 계속하도록 요청합니다.
타임라인에서 명령과 제어권 변경을 확인합니다. 요청을 거절해 실행되지 않는지도 확인할 수 있습니다. 다시 시도할 때는 명시적으로 요청하세요.

제어권을 가져와도 이미 실행 중인 명령을 되돌리거나 멈추지는 않습니다. 에이전트의 추가 입력을 막는 동작입니다. 실행 중인 프로세스를 멈추려면 Ctrl-C 같은 일반적인 터미널 인터럽트를 사용하세요.

열린 C 아이콘은 사람 제어, 대기 중인 요청, 에이전트 제어, 실행 유예를 나타내는 상태 표시이며 승인 버튼은 아닙니다.

4. 타임라인 읽기

전체는 명령과 협업을 합쳐 보여주고 명령, 협업으로 걸러 볼 수 있습니다. 상세에서 이벤트 순서를, 요청 원문 보기에서 기록한 메서드와 인자를 확인하세요. 오래된 기록이나 일부 클라이언트에는 예정 명령이 없을 수 있습니다.

거절, 정책 차단, 취소, 만료, 실행은 서로 다른 결과입니다. 실행됨은 입력이 셸에 도착했다는 뜻이며 명령 성공을 뜻하지 않습니다. 타임라인은 터미널 출력이나 스크롤백을 저장하지 않습니다.

CLI와 MCP

먼저 Conn 데스크톱 앱을 여세요. CLI는 보이는 세션에 에이전트를 연결하며, 터미널 프록시나 headless 협업 셸을 시작하지 않습니다. 모드·승인·속도는 앱에서 설정합니다.

conn --version
conn mcp --agent-id my-client

보통 에이전트 클라이언트가 설정에서 생성한 구성으로 MCP를 실행합니다. 참여자로 선택한 연결을 유지하세요. 같은 이름이라도 별도 CLI 프로세스는 다른 연결 ID를 받습니다. 일반 공유 탭에서 한 번만 읽기 전용 요청을 보낼 때는 다음을 사용할 수 있습니다.

conn agent --agent-id demo run "pwd" --reason "Show the current directory without changing files"

cmd.exe에는 cd를 사용하세요. 사람의 제어권 회수·승인·모드 변경은 앱에서 합니다. conn log -n 30은 OS 권한으로 로컬 감사 파일을 읽는 별도 기능이며 에이전트 화면 조회가 아닙니다. 이 CLI 변경은 v0.7.0부터 적용됩니다. 앱과 MCP 클라이언트를 함께 재시작하세요.

자주 묻는 문제

증상	확인할 것
에이전트가 CLI를 찾지 못함	설정에서 연결 구성을 다시 복사하세요. 데스크톱 연결은 절대 경로를 사용하므로 `PATH` 변경이 필요하지 않습니다.
에이전트가 연결되지 않음	Conn을 열어 두고 현재 주소를 사용하세요. 앱을 옮겼다면 설정을 다시 복사하세요.
`admission_pending`	Conn 창의 “참여를 요청합니다” 카드에서 허용을 누른 뒤 에이전트가 다시 시도하게 하세요.
읽지만 입력하지 못함	Observe 모드, 도구 권한, 제어권 소유자를 확인하세요. 사람이 입력하면 제어권이 돌아오며, 에이전트는 다시 요청해야 합니다.
요청이 계속 대기함	제어 요청, 명령 승인, Co-pilot 제안이 있는지 확인하세요.
보고 있지 않은 탭에서 에이전트가 작업함	정상입니다. 접근은 창 포커스나 보이는 탭이 아니라 공유, 모드, 제어권을 따릅니다. 제한하려면 공유를 중단하거나 Observe 모드를 쓰세요.
`surface_unavailable`	에이전트가 마지막으로 읽은 뒤 화면이 바뀌었습니다. 새 스냅샷을 읽고 다시 시도하세요.
복합 명령이 차단됨	`isolate_dangerous: true`이면 이동, 위험 작업, 검증을 각각 요청하세요.
명령이 아직 실행 중임	기다린 뒤 스냅샷을 다시 읽으세요. 입력 결과는 종료 상태가 아닙니다.

정책은 설정 → 정책 또는 ~/.conn/policy.yaml에 있습니다. 승인으로 정책 차단을 해제할 수는 없습니다. 설정과 기록의 기본 위치는 ~/.conn(Windows는 %USERPROFILE%\.conn)입니다. 요청과 프로필 환경 값에 민감한 내용이 있을 수 있으므로 공유 전에 확인하세요.

소스에서 실행

소스 빌드는 개발이나 직접 수정할 때 사용합니다. rustup으로 Rust와 네이티브 컴파일러·링커를 설치하세요. 데스크톱 빌드에는 Node.js 24와 Tauri 필수 구성 요소도 필요합니다. 저장소에서 Rust 도구 버전을 고정합니다.

git clone https://github.com/eggp-dev/conn.git
cd conn
cargo install --path crates/cli --locked
cd frontends/tauri
npm ci
npm run tauri dev

에이전트를 연결하려면 실행 중인 Conn 프런트엔드가 필요합니다. 같은 네이티브 백엔드를 브라우저에서 검증하려면 브라우저 테스트를 확인하세요.

다음 안내: 백엔드, 정책, 신뢰 범위, 기여.

업데이트 (v0.6.0 이상)

백그라운드에서 새 버전을 확인하고 서명된 업데이트를 다운로드합니다. 준비되면 Conn 메뉴에 설치하고 다시 시작이 표시됩니다. 설치 시점은 사용자가 결정하며, 실행 중인 명령을 포함한 모든 셸 세션이 종료된다는 안내를 확인합니다. 저장된 설정과 타임라인 기록은 유지됩니다.

업데이트 확인 → 업데이트 설정에서 자동 확인·다운로드를 끄거나 프리뷰 포함 여부를 바꿀 수 있습니다. 프리뷰 빌드는 기본적으로 프리뷰를 포함하고, 정식 빌드는 포함하지 않습니다. 채널을 바꿔도 이전 버전으로 내리지 않습니다. GitHub 계정이나 토큰은 필요 없습니다.

Apple Silicon macOS, Windows x64, Linux AppImage에서 앱 내 설치를 지원합니다. .deb는 패키지 관리자 또는 새 설치 파일을 사용하세요. 기존 0.5.x는 0.7.0을 한 번 직접 설치해야 합니다. 확인·다운로드 실패는 실행 중인 셸에 영향을 주지 않으며 다시 시도하거나 릴리스 페이지에서 받을 수 있습니다.

같은 세션에서 공유와 확장 사용 (v0.7.0)

외부 실행 세션은 비공유로 시작합니다. 해당 창의 공유 메뉴에서 연결한 에이전트를 고르면 현재 보이는 화면을 공유합니다. 기존 외부 입력 권한은 종료하고 셸·SSH 연결은 유지합니다. 공유를 끄면 혼자 작업할 수 있습니다. 이전 비공유 입력·출력은 소급 기록하지 않습니다.

설정 → 확장에서 터미널 테마를 고르거나 JSON 파일로 테마를 설치합니다. 확장 안내

연결 승인과 공유 복구 (미배포)

허용 / 거부 연결 카드는 비공개·셸 준비 중 화면과 설정창 안에서도 표시됩니다. 연결을 허용해도 참여자를 선택하고 공유를 시작하기 전까지 터미널은 비공개입니다. 미완성 입력 때문에 공유가 실패하면 터미널에서 입력을 완료하거나 취소한 뒤 다시 시도하세요. 실패한 전환은 외부 입력 권한을 유지합니다. 다른 화면에서 선택이 바뀌었다면 선택 다시 불러오기로 현재 참여자를 확인한 뒤 적용하세요. 검증 범위를 참고하세요.