Remote desktop

Create your workspace from the image catalog, then open its Desktop tab when you need a graphical session. Desktop access starts off; there is no desktop choice in the dashboard's creation form. Ubuntu 24.04/26.04, Debian 13, Node.js 24 and macOS support this capability. The same tab and browser/VNC controls work across operating systems and application images.

Ubuntu 24.04/26.04 and Debian 13 offer Cinnamon in the Desktop panel: a modern desktop with Firefox, a file manager, terminal and text editor. Its prepared files are shared read-only, so adding it needs no package downloads. macOS already includes its graphical system; enabling desktop controls remote access.

Use the normal workspace resource settings to allocate CPU, RAM and writable storage. Each Linux desktop has a private home directory and browser/settings profile in the workspace's writable storage. Its Workspace shortcut opens /root, also available through the terminal, Files tab and Runtime API. The ordinary Linux memory snapshot and restore feature also applies.

Choose screen resolution when creating a desktop, from 640 × 480 to 3840 × 2160, with 1280 × 800 selected initially. Rendering uses workspace CPU and RAM; the current provider has no GPU or desktop audio transport.

API and SDK clients can also request desktop during creation using the same image name:

const workspace = await client.workspaces.create({
  image: 'oblien/ubuntu:26.04', // 24.04 works too
  config: { desktop: { enabled: true } },
});

Omit desktop or set enabled: false to keep the image's normal environment. Existing resource and wait_ready options work unchanged. The dashboard returns the ID immediately and displays creation progress; the SDK waits by default.

Open the workspace's Desktop tab, next to Files. It checks whether the image provides a desktop and presents both Open in browser and Connect with VNC. Browser and CLI connections use HTTPS/WSS. Native apps can also use Oblien’s managed SSH desktop tunnel, with the same desktop access switch.

Once desktop software is installed, create a desktop and select Open desktop. This enables the required access and opens the selected desktop in this tab. Images with a single console show Main desktop. Opening the tab itself starts no stream. You can also use Enable desktop to make access available before choosing a client. Both browser and VNC options are visible before enabling. No restart is needed. Turning desktop access off disconnects desktop clients while terminals, SSH, jobs and the OS keep running. The choice is saved in the private writable layer and survives restart.

Images without a desktop do not gain GUI packages or extra processes. For Mac workspaces, the terminal and file APIs still run inside macOS whether anyone connects to the desktop or not. See macOS workspaces.

Saved desktops

In Desktop, choose New desktop, enter a name, and choose a screen size before selecting Create desktop. The desktop starts in the background and opens when ready. Create separate desktops for development, browsing or other work. Up to 10 saved desktops are available per workspace, including stopped ones. Active desktops share the workspace’s CPU and memory allocation; larger screens and more applications need more resources.

Each card shows its name, resolution and state. Its menu offers desktop settings, VNC access, Stop and Delete. Names and Linux screen resolutions can change while the desktop is running; resizing keeps applications open. Delete works directly on running desktops, with no separate Stop step. All sessions use the same installed, shared desktop software. No additional package download or workspace restart is needed to create a session.

Desktops are separate working environments within one workspace, not separate security boundaries. Anyone with workspace runtime access can manage them and access the workspace’s files. Use separate workspaces for users or software that must be isolated from each other.

The current macOS provider has one console desktop. Its API reports mode: "console" and max_sessions: 1; it cannot create independent graphical desktops. You can rename or delete its Main desktop connection and add it again. Screen size for this console is set in macOS display settings. The per-session can_resize flag indicates whether API screen resizing is available. Linux providers report their own capabilities instead of the dashboard assuming support from the OS name. Existing Linux console desktops are kept when upgrading, alongside new saved sessions. Restart a workspace using an older runtime to receive the updated desktop API.

API and SDK

Enable Runtime API access first. All management requests use normal workspace credentials and require workspace.runtime permission. Mutations through the control API appear in workspace audit history.

Creation returns {success: true, session: {...}} with an opaque ds_… ID. Poll GET while state is starting, stopping or deleting; other states are running, stopped and failed. Connection readiness is available: true. Reuse the same idempotency_key and body when retrying creation to avoid a duplicate desktop. The session limit and conflicting operations return HTTP 409. Invalid sizes return 400. Virtual-desktop deletion is asynchronous: it returns success: true with a deleting session, then disappears from the list. A direct runtime DELETE returns 202 while cleanup proceeds. Deleting the main console returns 200. Omit resolution when adding back an OS console connection.

