SSH

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

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

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	Unix user. Default: `"root"`

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