Quickstart
Getting started with CheerpX
1. Include CheerpX on your page
CheerpX’s API is still in the works, so we are not tagging releases yet. All nightly builds are immutable so you can trust that the URL above will not break.
2. Create an application instance
CheerpX is exposed in a global object called CheerpXApp
. To create an instance, call the create
method.
The example below uses WebVM’s debian_large
image, but you can also create your own images.
3. Enable cross-origin isolation
CheerpX requires SharedArrayBuffer, which requires the site to be cross-origin isolated. To enable cross-origin isolation, serve over HTTPS and set the following headers:
During development, you don’t need to set these headers if you’re using localhost
as the origin. However, you’ll need to set them and make sure you serve over HTTPS when you deploy.
Cross-origin isolation may break existing site functionalityCross-origin isolation is a security feature that you probably want to enable anyway, however it may impact your site in unexpected ways. For example, if you’re embedding third-party iframes or opening cross-origin popup windows, you may need to make changes to your site to make them work. Test carefully!
4. Attach a console
Use the setConsole
method to use an HTML element as a console.
5. Run an executable
Let’s run
bash!
Now you can interact with the console to run commands. 🎉