const vm = client.workspace(workspace.id);
const runtime = await vm.runtime(); // Enables Runtime API access if needed.
const { capabilities } = await vm.desktop.listSessions();
if (capabilities.can_create) {
  const { session } = await vm.desktop.createSession({
    name: 'Development',
    resolution: { width: 1920, height: 1080 },
    idempotency_key: 'development-desktop',
  });
  // Poll vm.desktop.getSession(session.id) until session.available is true.
  await runtime.desktop.enable();
  const viewer = runtime.desktop.url({ sessionId: session.id });
  // Open viewer privately; it carries your connection credential.
  const connection = await vm.desktop.sshConnection({ session_id: session.id });
}

Session methods are also available on runtime.desktop for direct runtime clients, using /desktop/sessions on workspace.oblien.com. The selected browser stream uses /desktop/sessions/{sessionId}/ws. Native VNC credentials are bound to the selected session; stop or deletion disconnects that session’s viewers. Disabling desktop access disconnects every desktop viewer without stopping apps.

Add desktop to an existing workspace

Open Desktop, choose Cinnamon, then select Add desktop. A running workspace shows Add desktop and restart because attaching the prepared files requires a restart. Running programs stop; your files and installed tools are kept. You can leave the page and return to preparation progress.

Desktop is available here only. Its internal storage does not appear in the Software library or your Disks list. Each workspace has a private browser profile, desktop preferences and writable files, while the installed programs are shared read-only. A change in one workspace cannot modify the shared source.

Prepared desktop requires at least 2 GiB RAM; 4 GiB is recommended for browser use. CPU, RAM and writable disk remain ordinary workspace resources. The shared desktop files do not use your private writable capacity. A stopped workspace stays stopped after adding desktop; start it when ready. Restore or discard saved execution before changing a hibernated workspace's disk layout.

Compatible app or custom images without a prepared layer offer Install desktop instead. This installs Cinnamon into that workspace's private storage, needs internet access, at least 2 GiB RAM and 3 GiB free writable disk, and can take several minutes. Other distributions need a compatible installer. An older runtime must be upgraded before installation.

For API clients, inspect GET /workspace/{id}/desktop/installation. Its choices field lists available prepared desktops. Add the selected desktop:

await client.workspace(workspace.id).desktop.install({
  desktop: 'cinnamon',
  restart: true, // Explicitly allow restarting a running workspace.
});
const preparation = await client.workspace(workspace.id).desktop.installation();

The corresponding request is POST /workspace/{id}/desktop/install with the same JSON body. A 202 response accepts background preparation. Poll installation status until its phase is ready or stopped with installed: true. While installing, stage describes progress. failed includes an error; fix the cause and retry. An explicit Stop cancels the preparer's automatic restart. The download-based installer may report restart_required; use the ordinary workspace restart to finish it.

After preparation, create a desktop, then open it or choose its Connect with VNC action. Disabling desktop access closes connections while leaving the installed desktop and workspace running.

Browser control

Connect replaces the connection choices with the desktop. Back closes that viewer and returns to the choices. Open in browser moves it to a separate window and closes the inline stream. Both use the same noVNC viewer and authenticated WebSocket connection, with keyboard, pointer input, fullscreen, scaling and Oblien's light/dark appearance.

The compact toolbar groups clipboard and display settings into menus. Streaming settings offers three modes that apply without reconnecting:

• Auto is the default. It adjusts compression when frame delivery slows or recovers, balancing detail and responsiveness. It also respects your browser's data-saving preference.
• Full quality preserves pixels using lossless formats and refreshes the entire screen. A slower connection may feel less responsive.
• Save bandwidth favors smaller updates. Image detail may be reduced when the workspace display supports it.

The current Mac display is already lossless, so Auto and Full quality can look identical. These modes do not increase screen resolution. Display settings includes Fit to window, Actual size with scrolling, and View only to temporarily stop keyboard and pointer input. Full screen and Open in browser are available as toolbar icons.

Local pointer is the default: your computer displays its own pointer immediately while movements still reach the workspace. Workspace pointer uses the cursor supplied by the display provider. A pointer drawn into the remote screen itself remains part of that image. Quality, sizing and pointer preferences are saved on your device; credentials and clipboard contents are not.

