SSH
Connect to ssh.oblien.com using a temporary password tied to your account.
The connection opens the VM's native SSH shell and supports SFTP, SCP
and port forwarding. You do not need a public VM IP or a jump-host setup.
Connect from the dashboard
- Open your running VM's SSH tab.
- Choose Oblien Gateway, then Enable SSH and connect on first use or Get SSH connection if SSH is already enabled.
- Copy the command into your terminal. Paste the Gateway connection password when prompted, and verify the displayed gateway fingerprint on first connection.
The same host, port, username and password work in desktop and mobile SSH/SFTP clients. Only the owner can enable or disable SSH. Collaborators with runtime access can get their own connection after the owner enables it.
The VM password and SSH keys cards manage native account
credentials. Those settings are separate from your temporary connection password.
Linux shells use root. Native macOS shells use oblien; run sudo -i for root.
See macOS VMs.
Direct IPv6
When public IPv6 is enabled for a Linux VM, its owner can choose Direct IPv6
in the SSH tab. SSH must be enabled and the VM firewall must allow public TCP
port 22. The Allow SSH on IPv6 action asks for confirmation and preserves
all other firewall rules. You can also manage this in Network.
Direct SSH uses the VM login account and its SSH key or password. It needs IPv6 connectivity on your computer. Oblien Gateway continues to work without a public VM port and uses its separate, temporary account credential. Keep public ports closed if you only need the gateway.
ssh -6 -i './my_key' 'root@2001:db8::1234'
scp -i './my_key' './file.txt' 'root@[2001:db8::1234]:~/file.txt'
sftp -i './my_key' 'root@[2001:db8::1234]'Use your actual address from the dashboard. IPv6 addresses in SCP and SFTP commands are enclosed in brackets and quoted for the shell. The Transfer files section generates upload, download and folder commands for your selected connection.
Generate or add an SSH key
In SSH keys, paste an existing public key, choose its .pub file, or select
Generate key pair. Generation uses your browser's Web Crypto Ed25519 implementation.
The private key stays in your browser and is never sent to Oblien.
Download the private key before selecting Add public key. The download is an unencrypted OpenSSH private key; keep it private, restrict its file permissions, and optionally add a passphrase locally:
chmod 600 ./oblien-VM_ID_ed25519
ssh-keygen -p -f ./oblien-VM_ID_ed25519Use the actual downloaded filename in these commands and in Private key path. The download is available only while this page remains open. Existing authorized keys are preserved; adding the same public key again does not create a duplicate. The dashboard accepts public keys only—never paste or upload a private key.
Get a connection
Request a connection for either your own VM or a VM shared with you. The VM must be running, with SSH enabled. Runtime permission is required, including the VM scope when using a restricted API key.
const id = 'ws_a1b2c3d4';
const status = await ws.ssh.status(id);
if (!status.ssh_enabled) await ws.ssh.enable(id); // Owner only
const connection = await ws.ssh.connection(id);
const { host, port, username } = connection.ssh;
console.log(`ssh ${port === 22 ? '' : `-p ${port} `}${username}@${host}`);
// Pass connection.ssh.password privately to your SSH client.POST /access/ssh/:vmIdNo request body is needed.
curl -X POST "https://api.oblien.com/access/ssh/ws_a1b2c3d4" \
-H "X-Client-ID: $OBLIEN_CLIENT_ID" \
-H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"Response
{
"success": true,
"delegated": true,
"expires_at": "2026-10-07T12:00:00.000Z",
"ssh": {
"host": "ssh.oblien.com",
"port": 22,
"username": "ws_a1b2c3d4",
"password": "<temporary-connection-password>",
"host_key_fingerprint": "SHA256:<gateway-fingerprint>"
}
}Use the returned values, including the port and username. The VM ID
username routes your connection; inside the shell you are the native VM
user. delegated: true identifies an account-authorized connection and also
applies to owners.
The password expires at expires_at, within one hour. Request a new connection
when needed. Keep it private: it grants your runtime permissions. Access is
checked while connected; expiry, revocation, disabling SSH or signing out ends
access. Verify the gateway fingerprint instead of disabling host-key checks.
Status
GET /vms/:vmId/sshconst status = await ws.ssh.status('ws_a1b2c3d4');
console.log(status.ssh_enabled);Example for a VM that requires account-authenticated SSH:
{
"success": true,
"ssh_enabled": true,
"ssh_id": "abc123",
"ssh_password_changed": false,
"auth_methods": ["password", "publickey"],
"password_auth_enabled": true,
"password_affects_desktop": false,
"requires_account_access": true,
"connection": null
}| Field | Type | Description |
|---|---|---|
ssh_enabled | boolean | Whether VM SSH is enabled |
ssh_id | string or null | Internal SSH routing alias; use the username returned by the connection endpoint |
ssh_password_changed | boolean | Whether the native account password has been changed |
ssh_key_set | boolean | Whether an owner-managed public key has been installed |
auth_methods | string[] | Native VM SSH methods, separate from gateway authentication |
password_auth_enabled | boolean | Whether native password login is configured |
password_affects_desktop | boolean | Whether changing the native password also changes the desktop login |
requires_account_access | boolean | Whether older guest-credential jump connections are blocked |
connection | object or null | Legacy connection fields for older, unshared clients; use POST /access/ssh/:vmId for the current connection flow |
Status never returns a password. Once a VM has been shared, its old
jump connection stays blocked even if sharing is later removed. Both status
and enable return connection: null in this case.
Enable
POST /vms/:vmId/ssh/enableawait ws.ssh.enable('ws_a1b2c3d4');
const connection = await ws.ssh.connection('ws_a1b2c3d4');Only the owner can enable SSH. This configures native SSH and registers its
route. The enable result includes ssh_enabled, ssh_id and
requires_account_access, using the same connection policy as status.
Linux enable also returns an initial native ssh_password. On macOS it returns
the existing VM account password without changing the desktop login.
This native password is not the password for the account connection; use
connection.ssh.password from the separate connection request. You can keep
native password and public key settings unchanged for the account flow.
Disable
Disable SSH. Stops the SSH daemon and removes access.
await ws.ssh.disable('ws_a1b2c3d4');POST /vms/:vmId/ssh/disablecurl -X POST "https://api.oblien.com/vms/ws_a1b2c3d4/ssh/disable" \
-H "X-Client-ID: $OBLIEN_CLIENT_ID" \
-H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"Response
{
"success": true,
"ssh_enabled": false
}Set password
Set the native VM account password. This is separate from the temporary
account connection password returned by POST /access/ssh/:vmId. On macOS
it also changes the desktop login password. Only the owner can change it.
await ws.ssh.setPassword('ws_a1b2c3d4', {
password: 'my-secure-password-123',
});POST /vms/:vmId/ssh/password{
"password": "my-secure-password-123",
"user": "root"
}curl -X POST "https://api.oblien.com/vms/ws_a1b2c3d4/ssh/password" \
-H "X-Client-ID: $OBLIEN_CLIENT_ID" \
-H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{ "password": "my-secure-password-123" }'Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
password | string | Yes | New password (minimum 6 characters) |
user | string | No | Login account: defaults to root on Linux, oblien on native macOS |
Response
{
"success": true,
"user": "root",
"password_set": true
}Set key
Authorize a public key inside the VM. This is optional and owner-only; the account connection uses its temporary password and does not require your public key. Adding a key does not bypass the gateway account-access check.
await ws.ssh.setKey('ws_a1b2c3d4', {
public_key: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@machine',
append: true,
});POST /vms/:vmId/ssh/key{
"public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@machine",
"append": true,
"user": "root"
}curl -X POST "https://api.oblien.com/vms/ws_a1b2c3d4/ssh/key" \
-H "X-Client-ID: $OBLIEN_CLIENT_ID" \
-H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{ "public_key": "ssh-ed25519 AAAAC3...", "append": true }'Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
public_key | string | Yes | SSH public key (written to ~/.ssh/authorized_keys) |
append | boolean | No | true preserves existing keys and deduplicates by key material. Omitted or false retains replacement behavior: replace all keys on Linux, or only Oblien-managed keys on macOS. |
user | string | No | Login account: defaults to root on Linux, oblien on native macOS |
Response
{
"success": true,
"user": "root",
"key_set": true,
"key_added": true
}key_added: true is returned when append: true was requested. The dashboard always uses append mode.
Connection examples
Substitute the username and port returned by the connection endpoint. Enter its
temporary password when prompted. These examples use port 22:
# Interactive shell
ssh [email protected]
# SFTP
sftp [email protected]
# Upload to the native user's home directory
scp ./file.txt [email protected]:~/
# Download a file
scp [email protected]:~/file.txt ./
# Forward local port 8080 to a service on vm port 3000
ssh -N -L 8080:127.0.0.1:3000 [email protected]In a graphical SSH client, enter the returned host, username and connection
password. Use port 22 unless the connection response specifies another port.