Cockpit can be embedded in other web applications either as a whole or specific Cockpit components can be integrated. Due to frame security policy restrictions, this only works if Cockpit and the web application have the same origin; this is commonly achieved by running both from a common reverse proxy.

Embedding the Cockpit Interface

Cockpit can be embedded into a larger web page as a frame. To embed the entire Cockpit Window use the URI: https://server.example.com:9090/

<html>
  <head>
    <title>Embedded Cockpit</title>
  </head>
  <body>
    This is Cockpit.
    <br/>
    <iframe width="800px" height="600px"
            src="https://server.example.com:9090/"/>
  </body>
</html>

Integrating Cockpit Components into Web Applications

Instead of embedding the entirety of Cockpit, you can integrate specific components. Only those components explicitly documented as API should be integrated. Other components can and will change regularly.

The component will load from the server in question and a WebSocket connection will be established with the server to relay the component’s message stream.

Cockpit components are HTML files contained in packages. These can be placed in an iframe or web browser window. Each documented and stable component has a well-known URL and these are documented in the API reference. Each component URL begins with the string /cockpit/@localhost/ followed a package name, and then the component itself.

For example the terminal.html in the system package, has this URL: /cockpit/@localhost/system/terminal.html

<html>
  <head>
    <title>Embedded Terminal</title>
  </head>
  <body>
    This is a terminal.
    <br/>
    <iframe width="800px" height="600px"
      src="https://server.example.com:9090/cockpit/@localhost/system/terminal.html"/>
  </body>
</html>

Deep Integration

Most often simple integration will be used to bring Cockpit components into web applications. However it is also possible to do deep integration for embedders who wish to perform non-standard authentication with the server, and relay the component’s message stream to the server themselves.

Warning

Deep integration capability is in heavy flux and is not yet documented.

Pinging Cockpit

When embedding Cockpit or integrating Cockpit components, it may be necessary to check whether Cockpit is available on a server before proceeding.

To do this perform a /ping request to Cockpit. This is a simple HTTP GET request. It returns the following:

GET: https://server.example.com:9090/ping
200 OK: { "service": "cockpit" }

The /ping request allows Cross Origin Resource Sharing headers and as such can be performed from Javascript code with any origin. The request can also be made via plain HTTP without SSL. It is by design that no further information is present in the response.

A complete example of using /ping is available in the Cockpit sources in the /examples/ping-server/ directory.