SpectaShell · Security
Security
Shells that stay. Keys that don't move.
SpectaShell speaks plain SSH to your servers, keeps your shells running on them through your own login, and keeps each device’s key in a chip it never leaves. No Calida Lab server ever sees your terminal: the one server Calida Lab runs relays notifications from hosts, sealed on the host (HPKE) so that only your device can open them.
How a shell keeps running
A shell normally belongs to the connection that started it: when the connection drops, the shell is hung up and whatever ran in it ends. SpectaShell starts each shell inside a small program of its own, spectashell-keeper, on the machine where the shell runs. The keeper holds the shell and the last part of its output, so the shell keeps running when the connection drops, the device sleeps or the app quits, and it shows you its screen again when you come back.
Your Mac, iPad or iPhone
- SpectaShell
- This device's key, in the Secure Enclave
Your server, as you
sshd→spectashell-keeper attach- keeper → its shell
- a socket in a folder only you can open (
0700) - no network port, no root
- Runs as you. The keeper is an ordinary process of your own account, with your permissions and nothing more. It needs no root and installs no system service.
- No port. It listens on a Unix socket in a private folder, never on the network. The app reaches it only by running
spectashell-keeper attachthrough your SSH login. It sends nothing anywhere, except, once a device of yours has notifications on, a sealed notification to SpectaShell’s relay (Notifications from hosts). - A folder only you can open. Sockets live in
/tmp/spectashell-<uid>/keeperson Linux — the same place at every login, and kept when you log out, unlike$XDG_RUNTIME_DIR, as tmux keeps/tmp/tmux-<uid>— and in~/Library/Application Support/SpectaShell/keeperson a Mac, which cleans its/tmp. Before using either, the keeper checks that the folder is a real folder, not a link, owned by you and closed to everyone else. If another user made it first, the keeper refuses to start rather than use it. - Safe from
/tmpcleaning. The keeper touches its socket, its description and their folders every hour, so age-based cleaning (systemd-tmpfiles) passes them by; if the folder is removed anyway, the keeper makes it again and your shell can be reached as before. - Installed only when you allow it. The first time you keep shells on a host, SpectaShell asks, then puts the program in
~/.local/share/spectashell/. A host where you say no works over plain SSH. - Keeps little, and only there. The shell's recent output stays in the keeper's memory; a small description — what runs, its folder, the last four lines of its screen — sits beside its socket, readable only by you. It goes nowhere but to your own devices.
- Ends cleanly. Close a shell and its keeper ends at once. A shell whose program ended and that no device opens again is cleaned up after 24 hours. Either way, a short note of how it ended stays for 30 days, so another device can say who closed it.
- Listing without Face ID. Running lists a host's shells with a second key of the device's, which signs without asking. The host lets it run one command, the keeper's list: no shell, no forwarding, no files. That list carries each shell's name, folder, program and the last four lines of its screen, so a device left unlocked shows them without Face ID — as it already shows the shells open in it.
~/.ssh/authorized_keys: restrict turns off the terminal, forwarding and the agent, and the forced command runs the keeper’s list, whatever the connection asks for.restrict,command="$HOME/.local/share/spectashell/current/spectashell-keeper list" ecdsa-sha2-nistp256 AAAA… SpectaShell listing on iPhoneto breach.
There is nothing of yours on a server of ours.
SpectaShell has no sign-up and no login. Sync and teams run on your own Apple Account's iCloud, so there is no Calida Lab account, no password database and no server of ours that could leak your hosts or keys.
How you can trust what runs on your server
- Open source with the public beta. The keeper’s whole source, with the terminal engine it links, will be published under the Apache 2.0 licence when the public beta opens.
- Rebuilt to the same bytes. The Linux keepers are built so anyone can rebuild them from that source and get the same file. Each release’s SHA-256 checksums will be listed on this page, to compare with
sha256sum ~/.local/share/spectashell/*/spectashell-keeperon your server. - Checked when installed. SpectaShell uploads the keeper over your SSH login and compares its SHA-256 on your server with the app’s copy; a keeper that arrived damaged is deleted before it ever runs. It then runs it once and uses it only if it reports the exact build the app carries. Anything else stops the install.
- Updated beside the old one. You agree once per host. When a new SpectaShell carries a new keeper, it goes in beside the old one the next time you connect; running shells stay on the build that started them, and a build nothing runs any more is removed.
- On a Mac. The Mac app’s own keeper is inside the app, signed with it, and will be notarized with it at release. The keeper sent to a Mac server is signed only ad hoc, as the linker signs it, and is not notarized: it arrives over SSH, so macOS does not check it as a download. Rebuilding the Mac keepers to the same bytes also needs the same Xcode.
A key per device, in its chip
The device key
Each Mac, iPad and iPhone makes its own key in the Secure Enclave. Its private half can't be copied out, not by SpectaShell and not by anyone holding the device. It signs only after Face ID, Touch ID or the device's password, at every login.
Agent forwarding that asks
Turn on agent forwarding for a host and that host can ask your device's key to sign — to log in elsewhere or sign a commit. Each request shows which host asks and what for, and needs your face or finger on its own. Cancel once and the connection gets no more requests.
Your own keys stay where they are
On the Mac, SpectaShell reads ~/.ssh and your SSH agent as ssh does. It never changes, copies or uploads them.
A lost device
Remove a lost device from another of yours: its keys are taken off your hosts as you reach them, and it can't list your shells again. A new device can list them only once one of yours approves it.
What syncs, and what never leaves
Syncs through your iCloud
- Hosts and groups
- Snippets and triggers
- Saved port forwards and favourite folders
- Host keys you trusted
Never leaves the device
- Private keys
- Passwords, passphrases and one-time codes — never stored at all
- What your shells print
- Command history
Synced items live in your own iCloud private database. SpectaShell’s relay never holds any of it.
Where SpectaShell connects, and nowhere else
- Your hosts, over SSH. Shells, files, port forwards and the keeper all travel inside your own SSH login.
- iCloud, through your Apple Account. For sync and for groups shared with your team.
- A cloud’s API, if you connect one. DigitalOcean or AWS, to list the servers of the account you add.
- The pages you open. A web tab goes where you send it; words typed in its address bar that are not an address are searched with Google, or with DuckDuckGo, Bing or Ecosia if you choose one in Settings ▸ Shell ▸ Search With.
- Pages for agents. A coding agent in a kept shell can open and use a page of its own host’s ports, beside its shell — never a page of the web — through the shell’s own connection, with no port opened. The page’s bar says when an agent is using it, Stop keeps agents off it, and a download the agent sets off asks you first. How pages for agents work →
- SpectaShell’s relay (
push.calidalab.ai), only from a device you turned notifications on for and the hosts that notify it. - Nothing else. No analytics and no tracking. Crash reports reach us only through Apple, and only if you share them with app developers. When the Mac app checks for updates, that check will be listed here.
- Host keys are checked. A host is trusted the first time you say so; a changed key is refused, never accepted silently.
- Nothing listens. SpectaShell runs no network service. Port forwards listen on your device's own address, 127.0.0.1, unless you choose otherwise.
- Plain text is labelled. Telnet is offered for old equipment and is marked “not encrypted” wherever it shows.
- A clean environment. A shell on the Mac starts with your login's variables, not the app's.
The one server of ours, and what it cannot see
Settings ▸ Notifications ▸ Notify This Device lets your hosts tell this device that a program needs you while none of your devices is in front. Apple delivers a notification to an app only from the holder of the app’s push key, which cannot be on your hosts, so a relay of Calida Lab’s stands between them.
- The relay cannot read a notification. Each host seals what it sends to a key your device made, whose public half it publishes in your iCloud so any of your devices can write it on a host; only your device can open it. The relay passes the sealed bytes to Apple and keeps none of them.
- It does not know your hosts’ names. What a notification says about its host is your device’s own record, never the host’s word.
- On the host, a file per receiving device in
~/.local/share/spectashell-push, readable by you alone, holds the key the host signs with, made there and never leaving it, and the device’s key it seals with. The keeper sends only over HTTPS, only when something happened, and still listens on nothing. - The lock screen shows a notification’s text only as your iPhone’s Show Previews setting allows: with When Unlocked, a locked phone shows “SpectaShell” alone.
- Turning it off in Settings stops them all at once for that device; each host deletes its file the next time it tries to send, or when one of your devices next opens a shell there.
What the relay and Cloudflare see
- Your device’s notification token
- The public keys of the hosts that notify it, so how many there are
- Sealed bytes of one size
- Each request’s address, written down nowhere
- When and how often each host sends
What they never see
- What a notification says
- Which host it is: its name or address
- Your commands or anything your shells print
- Any file
- Any key that signs or opens
Security Q&A
Can Calida Lab see my shells, hosts or keys?
No. Your shells go only between your devices and your hosts, synced settings sit in your own iCloud, and keys and passwords never leave your device. SpectaShell sends us no usage data: there are no analytics. The only thing that passes through a server of ours is a notification from a host, sealed so that only your device can open it.
Do I need an account?
No. There is nothing to sign up for and nothing to log in to. Sync and teams use the Apple Account your device is already signed in with.
How do teams work without an account?
A shared group is a CloudKit share between your Apple Accounts: only the people you invite can open it. Who may log in to a host is still decided by the host — each member uses their own device key, let in by someone who can log in there.
Does the keeper open a port on my server?
No. It listens on a Unix socket in a folder only your account can open. The only way in is your SSH login.
Does it need root?
No. The keeper runs as you, from your home folder, and installs nothing system-wide.
Who else on the server can reach my shells?
Only your account — and root, who can reach every process on a machine, as with tmux or screen. On a server whose administrators you don't trust, keep anything secret out of its shells.
What does the keeper keep, and for how long?
The shell's recent output, in memory, while the shell runs; and a small description beside its socket. Close the shell and the keeper ends and removes them at once; a shell whose program ended and that nobody opens again goes after 24 hours. In both cases a short note of how it ended stays for 30 days.
Is agent forwarding safe?
Forwarding always lets a host's root use what you forward. SpectaShell makes the device's key ask you, request by request, and refuses to let the host add or remove keys. Keys of the Mac's SSH agent are forwarded as ssh forwards them, so turn it on only for hosts you trust.
Are passwords saved?
Never. A password, passphrase or one-time code is asked when needed and forgotten once the login has it. Your own password manager (Passwords, 1Password) can fill the dialog through the system's AutoFill: it keeps the password, SpectaShell does not. After one password login, SpectaShell can put the device's key on the host so the next login needs none.
I lost my iPhone. What now?
On another of your devices, open Keys and choose Remove from Every Host… beside it. SpectaShell logs in to each of your hosts and takes its keys out; a host that was off loses them at your next login there. Its keys never go on a host again.
How do I remove SpectaShell from a server?
Close its shells, then delete ~/.local/share/spectashell and /tmp/spectashell-<your user id> (on a Mac, ~/Library/Application Support/SpectaShell/keepers), and remove the lines SpectaShell added to ~/.ssh/authorized_keys: for each device, its key, ending “SpectaShell on <device>”, and its listing key, the line that starts restrict,command= and ends “SpectaShell listing on <device>”.