Guides
Supported platforms
Agent Switchboard runs on three platforms.
| Operating system | Architecture | Installers |
|---|---|---|
| Windows | x64 | Agent-Switchboard-Setup-<version>-x64.exe, Agent-Switchboard-Portable-<version>-x64.exe |
| macOS | Apple Silicon (arm64) | Agent-Switchboard-<version>-mac-arm64.dmg, ZIP |
| Linux | x64 | Agent-Switchboard-<version>-linux-x86_64.AppImage, Agent-Switchboard-<version>-linux-amd64.deb |
On macOS, only Apple Silicon is supported. There are no builds for Intel Macs.
Get the installer from the download page. It shows the files for your current OS first.
Windows
Setup or Portable?
- Setup (
Agent-Switchboard-Setup-…exe) is the one we recommend. Once it's installed, the app can download and install new versions for you. - Portable (
Agent-Switchboard-Portable-…exe) runs without installing. The trade-off: it can't install updates from inside the app, so you'll need to grab the new file from the download page each time a version comes out.
SmartScreen warning
The Windows installers don't have an Authenticode code signature yet, so Windows SmartScreen may warn that it can't verify the publisher when you download or first run the file.
- Make sure the file came from the official download page (
switchboard.twentyoz.kr). - In the warning, click More info, then Run anyway.
Updates you get inside the app after installing are verified separately. The app checks the update policy's signature and the installer's SHA-512 hash against a public key built into the app, and installs only if both pass. This check doesn't replace OS code signing, though.
macOS
- Open the
…-mac-arm64.dmgfile. - Drag Agent Switchboard into your Applications folder.
- Launch the app from Applications.
The macOS builds are signed with a Developer ID, notarized by Apple, and checked against Gatekeeper before release. If you downloaded from the official page, the app opens like any other.
Linux
AppImage
The AppImage doesn't need installing. Just make it executable and run it.
chmod +x Agent-Switchboard-<version>-linux-x86_64.AppImage
./Agent-Switchboard-<version>-linux-x86_64.AppImage
.deb (Debian and Ubuntu-based)
sudo apt install ./Agent-Switchboard-<version>-linux-amd64.deb
Secure storage (keyring)
API keys are encrypted in your OS's secure storage, so on Linux you need a desktop keyring such as Secret Service. If no keyring is available, the app won't fall back to storing keys in plain text. Instead, it shows why the key can't be saved above the API key connection's 저장 후 적용 (Save and apply) button. Turn on a keyring and restart the app. Phone connection also needs secure storage before you can turn it on.
First run
The first time you open the app, you'll see the rail on the left and the main work area. Here's how to get going.
- Add a project folder: Click the 폴더 추가 (Add folder) icon at the bottom of the left rail and pick the folder you want to work in. The folder's project home opens.
- Add a connection: Open 환경 설정 (Settings) at the bottom of the sidebar (
Ctrl+,on Windows and Linux,⌘,on macOS) and add an API key or gateway under 연결 · 인증 (Connections · Authentication). If you only use subscription login (OAuth), skip this step. - Apply it to a tool: In 도구 설정 (Tool settings) on the project home, pick a tool and choose its connection and model. See Connections and per-project settings for details.
- Launch: Start a tool right from the project home header, or pick one from the project menu in the rail under
⋯ → 새 세션(New session). Tools open in a terminal tab inside the app by default.
You can find the same steps in the app under 도움말 (Help) → 처음 연결하기 (First-time setup).
Agent Switchboard doesn't replace coding agent CLIs like Codex or Claude Code. It checks whether each tool is installed and points you to the official install instructions for any that aren't.
Automatic updates
When the app checks
- About 2.5 seconds after launch
- Every 15 minutes while the app is open
- 5 seconds after your computer wakes from sleep
- Any time you click the download icon at the top
Updates come from the official server (https://switchboard.twentyoz.kr/releases). You don't need an account or access token.
When a new version is available
- Choose 업데이트 다운로드 (Download update), 이번 버전 건너뛰기 (Skip this version), or 나중에 (Later).
- The download runs in the background and shows progress, size, and speed. You can cancel it partway.
- Nothing is installed the moment the download finishes. The app closes and installs only after you click 재시작하여 설치 (Restart to install) and confirm once more.
If you choose Later, you won't be reminded again for 4 hours while the app stays open. A manual check brings back both postponed and skipped versions. The update window lets you read the changelog for everything up to the skipped version.
How it works on each platform
| Package | Installs from inside the app |
|---|---|
| Windows Setup | Yes |
| Windows Portable | No. Download the new file from the download page |
| macOS (signed app) | Yes. The app quits once install verification finishes. If there's an error or a 120-second timeout, you can try again |
| Linux AppImage | Yes. The new version starts after the old one quits |
| Linux .deb | Yes. You'll see an administrator authentication dialog during install |
If an install fails, the update window and the restart confirmation dialog show why. For fixes, see Troubleshooting.