ssh2incus – SSH server for Incus instances

β (beta) | Version 0.10 changelog

Beta notice: Breaking changes may occur between releases while the project remains in beta. Review the changelog before upgrading.

ssh2incus provides a full-featured SSH server that connects directly to Incus containers and virtual machines. It runs on the Incus host and intelligently routes incoming SSH connections to the appropriate instances using the Incus API, eliminating the need to run SSH servers inside the instances.

Features

Core Features

Web-Based User Interface:
- Browser-based terminal access to instance shells
- Auto reconnection to instances after disconnection
- Web-based instance creation interface with visual configuration builder
On-Demand Instance Creation:
- Create persistent instances with + prefix (e.g., ssh +test01@host)
- Create ephemeral instances with ~ prefix (auto-delete on poweroff)
- Inline configuration: ssh +test+ubuntu/24.04+m4+c2+d20+nest+priv@host
- Template-based defaults via create-config.yaml
Instance Management:
- Remove instances via /rm/ or /remove/ commands (requires root host user)
- Force removal with /rm-f/ or /remove-force/ to skip confirmation
- Automatic handling of ephemeral instance cleanup
- Explain login strings with /explain/ command for troubleshooting
Flexible Authentication:
- Public key authentication using host SSH keys (default)
- Password authentication support (--password-auth)
- Instance-based SSH key authentication (--instance-auth)
- Multi-factor authentication chains (--auth-methods)
- No-auth mode for development environments (--noauth)
- NixOS support (checks /etc/ssh/authorized_keys.d/<user>)
Multiple Remotes: Connect to any remote from incus remote list
Terminal Support: Full PTY (terminal) mode and remote command execution
File Transfer: Complete SCP and SFTP support with integrated SFTP server
Port Forwarding:
- Local forwarding (ssh -L)
- Reverse forwarding (ssh -R)
- Dynamic forwarding (ssh -D)
SSH Agent Forwarding: Seamlessly forward your SSH agent into instance sessions
Process Models:
- Master process mode: Maintains SSH connections after service restart
- Daemon mode: Single process with multiple threads for resource-constrained systems
Incus Shell: Manage Incus over SSH
Terminal Session Management:
- Persistent sessions with % prefix (survives SSH disconnections)
- Terminal multiplexer support (tmux or screen)
- Built-in tmux binary deployment for instances without tmux
- Automatic package installation for missing terminal multiplexers
System Integration:
- Cross-platform package management (Debian, RHEL, Alpine)
- Automatic OS detection and package manager selection
- Instance configuration templates (create-config.yaml)
- Non-root operation support (auto-detects process owner)
Compatibility:
- Built using Incus 6.20 API
- Works with Incus inside Lima and Colima
- Tested with Jetbrains Gateway, VSCode, Cursor and other IDEs
- Full Ansible support

Enterprise Features

Advanced authentication options (SSH keys, passwords, JWT, OpenID, OAuth 2.0, LDAP, etc.)
Web browser-based terminal access to instance shells
24/7 technical support with prioritized feature development

Screenshots

Instance Management Dashboard

Web-Based Terminal

Persistent Terminal Sessions (tmux)

Instance Creation Wizard - Step 1

Instance Creation Wizard - Step 2: Configuration

Instance Creation Wizard - Step 2: Disk Devices

Instance Creation Wizard - Step 2: Proxy Devices

Instance Creation Wizard - Step 3: Cloud-Init

Instance Creation Wizard - Step 4: Review & Summary

Instance Details Drawer

Installation

Download the latest package from the Releases page and install:

Debian-based Systems (Ubuntu, Debian)

apt-get install -f ./ssh2incus_0.8-0_amd64.deb

RPM-based Systems (RHEL, Fedora, CentOS, AlmaLinux, Rocky Linux)

dnf install ./ssh2incus-0.8-0.x86_64.rpm

Service Management

Start and enable the service:

systemctl enable ssh2incus.service
systemctl start ssh2incus.service

Monitor logs:

journalctl -f -u ssh2incus.service

Web Console Security (Reverse Proxy)

Recommendation: For production deployments, always run the web console behind an SSL-terminated reverse proxy server to ensure encrypted communication and implement additional security controls.

The web console listens on localhost:2280 by default. For external access, configure a reverse proxy with SSL/TLS termination:

Caddy Example

https://ssh2incus.mycompany.com {
    reverse_proxy localhost:2280
}

Nginx Example

server {
    listen 443 ssl http2;
    server_name ssh2incus.mycompany.com;

    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;

    location / {
        proxy_pass http://localhost:2280;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Apache Example

<VirtualHost *:443>
    ServerName ssh2incus.mycompany.com

    SSLEngine on
    SSLCertificateFile /path/to/certificate.crt
    SSLCertificateKeyFile /path/to/private.key

    ProxyPreserveHost On
    ProxyPass / http://localhost:2280/ upgrade=websocket connection=upgrade
    ProxyPassReverse / http://localhost:2280/
    RequestHeader set X-Forwarded-Proto "https"
    RequestHeader set X-Forwarded-Host "ssh2incus.mycompany.com"
</VirtualHost>

Connection Guide

Connection Format

To establish an SSH connection to an instance running on Incus host, run:

ssh -p 2222 [%][remote:][instance-user@]instance-name[.project-name][~host-user]@incus-host

For creating new instances on-demand (can be enabled using --allow-create flag), use:

ssh -p 2222 [+|~][remote:]instance-name[.project-name][+%profile1][+%profile2][+image][+memory][+cpu][+disk][+options][~host-user]@incus-host

Where:

instance-name: Name of an instance (required)
remote: Remote name from incus remote list (optional, defaults to either current remote or remote set via -r flag)
instance-user: User in the Incus instance (optional, defaults to root)
project-name: Incus project name (optional, defaults to default)
host-user: User on the Incus host (optional, defaults to root)
incus-host: Hostname or IP address of the Incus host where ssh2incus is running (required)

Special Prefixes:

%: Use persistent terminal session (tmux/screen) - reconnects to existing session if available
+: Create new persistent instance if it doesn't exist
~: Create new ephemeral instance (deleted on poweroff) if it doesn't exist

Instance Creation Options (when using + or ~):

%profile: Apply configuration profile (e.g., %web-server, %database)
image: Container/VM image (e.g., ubuntu/24.04, alpine/edge)
mN: Memory in GiB (e.g., m2 for 2GB, m4 for 4GB)
cN: CPU cores (e.g., c2 for 2 cores, c4 for 4 cores)
dN: Disk size in GiB (e.g., d10 for 10GB, d0 for unlimited)
nest or n: Enable nested virtualization
priv or p: Enable privileged container
vm or v: Create VM instead of container

Note: The login string parsing has been significantly improved in v0.8 with enhanced error handling, better validation, and comprehensive test coverage. The parser now handles complex scenarios more reliably while maintaining full backward compatibility with existing login string formats.

Connection Examples

Basic Connection

Connect to existing instance ubuntu as root:

ssh -p 2222 ubuntu@1.2.3.4

Specify Host User

Connect to instance ubuntu as root using admin on the host:

ssh -p 2222 ubuntu~admin@1.2.3.4

Specify Instance User

Connect to instance ubuntu as user ubuntu using host user admin:

ssh -p 2222 ubuntu@ubuntu~admin@1.2.3.4

Specify Project

Connect to instance ubuntu in project1 as user ubuntu:

ssh -p 2222 ubuntu@ubuntu.project1@1.2.3.4

Ssh2incus

Install / Use

README