Browser streams close after 5 minutes without input, or 1 minute in a background window. Select Reconnect to resume. Desktop access stays enabled; the workspace, its applications and jobs keep running. Native VNC clients manage their own connection lifetime. Inline, separate-window and VNC access share one desktop access switch and the same authentication.

For a prepared Mac, the browser opens the account's graphical session through the native runtime before connecting. No password-field click or manual password entry is needed. Existing sessions are reused; another account or an explicit screen lock is preserved. Temporary automatic-login credentials are removed when preparation finishes. Headless tasks do not require a graphical login.

The first connection to a fresh Mac starts Finder, Dock, icon services and the account's other graphical processes. CPU can briefly reach the workspace limit during this login and the initial full-screen update. Some background work can continue after disconnecting. Reconnecting reuses the same session. The current Mac display uses software graphics, so resizing and rapidly changing content also consume CPU; desktop access does not add a GPU.

Copy text on your computer, focus the desktop application and use Paste or Ctrl+V / ⌘V. The Mac receives Unicode and multiline text through its native clipboard. Ctrl+C / ⌘C copies the selected desktop text back to your computer; Copy from desktop retrieves text already on the desktop clipboard. These actions transfer text only, up to 1 MiB. Files use the Files tab.

If browser permissions prevent automatic clipboard access, select Clipboard, paste into its text box and choose Send to desktop. Copying out has the same manual fallback. Clipboard access happens when you request it, without background monitoring. Ubuntu uses the desktop's standard VNC text clipboard; use Ctrl+Shift+V in its terminal. On Mac, before graphical login, only short text using the US keyboard can be typed; the native clipboard becomes available after login.

The iframe stays on workspace.oblien.com, isolated from the dashboard origin. The plain /desktop URL only serves the viewer shell and grants no workspace access. The viewer does not use a session cookie to authenticate the desktop. New dashboard links deliver the credential in a URL fragment, which is removed immediately; HTTP uses a Bearer header and the browser WebSocket authenticates in its handshake header. The viewer does not store tokens or clipboard text in browser storage. Only the Oblien dashboard can embed it. Older SDK links remain credential-bearing URLs and must not be logged or shared. Copying the cleaned address or refreshing it does not carry the connection credential; open Desktop from your workspace again.

HTTPS/WSS encrypts traffic to the Oblien gateway. TLS terminates there, followed by the private workspace network and private VNC provider. Disabling Runtime API access or rotating the runtime token disconnects all runtime sessions. Desktop disable closes desktop connections only. Viewing this way does not expose a public VNC port.

The runtime relays binary display data; the image's display provider (TigerVNC for Ubuntu, QEMU for Mac) renders/encodes it and noVNC decodes it in your browser. It does not install another web server or maintain a desktop stream when nobody is connected. Closing idle and duplicate viewers avoids their encoding and network cost. The Mac display still uses software graphics, so this does not provide GPU-accelerated video streaming.

Native VNC client

Prefer a native VNC client for longer sessions, desktop shortcuts and the client's own display controls. It can feel more responsive than the browser, depending on the client and network. Both use the same workspace display; native VNC does not add GPU acceleration or guarantee a faster stream.

Use an SDK/CLI build with desktop session support and sign in with your usual Oblien account:

npm install -g oblien
oblien login
oblien desktop enable WORKSPACE_ID
oblien desktop vnc WORKSPACE_ID --session DESKTOP_ID

Keep the command running and connect your VNC client to 127.0.0.1:5901, or open vnc://127.0.0.1:5901. Use --port 5902 for another local port. Ctrl+C closes the tunnel. Retrieve the Mac OS login password with oblien desktop credentials WORKSPACE_ID. Native VNC clipboard support depends on the image's VNC provider; use the browser's clipboard controls for Mac text transfer through QEMU.

The tunnel authenticates to the same WSS gateway as the browser. You do not need to publish a VNC port, configure a bastion, or create another workspace password. It listens only on your computer's loopback interface. The Mac account login is separate from the VNC transport, which the gateway authenticates.

Mobile and remote devices

