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.

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
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

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

Install and authenticate the Northflank 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/

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.

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

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.

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

• 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.