Remote SSH Access

Mantra v0.10.0 introduces Remote SSH Project Access, letting you connect to remote servers and manage AI coding sessions as if they were local — import, browse files, and watch live updates, all without installing anything on the remote server.

What is Remote SSH Access?

When you run AI tools on remote servers (cloud instances, dev machines, team shared servers), you previously had to log in to the server to view session records. Now, Mantra can access these sessions directly from your local machine via SSH:

• Import remote AI sessions without downloading log files locally
• Browse remote project file trees and source code
• Watch live remote AI coding sessions in real-time

Core Features

Zero-Config SSH Connection

Mantra automatically reads your existing ~/.ssh/config to discover available remote hosts:

• No extra configuration: If you can SSH to a server from the terminal, Mantra can connect too
• Authentication methods: Supports key files, SSH Agent forwarding, and password auth with automatic fallback
• Saved connections: Successfully connected servers are saved for one-click reuse, sorted by last-used time

Remote Source Auto-Detection

After connecting to a remote server, Mantra automatically scans for available AI tool sessions:

AI Tool	Detection Path
Claude Code	~/.claude/projects/
Codex	~/.codex/
Cursor	~/.config/Cursor/ (Linux)
Gemini CLI	~/.gemini/

Detection results show the estimated session count for each tool, giving you a quick overview of what's available to import.

Remote Session Import

Two methods read sessions from remote servers with no local file storage:

• SFTP streaming: For Claude Code, Codex, and Gemini CLI JSONL/JSON formats, streams via SFTP without fully downloading files
• Remote command execution: For Cursor's SQLite database, executes queries remotely via SSH

Redesigned Import Page

v0.10.0 redesigns the import page with a flat, location-grouped layout:

• Local sources: Shown at the top (Claude Code, Cursor, Gemini CLI, Codex local paths)
• Remote servers: Each server as its own group with detected sessions
• Add new server: Choose from the SSH host list or enter manually

Remote File Browsing

In the session detail view, you can directly browse remote project file structures and source code:

• Lists remote directories via SFTP
• Click any file to view its content directly; frequently accessed files are memory-cached
• Identical file tree experience to local projects

SSH Connection Pool & Keepalive

Multiple operations (file browsing, live watching, import scanning) share a single SSH connection:

• Automatic channel multiplexing: Multiple operation channels on the same connection, conserving resources
• Keepalive messages: Regular keepalive messages prevent idle timeout disconnections
• Graceful recovery: Disconnected connections automatically re-establish on next use, with a 60-second grace period

How to Use

Step 1: Add a Remote Server

1. Open Mantra's import page
2. Click "Add Server" in the Remote Servers section
3. Choose from your SSH host list (from ~/.ssh/config) or enter the host address manually
4. Select authentication method: key file, SSH Agent, or password
5. Click "Connect" — Mantra auto-detects available AI sessions on the remote server

SSH Config Tip

If you have host aliases in ~/.ssh/config, Mantra recognizes them directly — no need to re-enter IP addresses and ports.

Host my-dev-server
    HostName 192.168.1.100
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519

Step 2: Import Remote Sessions

1. Find the target remote server group on the import page
2. Select the AI tool and projects to import
3. Click "Import" — Mantra reads session data via SFTP/SSH
4. After import, projects appear in Mantra's project list

No File Downloads

Remote session data is parsed directly into Mantra's local database. Raw log files are never downloaded to your local machine.

Step 3: Browse and Watch

After import, remote projects work exactly like local ones:

• Time Travel: Replay the history of remote sessions
• File browsing: View remote project source code directly in the right panel
• Live watching: If a remote session is still in progress, live updates activate automatically (see Session Live Streaming)

Remote Project Sync

For already-imported remote projects, click "Sync" to:

• Scan the remote server for new sessions and message updates
• Without full re-import
• Automatically reconnect SSH and continue syncing after disconnection

Authentication Methods

Key File Authentication (Recommended)

# Ensure correct private key permissions
chmod 600 ~/.ssh/id_ed25519

# Test connection
ssh user@hostname

Mantra automatically looks for common key files in ~/.ssh/ (id_rsa, id_ed25519, id_ecdsa).

SSH Agent Authentication

For keys with passphrases, using SSH Agent is recommended:

# Start SSH Agent and add key
eval $(ssh-agent)
ssh-add ~/.ssh/id_ed25519

Mantra automatically detects and uses the loaded SSH Agent.

Password Authentication

Not recommended, but available when necessary. Mantra prompts for the password in a secure input field and never stores it in plaintext.

Security Notes

Important

• Mantra does not store your SSH passwords
• Private key file paths are recorded, but key content is never read (loaded via system SSH library)
• SFTP file reading only accesses necessary data, no unrelated directories are scanned
• All remote operations are read-only — nothing is written to remote servers

FAQ

Connection failed — what should I do?

Common causes and solutions:

1. SSH service not running: Verify SSH is running on the remote server (systemctl status ssh)
2. Wrong port: Default is port 22; configure non-standard ports in ~/.ssh/config using Port
3. Authentication failure: Verify correct private key or password; if using SSH Agent, confirm key is loaded
4. Firewall: Ensure the remote server's firewall allows SSH from your machine
5. Host key verification: On first connection, Mantra prompts you to verify the server fingerprint

Debugging tip: First confirm you can ssh user@hostname from the terminal, then add in Mantra.

Does it support SSH Jump Hosts (bastion servers)?

Yes, via ProxyJump in ~/.ssh/config:

Host target-server
    HostName 10.0.0.1
    User ubuntu
    ProxyJump jump-host

Host jump-host
    HostName public-ip
    User admin
    IdentityFile ~/.ssh/id_ed25519

Once configured, select target-server in Mantra — jump host routing is handled automatically.

How does remote session live watching work?

Remote live watching uses different mechanisms per AI tool:

• Claude Code / Codex: Streams the tail of remote JSONL files via SSH, equivalent to tail -f, resuming from the last offset
• Cursor: Periodically executes SQLite queries remotely via SSH
• Gemini CLI: Periodically checks remote JSON file changes via SSH

After an SSH reconnection, Mantra resumes from the last recorded offset — no messages are missed during the disconnection window.

Can I connect to multiple servers simultaneously?

Yes. Mantra supports importing projects from multiple remote servers at the same time. Each server maintains an independent connection pool. You can see projects from different servers in the project list and interact with them identically.

Next Steps

• Session Live Streaming - Learn about real-time watching in detail
• Import Wizard - Learn the complete import flow
• Project Management - Manage local and remote projects