SSH

Connect to ssh.oblien.com using a temporary password tied to your account. The connection opens the workspace's native SSH shell and supports SFTP, SCP and port forwarding. You do not need a public workspace IP or a jump-host setup.

Connect from the dashboard

1. Open your running workspace's SSH tab.
2. Select Enable SSH on first use, or Get SSH connection if SSH is already enabled.
3. Copy the command into your terminal. Paste the 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 Workspace password and SSH Public Key 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 workspaces.

Get a connection

Request a connection for either your own workspace or a workspace shared with you. The workspace must be running, with SSH enabled. Runtime permission is required, including the workspace 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/:workspaceId

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": "access-ws_a1b2c3d4",
    "password": "<temporary-connection-password>",
    "host_key_fingerprint": "SHA256:<gateway-fingerprint>"
  }
}

Use the returned values, including the port and username. The access-… username routes your connection; inside the shell you are the native workspace 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 /workspace/:workspaceId/ssh

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

Example for a workspace 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
}

Status never returns a password. Once a workspace 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 /workspace/:workspaceId/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 workspace 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 /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 the native workspace account password. This is separate from the temporary account connection password returned by POST /access/ssh/:workspaceId. 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 /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

Response

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

Set key

Authorize a public key inside the workspace. 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',
});

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

Response

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

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