Session sharing and moderation

You can share a session with people who can open the same vault as its host. They either watch your terminal, or connect to the host themselves and attach to the same tmux session. In a live view you decide who only watches, who may be handed the keyboard, and who may end the session. For sensitive vaults, owners can require that every session is watched: it starts only once someone who manages the vault has joined to watch it.

Sharing is for hosts in a team. A host in your personal space cannot be shared: “Sessions can be shared with people in a team, because that is where ZestSSH knows who they are and has checked their keys. Move this host into a team’s vault to share it.”

	Shared tmux (recommended)	Live view
How	Each person connects with their own sign-in and attaches to the same tmux session.	They watch your terminal through an end-to-end encrypted stream.
What goes through ZestSSH	Nothing of the terminal. ZestSSH Cloud only says who is there.	The terminal, encrypted between your device and theirs. ZestSSH Cloud cannot read it.
Credentials	Everyone uses their own access to the host.	They never get the host’s credentials.
Typing	Each person types in their own connection to the host.	Nobody but you, until you hand someone the keyboard.

A shared tmux session needs tmux on the host, and the host must have reached ZestSSH Cloud so that the others have it (“This host has not reached ZestSSH Cloud yet, so the others do not have it. Sync first.”). When the tab is not in tmux yet, “A new tmux session starts in this tab. What the terminal shows now stays outside it.” A tmux session’s name must use only letters, digits, dash and underscore. People who join must sign in to the host as the same user as you to see the same session.

A live view needs the tab’s own terminal: while the tab shows tmux, “Share it as a shared tmux session, or leave tmux to share a live view.”

Connect to a host in a vault.
Open the session’s menu: on a computer, from the status chip in the session’s header; on a phone, from the terminal’s menu. Choose Share this session.
Choose Shared tmux (marked Recommended) or Live view.
Under Who, tick the people. Only people with access to the vault are listed, and someone whose keys changed since you compared them shows Key changed, verify first and cannot be picked. Their Verify button opens the team’s members, where you compare their keys.
For a live view, choose who may do what (see below).
Choose Invite to tmux session or Start live view.

They get a notice, “You are invited to a shared session”. To invite more people later, open the list of people (see Who is there) and choose Invite more people. On a computer, the session’s menu then says Sharing: people and keyboard.

You need your account keys on this device and the team open: otherwise “This session cannot be shared from this device right now.”

Who may do what in a live view

Everyone you invite to a live view watches your terminal, and nothing they type is sent unless you hand them the keyboard. On top of that, each person has one of three parts. ZestSSH does not use the words observer, operator and moderator; this is what the three are in the app:

Part	Who has it	What they can do
Observer: watches only	Anyone with the Connect level in the vault. The list says “can watch only”.	Sees your terminal. Is never handed the keyboard.
Operator: may be handed the keyboard	Everyone else you invite, unless they can end the session	Watches, and types into your session while they have the keyboard. With Let them request the keyboard on, they can also ask for it.
Moderator: can end the session	Those you mark with Can end the session	Watches, never types, and can close your session on your device.

Let them request the keyboard is on by default. Turned off, nobody can ask for the keyboard, and you can still hand it to an operator yourself.
Can end the session is set per person, under their name, once you tick them. Someone who can end the session is never handed the keyboard.

Hand over the keyboard

When someone asks, you see “priya@example.com asks for the keyboard”, with Give keyboard and Not now. Once you give it, “priya@example.com has the keyboard and can type in this session”, with Take back.

One person at a time has the keyboard. You keep yours: “You can still type”.
What anyone else types is dropped.
When ZestSSH locks on your device, the keyboard comes back to you. Watching goes on.
The person with the keyboard can choose Give it back.

Who is there

On a computer, a shared session’s header shows a chip such as Live view · 2 or Shared tmux · 1. On a phone, a strip under the toolbar says the same. Either one opens the list of people, with where each one stands: Invited, Declined, Connecting, Attached (shared tmux), Watching, Watching (can watch only), Watching (can end the session), Asks for the keyboard or Has the keyboard. From there you can give or take back the keyboard, remove someone, invite more people, or stop sharing.

When the vault logs sessions, the shared session is logged too, with who joined and left, and who had the keyboard when.

Join a shared session

Open the invitation from the notice, or open Shared with you: on a computer from the people icon in the top bar, which shows while something is shared with you, or from the command palette; on a phone from More.
Read what it says: who shares, on which host and in which vault, and what you can do.
Choose Watch for a live view or Join for a shared tmux session. Decline tells the person sharing.

A live view opens on its own screen, which says “End-to-end encrypted: ZestSSH Cloud cannot read this”. There you can Ask for the keyboard when you may, End session when you can, and Leave.

A shared tmux session opens a session of your own to the host, with your own sign-in, and attaches to the tmux session by name. The host must be on your device already, in the same vault: “This host is not on this device yet. Sync the team, then join again.”

When the keys of the person sharing changed since you compared them, the invitation says so, and you compare them on the Team page before you can join.

Limits

8 people at most in one share.
3 shared sessions at once for one account: “You are sharing three sessions already. Stop one to share another.”
12 hours at most for a share, however long the session lasts.
One device per person. Joining from another device stops the first: “You joined from another device, so this one stopped watching.”
Nothing is kept. ZestSSH Cloud keeps no log and no history of a share once it ends, and nothing about who joined.

