Agents on a server,
answered from your Mac.

In Gnista’s Settings ▸ Remote, click Connect and choose a host from your ssh config. Gnista copies its helper there, connects every agent it finds, and keeps one connection open through your own ssh. Their sessions show in the notch with the machine’s name.

• Gnista on your Mac, macOS 15 or later.
• A Linux server, x86_64 or arm64, or a Mac with Remote Login on.
• Your agents installed there, for the user you log in as: Claude Code, Codex, Gemini CLI, OpenCode, Copilot CLI or any other agent Gnista connects on your Mac.
• The machine in your ~/.ssh/config. A key that needs nothing from you is easiest; if logging in needs a password, a code or a key approval, Gnista asks you once, in Terminal.

An entry like this one is enough. Gnista uses everything your config says, so ports, users, keys, ProxyJump and the hosts that Coder, Codespaces or DevPod add to it work as they do in Terminal.

Host devbox
  HostName devbox.example.com
  User dev
  IdentityFile ~/.ssh/id_ed25519

ssh devbox uname -sm

It should print Linux x86_64, Linux aarch64 or Darwin arm64. If ssh asks to trust the host key, answer it there once.

1. Open Gnista’s Settings ▸ Remote. Click Connect and choose the host, devbox here. One that isn’t in your config: Other Host…, then type it.
2. Gnista checks the system with uname, copies its helper for that system into ~/.gnista there, and checks it arrived unchanged. Then it adds its hooks to each agent it finds.
3. The machine’s row says how many it connected, such as “Connected, 2 agents”. Hover it for their names.
4. If the row says “Needs you to log in.”, click Log in. Terminal opens, you log in once, and Gnista’s connection goes through that login.
5. Start a session on the server. Its row appears in the notch, with the server’s name next to the project.

• A row per session, with the machine’s name where a local row shows its app. Hover it: “On devbox, over SSH”.
• Its requests in the notch. When the agent asks, the notch opens with the request, as for a local session. With Settings ▸ General ▸ Answer prompts in Gnista on, you answer it there; Gnista keeps that setting in step on the server.
• Details. The title, the latest message, and tokens and cost, read on the server for the agents that keep them.
• The right tab. A click brings up the terminal tab on your Mac whose ssh, mosh or Eternal Terminal the agent came in on, and its tmux pane there. In a VS Code, Cursor, Windsurf or Zed remote window, that window; for a session Claude Desktop started over SSH, its chat.
• One login. Setup, the connection and the clicks share one ssh connection, so a Duo push or a key approval comes once, not each time.
• A connection that comes back. After a drop, sleep or a network change, Gnista reconnects by itself. Meanwhile the rows stay, and the machine says “Can’t reach it right now.”

Each machine’s ⋯ menu has a Connection setting. Automatic suits most servers. Without forwarding sends the hooks’ messages over an ordinary ssh command instead of a forward. Through my own ssh leaves Gnista with no connection of its own: Set up installs the helper once and gives you a RemoteForward line for your ssh config, so your own ssh sessions carry the agents’ events. For your IT team: security and privacy.

Connect the same server from each of your Macs. Each gets a socket of its own there, all of them show its sessions, and the first answer to a request decides. Disconnect on one Mac leaves Gnista on the server for the others.

Each time the connection starts, Gnista brings these up to date: a new helper after Gnista updates, and hooks for an agent installed since. Your agents’ settings are backed up before Gnista adds its hooks, and your own hooks stay.

For each machine, Gnista opens a socket on your Mac and runs your ssh with a reverse forward to it, so the hooks there talk to Gnista on your Mac through that connection. In short:

ssh -N -o ControlMaster=yes -R /home/dev/.gnista/sockets/<this Mac>.sock:<a socket on your Mac> -- devbox

Where the server forwards no sockets, Gnista forwards a port on its loopback instead, and each connection must start with a password only your account there can read. Where it forwards nothing, the helper carries the hooks’ messages over an ordinary ssh command.

The server’s name on a row comes from which connection an event arrived through, not from what the server says, so one server can’t pose as another. If the connection is down, the hooks find no Gnista, return at once, and the agent asks in its terminal as usual.

The helper for Linux comes from Gnista’s public downloads on GitHub, once per version of Gnista and processor, and Gnista uses it only if Gnista’s key signed it for that version. A Mac gets the helper from your Gnista, signed and notarised.

• “ssh said: …” ssh’s own last words. Run the check above with the same host, then click Connect again.
• “Needs you to log in.” Click Log in and log in in Terminal. With 1Password, its prompt may be waiting behind other windows; hover the row for what ssh said.
• “Can’t reach it right now.” Hover the row for ssh’s words. Gnista keeps trying, waiting longer each time.
• “Gnista connects Linux machines and Macs; this one is “…”.” The host runs another system, which Gnista can’t connect.
• “Gnista couldn’t download its helper for Linux. Check the Mac is online, then try again.” Your Mac needs to reach github.com the first time a server needs the helper for this version.
• “The helper arrived changed on the way” Gnista didn’t use it. Click Connect again.
• “Connected, but none of its agents is one Gnista connects.” Install an agent on the server, for the same user. Gnista connects it the next time the connection starts, or at once if you Disconnect and Connect.
• “It’s the same account as …, which is connected already.” Two names in your ssh config lead to the same account. Keep one.
• A session doesn’t show. Check the machine’s row says Connected, then start a new session; one that was already running may not have Gnista’s hooks.
• “Turned off by your organisation.” Your Mac is managed, and RemoteMachinesAllowed is off. Ask your IT team.

• Terminal notifications: Claude Code’s own notifications are escape codes in the terminal, so they travel over ssh to iTerm2 and other terminals that show them. They say something happened, not which server or session, and you answer in the tab.
• A tmux bell, with monitor-bell and a terminal that turns bells into notifications. Free, and the same limits.
• A hook that posts to a phone notification service, such as ntfy. It reaches you anywhere, but you write and maintain it, and answering still means going to the terminal.

• Anyone with root on the server can answer your approvals, since they can reach the socket. Connect servers you trust.
• Replies from the notch and plan limits are for sessions on your Mac; a server’s rows don’t have them.
• Disconnect removes Gnista’s hooks and ~/.gnista from the server, unless another Mac still uses them. If the server can’t be reached then, the hooks stay; without Gnista they do nothing.
• Agents in containers or Kubernetes pods: agents in containers.
• Organisations can turn remote machines off for their Macs: managed settings. What Gnista sends and where: privacy.
• Seven days free, then €19 once. More on Claude Code, Codex, Gemini CLI and OpenCode.