SSH

Enable SSH access to your workspace for direct shell access from any terminal. Connections route through Oblien's SSH gateway.

Native macOS uses the same endpoints and supports both passwords and public keys. Its login account is oblien; sudo -i opens a root shell. Changing the Mac SSH password also changes its desktop login and updates the desktop viewer's saved credential. See macOS workspaces.

Status

Check current SSH configuration.

const ssh = await ws.ssh.status('ws_a1b2c3d4');

if (ssh.ssh_enabled) {
  console.log(ssh.connection.command);
  // "ssh root@abc123 -J root@ssh.oblien.com"
}

GET /workspace/:workspaceId/ssh

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/ssh" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response

{
  "success": true,
  "ssh_enabled": true,
  "ssh_id": "abc123",
  "ssh_password_changed": false,
  "connection": {
    "user": "root",
    "host": "abc123",
    "bastion": "ssh.oblien.com",
    "command": "ssh root@abc123 -J root@ssh.oblien.com",
    "scp_upload": "scp -J root@ssh.oblien.com file.txt root@abc123:/path/",
    "scp_download": "scp -J root@ssh.oblien.com root@abc123:/path/file.txt ."
  }
}

Response fields

Field	Type	Description
`ssh_enabled`	`boolean`	Whether SSH is currently active
`ssh_id`	`string`	Unique SSH hostname for this workspace
`ssh_password_changed`	`boolean`	Whether the default password has been changed
`auth_methods`	`string[]`	Supported SSH methods: `password`, `publickey`
`password_auth_enabled`	`boolean`	Whether password login is configured; setting a password activates it for an existing key-only Mac
`password_affects_desktop`	`boolean`	Whether SSH shares the graphical desktop account password
`connection.command`	`string`	Ready-to-use SSH command
`connection.scp_upload`	`string`	SCP upload command template
`connection.scp_download`	`string`	SCP download command template

Enable

Enable SSH on the workspace. This starts SSH access, opens port 22, and generates a one-time password.

On macOS, enable returns the current workspace account password instead of changing an existing desktop password. Status never returns a password.

const result = await ws.ssh.enable('ws_a1b2c3d4');

console.log(result.ssh_password);      // "xK9mP2..." (shown once!)
console.log(result.connection.command); // "ssh root@abc123 -J root@ssh.oblien.com"

POST /workspace/:workspaceId/ssh/enable

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/ssh/enable" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response

{
  "success": true,
  "ssh_enabled": true,
  "ssh_id": "abc123",
  "ssh_password": "xK9mP2qR7vL4",
  "connection": {
    "user": "root",
    "host": "abc123",
    "bastion": "ssh.oblien.com",
    "command": "ssh root@abc123 -J root@ssh.oblien.com",
    "scp_upload": "scp -J root@ssh.oblien.com file.txt root@abc123:/path/",
    "scp_download": "scp -J root@ssh.oblien.com root@abc123:/path/file.txt ."
  }
}

The ssh_password is shown only once when SSH is enabled. Save it immediately or set a custom password afterward.

Disable

Disable SSH. Stops the SSH daemon and removes access.

await ws.ssh.disable('ws_a1b2c3d4');

POST /workspace/:workspaceId/ssh/disable

curl -X POST "https://api.oblien.com/workspace/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 a custom SSH password for a user.

await ws.ssh.setPassword('ws_a1b2c3d4', {
  password: 'my-secure-password-123',
  user: 'root',
});

POST /workspace/:workspaceId/ssh/password

{
  "password": "my-secure-password-123",
  "user": "root"
}

curl -X POST "https://api.oblien.com/workspace/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

Add an SSH public key for passwordless authentication.

await ws.ssh.setKey('ws_a1b2c3d4', {
  public_key: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@machine',
  user: 'root',
});

POST /workspace/:workspaceId/ssh/key

{
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@machine",
  "user": "root"
}

curl -X POST "https://api.oblien.com/workspace/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..." }'

Parameters

Parameter	Type	Required	Description
`public_key`	`string`	Yes	SSH public key (written to `~/.ssh/authorized_keys`)
`user`	`string`	No	Unix user. Default: `"root"`

Response

{
  "success": true,
  "user": "root",
  "key_set": true
}

Connection examples

Once SSH is enabled, connect from your local terminal:

# Interactive shell
ssh root@abc123 -J root@ssh.oblien.com

# Upload a file
scp -J root@ssh.oblien.com ./deploy.sh root@abc123:/app/

# Download a file
scp -J root@ssh.oblien.com root@abc123:/app/logs/app.log ./

# Run a remote command
ssh root@abc123 -J root@ssh.oblien.com 'cat /etc/os-release'

The -J flag routes the connection through Oblien's SSH gateway (ssh.oblien.com), so no public IP or port forwarding is needed on the workspace.

On this page