## 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.