Console API reference for VM applications

Use the following reference to understand the console WebSocket endpoint, error codes, and guest requirements for VM application serial console access.

Application console WebSocket endpoint
Copy link

The VM application console uses a WebSocket connection served by the flightctl-api service. This endpoint is distinct from the device console endpoint (/ws/v1/devices/{name}/console), which provides access to the host operating system shell on the device.

Table 1. Endpoint specification
Property Value

Endpoint

GET /ws/v1/devices/{name}/applications/{appname}/console

Protocol

WebSocket

Service

flightctl-api

Path parameter: name

The device name.

Path parameter: appname

The VM application name.

Query parameter: consoleType

The console type: serial or vnc.

Query parameter: force

When set, takes over an existing console session of the same type for this application.

RBAC

Requires get permission on the devices/applications/console resource.

Error codes
Copy link

Table 2. Console error codes and resolutions
HTTP code Meaning Resolution

400

Missing session metadata.

Ensure the metadata query parameter is present and contains valid JSON session metadata.

403

Access denied. The user does not have get permission on the devices/applications/console resource.

Request the required permission from your administrator.

404

The device or application was not found.

Verify the device name and application name.

409

Another console session of the same type is already active for this application, or the device is in a state that prevents console access.

To take over an existing session, use the force query parameter. The original session is disconnected when a new session takes over.

504

Protocol negotiation with the device agent timed out after 60 seconds.

The device agent might be unreachable or the VM might still be starting. Wait and retry.

Guest kernel requirement
Copy link

The VM guest kernel must include console=ttyS0 in the kernel command line for serial console output. Without this parameter, the serial console session connects but does not display any output.

Most Linux distribution cloud images include this parameter by default. If your guest image does not, add console=ttyS0 to the kernel command line in the GRUB configuration or through a cloud-init bootcmd directive.

By default, Windows VM guests do not output to the serial console. To enable it, configure EMS/SAC in the guest (bcdedit /ems {current} on and bcdedit /emssettings EMSPORT:1 EMSBAUDRATE:115200). For Windows VMs without EMS/SAC, use RDP via port publishing for remote access.