Use a VNC app with built-in SSH tunneling. In the workspace’s Desktop tab, choose Connect with VNC from the desktop’s menu, then Get VNC connection. This enables desktop access if needed and displays the settings. Your phone connects directly to Oblien; no computer running the CLI is needed.

Choose SSH password authentication in the VNC app. The password is restricted to that selected desktop and expires after eight hours for the owner; its open connections close at expiry. Select Get new connection to reconnect afterward. The password is shown only in this dashboard view and is not saved in browser storage. Keep it private if you save it in your VNC app.

The SSH username and password above are desktop connection credentials. They grant no SSH shell, SFTP, terminal, file API or arbitrary port forwarding. You do not need to enable the workspace’s normal SSH service. The OS login screen uses a separate account password: select Show desktop login when the image provides one. This OS password may also be used by that account’s ordinary SSH login, so share it only when you intend to grant that account access.

Disabling desktop access closes connections and rejects new ones while disabled. Re-enabling permits unexpired connection passwords again. Rotating the Runtime API token permanently invalidates existing desktop passwords and closes their streams; turning Runtime API access off also disconnects them. Issuing a new desktop password does not revoke previously issued ones.

A client without built-in SSH tunneling can use a separate local SSH forwarding app, or the CLI tunnel on a computer. For an OpenSSH client, use the SSH username from the dashboard and enter the connection password at the password prompt:

ssh -N -L 5901:127.0.0.1:5900 [email protected]

Connect the local VNC app to 127.0.0.1:5901 while this command runs. Never put the password in the command itself. Mobile apps must keep their SSH forwarder active when switching apps; built-in forwarding avoids that extra app.

Transport, security and capacity

workspace.oblien.com continues to use standard HTTPS/WSS port 443, with no port suffix in its URL. ssh.oblien.com uses standard SSH port 22. The VNC port 5900 above is a destination inside the authenticated SSH tunnel; there is no public raw VNC listener. Changing the name to vnc.oblien.com alone would not make a VNC app understand HTTPS/WebSocket authentication.

The browser and CLI use WSS → workspace runtime → private display. Native apps use SSH → Oblien gateway → the same runtime desktop endpoint → private display. TLS or SSH encrypts the public hop; the gateway-to-runtime hop uses Oblien’s private network. This does not claim separate encryption on that internal hop. The gateway relays bytes without screen rendering or transcoding.

The gateway validates the current runtime credential and desktop switch, binds the connection to its assigned workspace, and limits concurrent streams. It uses bounded buffers and closes stalled streams. Gateway replicas can distribute connections without maintaining a ticket database; capacity still depends on bandwidth, CPU and connection limits. Functional and isolation checks do not establish a large-scale concurrency benchmark.

Native VNC clipboard support depends on the display provider. For Mac text copy and paste across devices, use the browser’s native clipboard controls. A VNC client may still need the OS login; the browser prepares supported Mac sessions automatically.

API and SDK

Optionally enable access when creating a supported image:

{ "config": { "desktop": { "enabled": true } } }

Use the live Runtime API to change access later, with the same authentication as files and terminals:

const runtime = await client.workspaces.runtime(workspaceId);
console.log(await runtime.desktop.status());
await runtime.desktop.enable();
const viewerUrl = runtime.desktop.url(); // Private URL; do not log it.
const tunnel = await runtime.desktop.tunnel({ port: 5901 }); // Node.js only
// Connect a VNC client to tunnel.url.
await tunnel.close();
await runtime.desktop.disable();

To issue native SSH/VNC settings through the authenticated control API:

POST /workspace/WORKSPACE_ID/desktop/ssh

const connection = await client.workspaces.desktop.sshConnection(workspaceId);
// Enter connection.ssh and connection.vnc in the VNC app; keep the password private.

The same operation is available as oblien desktop ssh WORKSPACE_ID and client.workspace(workspaceId).desktop.sshConnection(). Desktop access must already be enabled. The normal workspace ownership, namespace and scoped-token checks apply.

The methods are included in the downloadable 2.3.2 package above. Install it without -g to use it in an application.

Status returns supported, enabled, available, credentials and supported transports. available means the private display provider can be reached. A ready workspace can still be starting its display; the Desktop tab checks it automatically while the display is preparing.

Desktop belongs to the image, so runtime.forTarget(...) changes the execution target without selecting another desktop. Supporting images use the same API and supply their own private display provider.