설치·첫 실행

지원 환경

Agent Switchboard는 다음 세 환경에서 실행됩니다.

macOS는 Apple Silicon 전용입니다. Intel Mac용 파일은 제공하지 않습니다.

설치 파일은 다운로드 페이지에서 받습니다. 다운로드 페이지는 지금 쓰는 운영체제를 먼저 보여 줍니다.

Windows

Setup과 Portable 고르기

• Setup(Agent-Switchboard-Setup-…exe)을 권장합니다. 설치 후 앱 안에서 새 버전을 받아 설치할 수 있습니다.
• Portable(Agent-Switchboard-Portable-…exe)은 설치 없이 실행합니다. 앱 안 자동 설치는 지원하지 않습니다. 새 버전이 나오면 다운로드 페이지에서 파일을 다시 받아야 합니다.

SmartScreen 경고

Windows 설치 파일에는 아직 Authenticode 코드 서명이 없습니다. 그래서 브라우저로 받거나 처음 실행할 때 Windows SmartScreen이 게시자를 확인할 수 없다고 경고할 수 있습니다.

1. 파일을 공식 다운로드 페이지(switchboard.twentyoz.kr)에서 받았는지 확인합니다.
2. 경고 창에서 추가 정보를 누른 뒤 실행을 누릅니다.

설치한 뒤 앱 안에서 받는 업데이트는 별도로 검증합니다. 앱에 내장된 공개키로 업데이트 정책의 서명과 설치 파일의 SHA-512 해시를 확인한 뒤에만 설치합니다. 이 검증은 운영체제 코드 서명을 대신하지는 않습니다.

macOS

1. …-mac-arm64.dmg 파일을 엽니다.
2. Agent Switchboard를 응용 프로그램 폴더로 끌어 놓습니다.
3. 응용 프로그램 폴더에서 앱을 실행합니다.

macOS 배포 파일은 Developer ID 서명과 Apple 공증(notarization)을 거쳐 게시합니다. 배포 전에 Gatekeeper 검증도 통과해야 합니다. 그래서 공식 다운로드 페이지에서 받은 파일은 일반 앱처럼 열립니다.

Linux

AppImage

AppImage는 설치 없이 실행 권한만 주면 됩니다.

chmod +x Agent-Switchboard-<버전>-linux-x86_64.AppImage
./Agent-Switchboard-<버전>-linux-x86_64.AppImage

.deb (Debian·Ubuntu 계열)

sudo apt install ./Agent-Switchboard-<버전>-linux-amd64.deb

보안 저장소(keyring)

API 키는 운영체제 보안 저장소에 암호화해 보관합니다. Linux에서는 Secret Service 같은 데스크톱 keyring이 필요합니다. keyring을 쓸 수 없으면 키를 평문으로 저장하지 않고, API 키 연결의 저장 후 적용 위에 저장할 수 없는 이유를 표시합니다. keyring을 켠 뒤 앱을 다시 시작하세요. 휴대폰 연결도 보안 저장소가 있어야 켤 수 있습니다.

처음 실행하기

앱을 처음 열면 왼쪽 레일과 작업 화면이 보입니다. 아래 순서로 시작합니다.

1. 프로젝트 폴더 등록: 왼쪽 레일 아래쪽의 폴더 추가 아이콘을 누르고 작업할 폴더를 고릅니다. 폴더를 고르면 그 폴더의 프로젝트 홈이 열립니다.
2. 연결 등록: 사이드바 아래쪽의 환경 설정(단축키 Windows·Linux Ctrl+,, macOS ⌘,)을 열고 연결 · 인증에서 API 키나 게이트웨이를 등록합니다. 구독 로그인(OAuth)만 쓴다면 이 단계는 건너뛰어도 됩니다.
3. 도구에 적용: 프로젝트 홈의 도구 설정에서 도구를 고르고 연결과 모델을 정합니다. 자세한 방법은 연결·프로젝트별 설정을 참고하세요.
4. 실행: 프로젝트 홈 머리줄에서 도구를 바로 실행하거나, 레일의 프로젝트 메뉴 ⋯ → 새 세션에서 도구를 고릅니다. 기본 실행 위치는 앱 안 터미널 탭입니다.

앱 안의 도움말 → 처음 연결하기에서도 같은 순서를 안내합니다.

Agent Switchboard는 Codex, Claude Code 같은 각 코딩 에이전트 CLI를 대신하지 않습니다. 앱이 도구 설치 여부를 감지하고, 설치되지 않은 도구는 공식 설치 경로를 안내합니다.

자동 업데이트

확인 시점

• 앱 시작 약 2.5초 뒤 새 버전을 확인합니다.
• 앱이 켜져 있으면 15분마다 확인합니다.
• 절전에서 돌아오면 5초 뒤 다시 확인합니다.
• 상단의 다운로드 아이콘으로 언제든 직접 확인할 수 있습니다.

업데이트는 공식 서버(https://switchboard.twentyoz.kr/releases)에서 받습니다. 계정이나 액세스 토큰은 필요하지 않습니다.

새 버전이 있을 때

1. 업데이트 다운로드, 이번 버전 건너뛰기, 나중에 중 하나를 고릅니다.
2. 다운로드는 백그라운드에서 진행되고 진행률·용량·속도를 보여 줍니다. 중간에 취소할 수 있습니다.
3. 다운로드가 끝나도 자동으로 설치하지 않습니다. 재시작하여 설치를 누르고 한 번 더 확인해야 앱을 종료하고 설치합니다.

나중에를 고르면 지금 실행 중에는 4시간 동안 다시 알리지 않습니다. 직접 확인하면 이 보류와 건너뛴 버전도 다시 보여 줍니다. 업데이트 창에서 건너뛴 버전까지의 변경 기록을 읽을 수 있습니다.

운영체제별 동작

설치가 실패하면 업데이트 창과 재시작 확인 창에 실패 이유를 보여 줍니다. 해결 방법은 문제 해결을 참고하세요.