# Access services with SSH

SSH identities allow you to SSH into running service containers using your SSH keys. This enables integration with development tools like VSCode and Cursor, and file transfer using standard SSH tools (scp, sftp, rsync).

SSH identities are managed at the team level and can be restricted by project or tag.

## Create an SSH identity

### Generate an SSH keypair

If you don't already have an SSH key, generate one:

```
ssh-keygen -t ed25519 -f ~/.ssh/id_northflank
```

This creates:

- `~/.ssh/id_northflank` (private key)

- `~/.ssh/id_northflank.pub` (public key)

**Load your key into your SSH agent:**

```
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_northflank
```

### Create the identity in Northflank

1. Navigate to [**Team** → **Integrations** → **SSH Identities**](https://app.northflank.com/s/account/integrations/ssh-identities)

2. Click **Create SSH Identity**

3. **Name**: Enter a name

4. **Description**: (Optional)

5. **SSH Public Keys**: Add keys

6. **(Advanced options)** Configure restrictions:
  
  
  - **Projects**: Restrict to specific projects, or leave disabled for all projects
  
  - **Tags**: Restrict by tags. Toggle "Match all tags" for AND logic (service needs all tags) or leave off for OR logic (service needs one tag)
  
  - **Both enabled**: Service must match project AND tag requirements

7. Click **Create SSH identity**

## Enable SSH on a service

SSH must be enabled on each service individually:

1. Navigate to your project

2. Select the service

3. Open the **Resources** tab

4. Check **Enable SSH**

5. Click **Update and restart**

## Connect via SSH

[Install and authenticate the Northflank CLI](/docs/v1/api/use-the-cli) before connecting.

### Direct SSH session

To SSH directly into a service:

**Interactive selection:**

```
northflank ssh service
```

**Specify project and service:**

```
northflank ssh service --projectId my-project --serviceId my-service
```

By default, this logs you in as the root user. To specify a different user:

```
northflank ssh service --projectId my-project --serviceId my-service --user my-user
```

### SSH proxy mode

To run an SSH proxy without opening a terminal session:

```
northflank ssh service --projectId my-project --serviceId my-service --proxyOnly
```

This sets up port forwarding, allowing you to use standard SSH tools:

```
SSH proxy started on endpoint: 127.24.1.1:37071, stop with Ctrl+C
Use with any SSH compatible client. Example usages:
  > SSH session: ssh root@127.24.1.1 -p 37071
  > SFTP:        sftp -P 37071 root@127.24.1.1
  > RSYNC:       rsync -avz -e "ssh -p 37071" ./data/ root@127.24.1.1:/rsync-test/
  > SCP:         scp -P 37071 file.txt root@127.24.1.1:/remote/path/
```

## Transfer files

With the SSH proxy running (`--proxyOnly`), you can transfer files using standard tools. Replace the port with the one shown in your proxy output.

**Copy a file to the service:**

```
scp -P 51887 model.bin root@127.0.0.1:/data/
```

**Copy a file from the service:**

```
scp -P 51887 root@127.0.0.1:/data/results.csv ./
```

**Sync a local directory to the service:**

```
rsync -avz -e "ssh -p 51887" ./my-project/ root@127.0.0.1:/workspace/
```

**Sync a remote directory to your local machine:**

```
rsync -avz -e "ssh -p 51887" root@127.0.0.1:/workspace/outputs/ ./outputs/
```

**Interactive SFTP session:**

```
sftp -P 51887 root@127.0.0.1
```

**Note:** `rsync` must be installed on both your local machine and the remote service. `scp` and `sftp` are included with OpenSSH by default.

## Connect your editor

You can connect VSCode or Cursor to your service using the SSH proxy.

> [!note]
>
> Mount a directory that is persisted (backed by a volume). Otherwise, you risk losing changes when the container restarts. See [Add a persistent volume](/docs/v1/application/databases-and-persistence/add-a-volume).

### Cursor

1. Start the SSH proxy: `northflank ssh service --projectId my-project --serviceId my-service --proxyOnly`

2. In Cursor, click **Connect via SSH**

3. Paste the command (e.g., `ssh root@127.24.1.1 -p 37071`) and press Enter

4. Approve the host keys when prompted

5. Once connected, click **Open Folder**

### Visual Studio Code

1. Start the SSH proxy: `northflank ssh service --projectId my-project --serviceId my-service --proxyOnly`

2. In VSCode, install the Remote SSH extension

3. Click the Remote SSH button and select **Connect to Host**

4. Enter the SSH command in this format: `ssh <user>@127.0.0.1 -p <port>`
  
  Example: `ssh root@127.0.0.1 -p 51887`

5. Select the platform and approve the host keys

For more details, see the [VSCode Remote SSH documentation](https://code.visualstudio.com/docs/remote/ssh).

## Troubleshooting

**Permission denied (publickey):**

```
Permission denied (publickey).
SSH exited with code: 255
```

Check that:

- You added the correct **public key** to the SSH identity

- SSH is enabled on the service's **Resources** page

- You have added the key to your SSH agent: `ssh-add ~/.ssh/id_northflank`

- Your service matches the project or tag restrictions configured on the SSH identity

## Limitations

- SSH access is currently available for **services only**. Job support is planned for the future.

- Services automatically open port 22 for SSH. You should not manually configure this port.