What happens	What the people watching see
You choose Stop sharing and confirm. In a live view everyone watching is disconnected and your own session goes on. In a shared tmux session everyone else is detached from the tmux session, and can still connect to the host themselves.	”alex@example.com stopped sharing.”
Your session closes, or loses its connection.	”The session closed.”
You remove someone, with the Remove from this share button by their name. They cannot come back with that invitation.	”alex@example.com removed you from this share.”
Someone who can end the session chooses End session and confirms. It closes on your device at once, for you and everyone watching. You are told “Someone watching your session ended it."	"The session closed.”
12 hours pass, or your device is away from ZestSSH Cloud for three minutes.	”This share has ended.”
Someone loses access to the vault. Their invitation disappears and their connection is dropped.	”This share is no longer available to you.”
You sign out. Every share of yours ends, and so does every view you watch.	”alex@example.com stopped sharing.”

A viewer can also choose Leave at any time, or Decline an invitation.

Watched sessions

For a sensitive vault, owners can make every session to its hosts a watched one. A session then starts only once someone else who manages the vault has joined to watch it, typing is held while nobody watches, and whoever watches can end the session.

Turn it on (owners)

Open Team, then Vaults. On a computer, click the vault to open its pane. On a phone, each vault is a card with its settings under it (with more than three vaults, open them with What it allows).
Turn on the switch of the Watched sessions row: under Protection in the pane on a computer, under Access on the card on a phone.
Read Watch sessions to Production’s hosts? and choose Watch sessions. ZestSSH may ask you to sign in again first.

Turning it on switches off SFTP, port forwarding and agent forwarding in the vault, because they cannot be watched: a watched vault allows the terminal only. Everyone who can open the vault is told, and an invitation to the team says how many of the vaults it opens are watched. Everyone else sees Sessions watched on the vault, and a host in it says “Sessions to this host are watched”: on a computer on its panel, with a small mark on its card, and on a phone with the same mark in the host list.

To turn it off, turn the switch off, then choose Stop watching in Stop watching sessions to Production’s hosts?. “SFTP and forwarding stay off until someone allows them again.”

Only owners turn watched sessions on or off.

Connect to a watched host

Connect as usual. Ask someone to watch lists everyone else who manages the vault (“Manages Production”).
Tick one or more and choose Ask to watch. They get an invitation under Shared with you: “alex@example.com asks you to watch a session”.
The tab shows Waiting for someone to watch: “The connection is made once one of the people you asked has joined.” Ask someone else asks more people.
Once one of them is watching, the connection is made. Not even a jump host is dialled before that.

If nobody joins within 10 minutes: “Nobody joined to watch, so the session was not started. Connect again when someone who manages the vault is around.”

Who can watch: someone else who has Manage in the vault. Someone whose keys changed since they were compared is listed with Key changed, verify first and cannot be asked until you compare them again. You cannot watch your own session, so a watched vault needs at least two people who manage it: “An owner can give a second person Manage in it.” ZestSSH looks at the team’s record again every 15 seconds while a session runs: someone who no longer manages the vault no longer counts as watching.

While nobody is watching

When everyone who may watch has left, the session is held: “Nobody is watching. Typing is held, and the session closes in 1:45.” Nothing typed reaches the host: not from you, not from someone handed the keyboard, not a snippet, not a broadcast from another tab. After two minutes of that, the session closes: “A watched session was closed: nobody was watching it.” Someone who joins in time makes it a watched session again.

When the vault logs sessions, the log has lines such as “Nobody is watching: typing is held”, “Watched again” and “priya@example.com ended the session”.

What a watched session cannot do

No shared tmux session, only a live view: “Sessions in this vault are watched, so only a live view is possible.”
No SFTP, port forwarding or agent forwarding, and no tmux control mode. tmux typed in the terminal works as ever.
Its hosts cannot be jump hosts, and the host editor makes no test connection.
Nothing connects to its hosts without a watched session: no Server monitor checks, no commands from Run on hosts, and no reconnecting on its own after a dropped connection.
The vault’s keys sign in only to the vault’s own hosts: “This key is in a vault whose sessions are watched, so it signs in only to that vault’s hosts.”

When ZestSSH Cloud cannot be reached

A live view goes through ZestSSH Cloud, so while it cannot be reached nobody can be asked to watch. The service being away must not stop a team from reaching its machines, so then, and only then:

An owner can connect with nobody watching, after giving a reason. Connect with nobody watching? asks for Your reason; choose Connect without a watcher. A session that is held can go on the same way with Go on without a watcher.
Everyone else can too, where the owners allowed it. Under the Watched sessions row, the vault says “ZestSSH Cloud unreachable: owners connect, with a reason”. Owners can choose Change, read Let everyone connect to Production?, and choose Let everyone connect. The row then says “ZestSSH Cloud unreachable: everyone connects, with a reason”, and Change, then Owners only, takes it back. Without that: “The owners have not allowed that for anyone else in this vault.”

Such a session is reported in the team’s record once the device is back online: who connected, in which vault and when, for every member to read, and the host and the reason, sealed for those who can open the vault. Those who manage the vault, every owner among them, are told “A session in Production ran with nobody watching”. If the report cannot be kept on the device first, the session does not start. If ZestSSH Cloud answers again while you are being asked, someone can be asked to watch after all.

What it does not do

It is a rule the ZestSSH app keeps. ZestSSH puts no machine of its own between your members and your hosts. Someone who reaches a host some other way, with credentials from the vault, is not stopped by it.
A watcher sees what the terminal shows. What runs out of sight of the terminal is not on their screen.

Next steps

Team session logs: where the lines about who watched and who had the keyboard go.
Vaults, access and roles: the Connect and Manage levels that decide who watches and who may watch.
Password managers: keep a key’s password in your password manager.
Seats and billing: everyone you share with is a member who holds a seat.
Setup as code: a setup file can mark a vault as watched.