Support

Find answers to common questions about AgentShell.

Frequently Asked Questions

How do I add a new SSH connection?

Go to the Connections tab, tap the + button, and enter your server details including hostname, port, username, and authentication method (password or SSH key).

How do I generate an SSH key?

Navigate to Settings -> SSH Keys -> Generate New Key. Choose your key type (Ed25519 is recommended), give it a name, and optionally protect it with a passphrase. The public key can then be copied and added to your server's authorized_keys file.

How do I import an existing SSH key?

Go to Settings -> SSH Keys -> Import Key. You can paste your private key directly or import from a file. The key will be securely stored in your device's Keychain.

What AI coding assistants are supported?

AgentShell automatically detects Claude Code CLI, Gemini CLI, and Cursor. The app monitors terminal output patterns to identify when these AI agents are running, working, or waiting for input.

How do Live Activities work?

When you have an active SSH session and switch away from the app, a Live Activity appears on your Lock Screen and Dynamic Island showing the session status. You'll see when your AI agent is working, needs confirmation, or is waiting for input. Tap the Live Activity to return to your session.

Can I run multiple SSH sessions at once?

Yes! AgentShell supports up to 10 concurrent SSH sessions. Switch between them using the Sessions tab, which shows thumbnails of each active terminal.

Is my data synced to the cloud?

No. All your data (connection profiles, SSH keys, passwords) is stored locally on your device only. Nothing is synced to iCloud or any external servers. See our Privacy Policy for details.

How do I use voice input?

When connected to a server, tap the microphone button in the terminal toolbar. Speak your response and it will be converted to text and sent to the terminal. This is especially useful for responding to AI agent prompts.

Why won't my connection work?

Common connection issues and solutions:

  • Connection refused: Verify the hostname and port are correct, and that SSH is running on the server
  • Authentication failed: Double-check your username, password, or SSH key
  • Host key verification: If prompted, verify the server's fingerprint matches your expected value
  • Timeout: Check your network connection and ensure the server is reachable

What key types are supported?

AgentShell supports Ed25519 (recommended), RSA (2048, 3072, or 4096 bit), and ECDSA (P-256) keys. Ed25519 keys are the most secure and efficient option for modern systems.

How do I get notified when my AI agent needs input?

Enable notifications in Settings. When an AI agent running in your terminal session needs input or confirmation, you'll receive a notification. Make sure to also enable Live Activities for real-time status on your Lock Screen.

Can I customize the terminal appearance?

Yes! Go to Settings -> Terminal to customize font size and other display options. The terminal uses a dark theme optimized for readability.

Troubleshooting

App crashes on launch

Try force-quitting the app and relaunching. If the issue persists, ensure you have the latest version from the App Store. As a last resort, uninstall and reinstall the app (note: this will remove saved connections and keys).

Terminal text appears garbled

This can happen if the server sends unexpected character encodings. Try disconnecting and reconnecting. Ensure your server's locale settings match what your terminal expects (UTF-8 is recommended).

Session disconnects frequently

Check your network connection stability. Consider adjusting your server's SSH keep-alive settings. Note that when the app is in the background for extended periods, iOS may terminate connections to save battery.