Authentication & SSH Agent

Secure connection authentication is the core of PhanTerm. We employ a dual-track credential storage mechanism and native Agent integration to ensure your secrets are always safe.

Secure Credential Storage

Whether it’s the main connection password, jump host password, or the passphrase protecting your SSH private key, PhanTerm prioritizes storing them in your operating system’s System Keyring.

Caution

Your Secrets Always Stay Local Your passwords and credentials are never uploaded to the cloud. When system-level key management is unavailable (e.g., on some headless Linux servers), PhanTerm securely falls back to using a local, highly randomized key for AES-256-GCM encrypted storage. The cipher text is saved locally in connections.yaml.

SSH Key Authentication

When creating or editing a connection, you can set the Auth Type to Key and specify the path to your private key file (e.g., ~/.ssh/id_ed25519). PhanTerm securely reads the key for authentication and can automatically prompt you to decrypt password-protected private keys.

SSH Agent Integration

PhanTerm perfectly supports SSH Agent, meaning you can avoid repeatedly entering your private key password.

1. System Agent Bridging

If you are already running an SSH Agent on your operating system:

• Windows: PhanTerm automatically detects and bridges to the OpenSSH Agent (\\.\pipe\openssh-ssh-agent).
• macOS / Linux: It automatically detects and bridges to SSH_AUTH_SOCK.

2. Built-in Agent & Agent Forwarding

Even if you don’t use a system-level agent, PhanTerm runs its own Agent service in memory. By enabling Forward Agent in your connection settings, PhanTerm securely forwards your credential authorization to the remote server via the RFC 4254 protocol. This allows you to clone Git repositories directly or jump to other machines from the remote server without copying your private key files there.

Authentication Priority Order: If multiple authentication methods are enabled, PhanTerm attempts to log in in the following order:

1. Keys provided by the System Agent
2. Keys provided by PhanTerm’s built-in Agent
3. The specified private key file
4. Username and password