Getting Started

Most connection failures are authentication errors. Check three things: your username is case-sensitive (use root, not ROOT); use a modern Ed25519 key, since OpenSSH 9+ servers reject older RSA-SHA1 signatures so a valid RSA key can still fail; and make sure the public half of your key is in the server's ~/.ssh/authorized_keys. “Host unreachable” means a wrong IP or port or a down server, and “Permission denied (publickey,password)” means the server disabled password auth and your key isn't trusted yet.

Open the terminal menu (the three-lines icon) and tap Generate SSH key, or tap Generate new key while adding or editing a host. ShellSage creates a modern ed25519 key right on your phone. Copy the public key into the server's ~/.ssh/authorized_keys, or if you're already connected tap Install on <host> to add it in one tap. The private key is held in encrypted secure storage on your phone; when you save the host, it's also uploaded to our servers and stored encrypted at rest (AES-256) so the host appears on every device you sign in on — that's encryption at rest, not end-to-end. No laptop or desktop terminal required.

Your terminal sessions stay private: ShellSage does not record your commands, keystrokes, or scrollback. It does store your saved hosts so they sync across devices — the label, address, port, username, and the sign-in credential (key or password), all kept encrypted and access-controlled. AI help is processed to answer you and isn't kept unless you turn on assistant history, and a file you send to a host is stored privately for 24 hours, then deleted automatically.

After your first sign-in, ShellSage reopens behind Face ID or fingerprint, and you can tap Unlock with biometrics instead of typing your password. Per host, toggle Require biometric on when adding or editing a host, and every tap on that host's card then triggers Face ID, fingerprint, or device passcode before it unlocks and connects. It falls back to the device passcode if biometrics aren't enrolled, and it's recommended on for all production hosts — a small lock badge on the card confirms it's active.

If an AI Fix suggestion matches a destructive pattern (rm -rf /, dd of=/dev/sda, mkfs, a fork bomb, and similar), the Run button is replaced with a red warning and you must type the command character-by-character to confirm before it executes. ShellSage never auto-runs anything destructive — even with “Always run on tap” enabled, a destructive command still stops and asks first — and prod-tagged hosts skip AI Run entirely so you copy and paste manually.

Yes. On Pro and Team plans, open Account → AI → Use your own key, choose OpenAI or Anthropic (Claude), and paste your key — it starts with sk- for OpenAI or sk-ant- for Anthropic. All of ShellSage's AI features (Ask Sage, Explain, Fix, and the command bar) then run on your own account with no monthly caps, billed by your provider instead of us. The key is verified with the provider, stored encrypted, and only the last 4 characters are ever shown; you can remove or replace it anytime.

A tunnel opens a port on your phone and pipes anything that connects to it through your SSH session to a remote address — exactly like ssh -L on a desktop. In the terminal's menu tap Port forwarding (the session must be connected), add a local port (1024–65535), a remote host (usually localhost, from the server's point of view), and the remote port. For example, forward local 5432 to the server's internal database at localhost:5432, then point a database app at 127.0.0.1:5432. Tunnels bind to 127.0.0.1 only and auto-close when the SSH session disconnects.

On Android, sessions keep running when you switch apps via a foreground service (the “session active” notification), and any running command or AI tool keeps the session alive indefinitely; an idle session at a bare prompt disconnects after about 10 minutes, with a 2-minute “Still there?” countdown first so you can tap Stay connected. On iOS the system forbids long-running background SSH, so a backgrounded session drops and reconnects when you reopen the app — use tmux or screen on the server for uninterrupted long tasks there.

On the Hosts screen, tap the import icon next to the plus button. Paste your OpenSSH config or a PuTTY export, or pick the file, then tap Scan. Review the servers it found, tick which ones to bring in, and import. You can add one key or password for all of them at once, or add keys later when you first connect to each host.

When you launch Claude or Codex, ShellSage asks how it should run for that session. I Want Control (recommended) pauses your AI on every yes/no confirmation and waits for you to tap Yes or No — nothing runs without your approval. Full Automation taps Yes for you on every confirmation so the AI runs end-to-end without stopping, even when you connect as root. Only choose Full Automation if you trust the assistant and have backups in place; you are responsible for whatever it runs, and you can switch back to Control by reconnecting.

When a new version ships, a banner appears on launch. Tap What's new to read the changelog, then Download. The update downloads inside the app with a 0–100% progress bar and the Android installer opens automatically — you never dig through a browser. The first time only, Android asks you to allow ShellSage to install unknown apps. Critical security fixes ship as forced updates you can't decline, and an auto-check runs on every cold start.

Email shellsage@aicanadiansolutions.ca for general questions, bug reports, and feature requests, or security@aicanadiansolutions.ca to report a security vulnerability (responsible disclosure honored, with a 90-day window). Every message is read by the founder, with a reply within 24 hours on weekdays.