Start an SSH session
An SSH session in VaultPAM is a secure terminal connection to a Linux or Unix server (or any device that speaks SSH), launched and recorded through the platform instead of by sharing server passwords directly.
VaultPAM checks that you are authorised to connect to the target server under a named Safe, retrieves the server's credentials from the vault on your behalf — you never see or type the actual username or password — connects you through an encrypted tunnel, and records the terminal so the session can be reviewed later for audit or compliance.
From your perspective, an SSH session looks and feels like any other terminal window. The difference is that access is controlled, credential-free for you, and fully recorded.
Before you begin
- You are a member of an Organisation on the platform.
- You have been granted access to a Safe that contains the target server (your org admin assigns Safe memberships).
- The Safe contains a Resource (the target server) with an associated Account whose SSH credentials are stored in the vault.
- Your organisation's connector for that resource is online (a green indicator next to the connector in the Endpoints list).
If your organisation requires an approval (for example, from a manager) before a session can open, you are shown an Approval required screen — see Approve a pending session for what happens next.
Start the session from the VaultPAM dashboard
- Log in to the VaultPAM dashboard.
- Click Sessions or Resources in the left sidebar.
- Find the server you want to connect to. Filter by Safe name, resource name, or IP address.
- Click Connect (or the SSH icon) next to the resource. If the resource supports multiple protocols, make sure SSH is selected.
- If your Safe policy requires an extra verification step at the moment of connection, complete it using your authenticator app or security key.
- A terminal window opens in the browser — you are now connected. The window title shows the resource name and session ID, and a small recording indicator may be visible in the corner.
Note: You do not need to remember or enter a server password. VaultPAM handles credential retrieval automatically.
If the Connect button is greyed out or you do not see the resource at all, see Launch your first session.
Start the session with a native SSH client
For workflows that need a real terminal application (scripting, SCP, SFTP), VaultPAM supports connecting via your local SSH client instead of the browser window.
-
Start the session from the dashboard as described above. When a native-client option is available, the dashboard displays an SSH command instead of opening a browser terminal:
ssh -p 2222 <session-token>@<proxy-address> -
Copy that command and paste it into your terminal application.
-
The token in the command is valid for a short window (typically a few minutes). Use it promptly — if it expires, click Connect again in the dashboard for a fresh command.
-
Your terminal connects and you are dropped into the remote shell.
Important: Do not share the SSH command shown on the dashboard with anyone. It is a single-use access token — once used, it cannot be used again, and once expired, it cannot be used at all.
Any standard SSH client works: OpenSSH (built in on macOS and Linux), PuTTY on Windows, or any terminal emulator with SSH support. No special plugins or configuration are needed beyond what VaultPAM shows on screen.
What gets recorded
Everything that appears in the terminal window is recorded: every command you type, all output the server sends back, and the full session timeline from connect to disconnect.
| Item | Recorded? | Notes |
|---|---|---|
| Your keystrokes (what you type) | Yes | Including passwords typed at prompts on the remote server |
| Server output | Yes | All text in the terminal |
| Your local clipboard | No | Copy-paste on your local machine is not visible |
| Files transferred (SCP/SFTP binary) | No | Binary file transfer streams are not decoded into the recording |
| Screen content outside the terminal window | No | Only in-terminal text |
Important: If the server itself asks you to type a password (for example,
sudoasking for your local password), that password appears in the recording — a consequence of full terminal recording. If your compliance policy requires masking of typed passwords, this must be addressed at the server level (for example, via PAM modules that avoid echoing sensitive input).
The recording is stored in a standard format (asciinema) and can be replayed faithfully in the browser — you can scrub forwards and backwards through the session like a video of the terminal.
Who can see my recording
| Role | Can see recordings? |
|---|---|
| Operator (session owner) | Yes — only their own sessions |
| Org Admin / Org Owner | Yes — all recordings within their organisation |
| Auditor | Yes — all recordings within their organisation (read-only) |
| Members of a different organisation | No — recordings are strictly separated by organisation |
Recordings are scoped to your organisation; no one outside your org can access them. An auditor or admin can view any recording in the org, not only sessions they personally launched — this is intentional and supports compliance and incident review. Recordings are retained according to your organisation's retention policy (default: indefinitely until manually deleted).
Play back a recording
- Log in to the VaultPAM dashboard and open Sessions in the sidebar.
- Find the session you want to review — filter by date, resource, user, or Safe.
- Click the session row to open the recording player.
- Use Play/Pause, the scrub bar, speed control (1×, 2×, or faster), and the activity timeline (where available, marking periods of high keystroke activity).
Tip: For long sessions, use the speed control to skip idle periods quickly; the activity timeline highlights the busiest moments.
If a recording is still processing (the session ended very recently), the player shows "Processing" — refresh after 30–60 seconds. If the status shows "Failed", contact your VaultPAM admin.
Share or export a recording
You can give a stakeholder — an external auditor, a regulator, or a manager without a VaultPAM account — access to a specific recording without granting broader platform access. See Share a recording for creating a time-boxed shareable link, granting access to a specific VaultPAM user, revoking a share early, or requesting an MP4 export.
Troubleshooting
Connection refused
The SSH command fails with Connection refused, or the browser terminal shows an error before the session starts.
| Cause | What to do |
|---|---|
| The session token has expired | Return to the dashboard and click Connect again for a fresh command |
| The SSH proxy service is not running | Check the Endpoints page — if all connectors are offline, contact your VaultPAM admin |
| A firewall is blocking port 2222 | Ask your network team to allow outbound TCP to the proxy address on port 2222 |
| The target connector is offline | The connector indicator shows red/offline on the Endpoints page — ask the connector owner to restart it |
See My RDP session disconnects unexpectedly — many of the same network-level checks apply to SSH sessions.
Authentication failure
The SSH client connects but immediately shows Permission denied or Authentication failed.
| Cause | What to do |
|---|---|
| The session token was already used | Each token works only once — return to the dashboard for a new Connect command |
| The token expired before you used it | Tokens are valid for a few minutes — return to the dashboard for a fresh command |
| Your Safe access was revoked between clicking Connect and connecting | Contact your org admin to verify your Safe membership |
| The vault credential for the target is missing or misconfigured | Contact your VaultPAM admin |
| A step-up verification was required but not completed | Return to the dashboard — if a step-up prompt appears, complete it before running the SSH command |
Note: You should never need to know or enter the target server's actual password. If VaultPAM asks you for a password for the proxy connection, something is misconfigured — contact your VaultPAM admin.
Idle timeout or disconnected
The session drops while you are not typing, or closes unexpectedly.
- SSH idle timeout on the target server: many servers disconnect idle SSH sessions after a period (commonly 5–30 minutes). This is configured on the target server, not in VaultPAM. Ask the server administrator to increase
ClientAliveIntervalorServerAliveIntervalon the target if this affects your workflow. - Network interruption: reconnect via the dashboard if your network connection dropped briefly.
- Planned maintenance: occasionally a maintenance restart of the SSH proxy service drops active sessions. Your VaultPAM admin can confirm whether maintenance is in progress.
Tip: For long-running commands that must survive a disconnect, consider using a terminal multiplexer (such as
screenortmux) on the remote server — your session survives a network drop and you can reconnect and re-attach.
Recording not visible after session ends
The session ended but you cannot find it in the Sessions list.
- Wait 60 seconds and refresh — recordings are processed in a background scan.
- Check the date filter — the session may be filtered out by the current date range.
- If the session ended abruptly (for example, connection refused or a proxy crash), the recording file may be incomplete and marked Failed. Contact your VaultPAM admin.
See also My SSH session fails to connect for additional connection-time diagnostics.
Privacy and retention
- Full terminal I/O is recorded as an asciinema
.castfile, stored in your organisation's object storage, scoped to your org. No other organisation can access your recordings. - A metadata record is stored in the platform database (session ID, resource, start time, duration, recording status) — no raw terminal content is stored in the database.
- Access is limited to members of your organisation with the Auditor or Admin role, plus the session owner (see Who can see my recording).
- Recordings are kept according to your org's configured retention policy (default: indefinitely until deleted). An admin can delete a recording from the Sessions view, which removes both the metadata record and the stored file. If your organisation is deleted from the platform, all associated recordings and metadata are purged.
- Every access to a recording — playback, download, and share creation — is written to the audit log; external share recipients are also audited each time they open a shared recording.
- Recordings capture everything visible in the terminal, including any sensitive output that appears (for example, decrypted secrets printed to the shell). VaultPAM has no way to automatically redact sensitive content from recordings — avoid printing secrets to the terminal during sessions subject to external audit review.