Console Access

This feature provides out-of-band access to Civo compute instances, allowing users to access a shell or desktop environment as if they were physically in front of the instance's monitor.

This functionality can be accessed by following three separate steps:

1. Console Session Initialisation
2. JWT Exchange (see link: JSON Web Token Exchange)
3. Console Access

The above phases are not explicit if you use a client like the Civo CLI or the Civo Dashboard, as they wrap the above steps. Read on to learn about each one of the phases.

Console session initialization

Out-of-band console sessions are started by sending an authorised PUT request to https://api.civo.com/v2/instances/:id/vnc.

Request

You can specify these query parameters with your request:

Response

The response will contain a uri that you will need to visit to access the out-of-band console, and the duration of the session.

{
  "uri": string,
  "duration": string
}

cURL

curl -H "Authorization: Bearer {jwt/apikey}"
     -X PUT 'https://api.civo.com/v2/instances/{instance_id}/vnc?duration={duration}&region={region}'
          

Console session access

Once you've obtained a URI by initializing a console session, you can visit that link to access the out-of-band console.

To do so, you will need a valid Civo JWT (JSON Web Token). Learn how to obtain one here.

Send it alongside your request as an Authorization header, or alternatively append it to the uri as a token query parameter.

Assuming you choose to append the obtained JWT as a query parameter, the resulting URL should have the following format:

https://vnc.{region}.civo.com/{instance_id}/vnc.html?path=/{instance_id}/websockify&token={jwt}

By visiting the resulting URL in your browser, you’ll get automatically authenticated and redirected to the noVNC connection page, allowing you to interact via the browser with the instance. This client webpage only supports one concurrent connection to the instance at any time. You can disconnect or close the browser tab if you wish to let other users interact with the instance using the web console.

Retrieve console session status

If you want to know if a Console session is already active for an instance, send an authorised GET request to https://api.civo.com/v2/instances/{uuid}/vnc.

Request

You must specify the following query parameter with your request:

Response

If a VNC session is active for the specified instance, you will receive a JSON response with HTTP status code 200, with the following details, where uri represents the console access URI and the expiration is the time at which the current session is set to end:

{
  "uri": string,
  "expiration": string
}

If there is no current console access session for the instance queried, the API will return HTTP status 404 Not Found.

cURL

curl -H "Authorization: Bearer {jwt/apikey}"
     'https://api.civo.com/v2/instances/{instance_id}/vnc?region={region}'
          

Stop a console session

To stop an existing console session, and prevent any subsequent access until a new session is created, send an authorised DELETE request to https://api.civo.com/v2/instances/{uuid}/vnc.

Request

You must specify the following query parameter with your request:

Response

If a VNC session is active for the specified instance, you will receive a JSON response with HTTP status code 200 OK and any access using the console URI will be prevented.

If there is no active console access session for the instance, the API will return HTTP status 404 Not Found.

cURL

curl -H "Authorization: Bearer {jwt/apikey}"
    -X DELETE 'https://api.civo.com/v2/instances/{instance_id}/vnc?region={region}'