Installation

APX Terminal is distributed as a portable binary or installer depending on your OS.

macOS (Apple Silicon & Intel)

Download the .dmg file.

Universal Binary included.

Windows 10/11

Download the .exe installer.

Standard NSIS Installer.

Linux

Use .AppImage or .deb.

Ubuntu/Debian/Arch supported.

First Launch & Gatekeeper (macOS)

⚠️ Important for macOS Users: Since APX is a notarized independent app (not on the App Store), you must perform a one-time approval.

Follow these exact steps if the app does not open immediately:

  1. Wait for verification: After double-clicking, the icon may "bounce" in the dock for 10-30 seconds. This is normal.
  2. Handle the warning: A system popup ("Malicious Software" or "Unidentified Developer") will appear. Click Done or Close.
  3. Authorize via Settings: Go to System Settings > Privacy & Security.
  4. Open Anyway: Scroll down to the security section, find the note about APX Terminal, and click Open Anyway.
  5. Final Step: When the app launches, if prompted to access your Documents folder, click Allow (required for saving logs/keys).

AI Agent Setup (BYOK)

APX uses a "Bring Your Own Key" model. We do not markup AI costs. You connect directly to AI Provider.

Step 1: Get API Key

Obtain your API Key from your preferred provider (OpenAI, Google Gemini, Groq, DeepSeek, etc).

Step 2: Configure APX via Command Palette

Access the configuration menu quickly using the keyboard shortcut:

  1. Press Cmd + K (macOS) or Ctrl + K (Windows/Linux).
  2. Type "Settings" in the search bar.
  3. Select Open Settings.
  4. Navigate to the AI Configuration tab and paste your API Key.

Note: Your key is stored in your OS's secure keychain (AES-256). It never touches our servers.

Migrating Hosts

Currently, host migration from other clients (PuTTY/Termius) must be done manually. Automated import tools are on the roadmap for v1.2.

Manual Entry

You can add hosts individually via the "Add Host" button in the sidebar.

  • Host Label (Friendly Name)
  • IP Address / Hostname
  • Username
  • SSH Key (Select from file manager) or Password (not recommended)

SSH Keys Management

APX enforces strict security permissions for key files, similar to the native SSH command.

Key Storage Location

Keys are stored in the local vault:

  • macOS: ~/Library/Application Support/apx-terminal/keys/
  • Windows: %AppData%\apx-terminal\keys/

⚠️ Permission Error (0600)

If you see "UNPROTECTED PRIVATE KEY FILE", run this command in your terminal:

chmod 600 /path/to/your/private_key

Themes & Fonts

APX is designed with a "Cyber-Industrial" aesthetic, but legibility is paramount.

Font Support

We support all Nerd Fonts and Powerline fonts. Default is JetBrains Mono.

To change: Go to Settings > Appearance > Font Family.

Color Schemas

Pre-installed themes include:

  • APX Dark (Default)
  • Dracula
  • One Dark Pro
  • Gruvbox Material

Shortcuts

Action

Keybinding

Command Palette (Settings)

Cmd/Ctrl + K

Troubleshooting

Error: "Blank Screen" on Windows

Usually caused by path conflicts during installation.

Fix: Uninstall, delete the folder %AppData%/apx-terminal, and reinstall the latest version.

SSH Key Permission Denied

APX enforces strict permission checks like standard SSH.

Fix: Ensure your private key is chmod 600. If utilizing the built-in key manager, re-import the key.