API Reference

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

  1. Open your running VM's SSH tab.
  2. Choose Oblien Gateway, then Enable SSH and connect on first use or Get SSH connection if SSH is already enabled.
  3. 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_ed25519

Use 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/:vmId

No 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/ssh
const 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
}
FieldTypeDescription
ssh_enabledbooleanWhether VM SSH is enabled
ssh_idstring or nullInternal SSH routing alias; use the username returned by the connection endpoint
ssh_password_changedbooleanWhether the native account password has been changed
ssh_key_setbooleanWhether an owner-managed public key has been installed
auth_methodsstring[]Native VM SSH methods, separate from gateway authentication
password_auth_enabledbooleanWhether native password login is configured
password_affects_desktopbooleanWhether changing the native password also changes the desktop login
requires_account_accessbooleanWhether older guest-credential jump connections are blocked
connectionobject or nullLegacy 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/enable
await 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/disable
curl -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

ParameterTypeRequiredDescription
passwordstringYesNew password (minimum 6 characters)
userstringNoLogin 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

ParameterTypeRequiredDescription
public_keystringYesSSH public key (written to ~/.ssh/authorized_keys)
appendbooleanNotrue 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.
userstringNoLogin 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.