> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sinelaw/fresh/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote Editing via SSH

> Edit files on remote machines via SSH without installing Fresh remotely

<Warning>
  This feature is experimental.
</Warning>

Fresh supports editing files on remote machines via SSH using the `user@host:path` syntax. This is useful for editing files on servers without needing to install Fresh remotely.

## Quick Start

<CodeGroup>
  ```bash Open a specific file theme={null}
  fresh deploy@server.example.com:/etc/nginx/nginx.conf
  ```

  ```bash Open home directory theme={null}
  fresh user@host:~
  ```

  ```bash Open with line number theme={null}
  fresh user@host:/var/log/app.log:100
  ```
</CodeGroup>

## Features

<CardGroup cols={2}>
  <Card title="Authentication" icon="key">
    Password and SSH key authentication supported
  </Card>

  <Card title="File Explorer" icon="folder-tree">
    File explorer shows remote directory structure
  </Card>

  <Card title="Sudo Save" icon="shield">
    Save protected files with sudo support
  </Card>

  <Card title="Status Indicator" icon="server">
    Status bar shows `[SSH:user@host]` indicator
  </Card>
</CardGroup>

## Requirements

<Steps>
  <Step title="SSH Access">
    You need SSH access to the remote host
  </Step>

  <Step title="Python 3">
    Python 3 must be installed on the remote host (for the agent)
  </Step>
</Steps>

## SSH Syntax Examples

```bash theme={null}
# Edit a configuration file
fresh admin@webserver:/etc/apache2/apache2.conf

# Edit a log file at a specific line
fresh dev@api.example.com:/var/log/application.log:250

# Open user's home directory
fresh user@host:~/projects

# Edit files requiring sudo (Fresh will prompt for sudo password when saving)
fresh root@server:/etc/systemd/system/myservice.service
```

## How It Works

<Steps>
  <Step title="Connection">
    Fresh establishes an SSH connection to the remote host using your SSH credentials
  </Step>

  <Step title="Agent Transfer">
    A lightweight Python agent is transferred to the remote host
  </Step>

  <Step title="File Operations">
    The agent handles file reading, writing, and directory browsing
  </Step>

  <Step title="Local Editing">
    You edit files locally in Fresh with all features available (LSP, syntax highlighting, etc.)
  </Step>

  <Step title="Synchronization">
    Changes are automatically synced back to the remote host when you save
  </Step>
</Steps>

<Info>
  The remote agent is temporary and doesn't require installation. It's transferred on-demand and runs only during your editing session.
</Info>

## Alternative: SSH + Session Persistence

If you need a persistent editing session that survives connection drops, consider running Fresh directly on the remote host with [Session Persistence](./session-persistence.mdx):

```bash theme={null}
ssh user@host
fresh -a        # start a persistent session on the remote host
# if SSH disconnects, just reconnect and reattach:
ssh user@host
fresh -a
```

### SSH + tmux

You can also pair SSH with `tmux` for a similar effect—run `tmux` on the remote host and launch Fresh inside it.

<Tip>
  Session persistence has the advantage of being built into Fresh, so editor state (open files, terminals, undo history) is preserved without an external multiplexer.
</Tip>

## Comparison: Remote Editing vs SSH Session

| Feature          | Remote Editing (`user@host:path`) | SSH + Session Persistence         |
| ---------------- | --------------------------------- | --------------------------------- |
| **Installation** | No installation on remote         | Fresh must be installed remotely  |
| **LSP Support**  | Runs locally                      | Runs on remote host               |
| **Latency**      | Higher (file transfers over SSH)  | Lower (local to remote host)      |
| **Persistence**  | No session persistence            | Full session persistence          |
| **Network Drop** | Connection lost                   | Can reattach to session           |
| **Use Case**     | Quick edits, single files         | Long-running development sessions |

<Note>
  Choose remote editing for quick configuration changes or log inspection. Choose SSH + session persistence for full development workflows on remote machines.
</Note>