Install and first run

Supported environments

Agent Switchboard runs in the following three environments.

macOS is supported on Apple Silicon only. No files are provided for Intel Macs.

Download the installer from the download page. The download page shows your current operating system first.

Windows

Choosing Setup or Portable

• Setup (Agent-Switchboard-Setup-…exe) is recommended. After installation, you can download and install new versions from inside the app.
• Portable (Agent-Switchboard-Portable-…exe) runs without installation. It does not support automatic installation from inside the app. When a new version is released, you need to download the file again from the download page.

SmartScreen warning

The Windows installers do not have an Authenticode code signature yet. As a result, Windows SmartScreen may warn that it cannot verify the publisher when you download the file in a browser or run it for the first time.

1. Make sure you downloaded the file from the official download page (switchboard.twentyoz.kr).
2. In the warning dialog, click More info, then click Run anyway.

Updates downloaded inside the app after installation are verified separately. They are installed only after the signature of the update policy and the SHA-512 hash of the installer are checked against a public key built into the app. This verification does not replace operating system code signing.

macOS

1. Open the …-mac-arm64.dmg file.
2. Drag Agent Switchboard into the Applications folder.
3. Launch the app from the Applications folder.

macOS release files are published after Developer ID signing and Apple notarization. They must also pass Gatekeeper verification before release. Files downloaded from the official download page therefore open like any other app.

Linux

AppImage

The AppImage needs no installation; just make it executable.

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 stored encrypted in the operating system's secure storage. On Linux, a desktop keyring such as Secret Service is required. If no keyring is available, keys are not stored in plain text; instead, the reason they cannot be saved is shown above 저장 후 적용 (Save and apply) for the API key connection. Turn on a keyring, then restart the app. Phone connection also requires secure storage before it can be turned on.

First run

When you open the app for the first time, you see the rail on the left and the work area. Get started in the following order.

1. Register a project folder: Click the 폴더 추가 (Add folder) icon at the bottom of the left rail and choose the folder you want to work in. Once you choose a folder, that folder's project home opens.
2. Add a connection: Open 환경 설정 (Settings) at the bottom of the sidebar (shortcut Ctrl+, on Windows and Linux, ⌘, on macOS), and add an API key or gateway under 연결 · 인증 (Connections · Authentication). If you only use subscription login (OAuth), you can skip this step.
3. Apply to a tool: In 도구 설정 (Tool settings) on the project home, choose a tool and set its connection and model. For details, see Connections and per-project settings.
4. Launch: Launch a tool directly from the header of the project home, or choose a tool from the project menu in the rail, ⋯ → 새 세션 (New session). By default, tools run in a terminal tab inside the app.

The app's 도움말 (Help) → 처음 연결하기 (First-time setup) walks you through the same steps.

Agent Switchboard does not replace coding agent CLIs such as Codex or Claude Code. The app detects whether each tool is installed and points you to the official installation method for tools that are not installed.

Automatic updates

When updates are checked

• About 2.5 seconds after the app starts.
• Every 15 minutes while the app is running.
• 5 seconds after the computer wakes from sleep.
• At any time, using the download icon at the top.

Updates are downloaded from the official server (https://switchboard.twentyoz.kr/releases). No account or access token is required.

When a new version is available

1. Choose 업데이트 다운로드 (Download update), 이번 버전 건너뛰기 (Skip this version), or 나중에 (Later).
2. The download runs in the background and shows progress, size, and speed. You can cancel it at any time.
3. The update is not installed automatically when the download finishes. The app quits and installs only after you click 재시작하여 설치 (Restart to install) and confirm once more.

If you choose Later, you will not be notified again for 4 hours during the current session. Checking manually shows the postponed update and skipped versions again. In the update window, you can read the changelog up to the skipped version.

Behavior by operating system

If installation fails, the reason is shown in the update window and the restart confirmation dialog. For solutions, see Troubleshooting.