Build an app
Turn any repository into a Cube app with a cube.json, or start one from scratch.
Any repository becomes a Cube app once it has a cube.json at its root. The app is a small web
server, or a folder of web pages, that Cube runs on your machine and shows in a tile.
Start a new app
In Market, choose Create new app and give it a name. Cube creates a repository on your
machine with a small starter app in it (a cube.json, a server.mjs with no dependencies, and a
README), runs it, and opens your default agent there to build it with you.
Ask the agent for what you want. The README in the new repository explains the rules below, so agents know how to build a Cube app without anything else from you. After changing the server, Restart the app from Manage app to see it.
Run a repository as an app
If one of your repositories already has a cube.json, right-click it in
Studio and choose Run as app. Cube installs it from your repository, so the app
runs your code as it is on disk.
To share an app, push it to a public GitHub repository. Anyone can install it with Add app from repo.
cube.json
cube.json sits at the root of the repository:
{
"name": "Control Panel",
"description": "Resources, CI, terminals and security for your Cube",
"icon": "web/icon.svg",
"platforms": ["linux"],
"install": "./install.sh",
"start": "./control-panel -addr 127.0.0.1:$PORT"
}| Field | Required | What it does |
|---|---|---|
name | Yes | The app's name in Cube, 1 to 64 characters. |
start | No | The command that runs the app's server, from the app's folder. Leave it out for an app that's only web pages: Cube serves the files itself. |
install | No | A command to run after the app is downloaded and after each update, before start, such as npm install. Stopped after 30 minutes. |
root | No | For an app without start: the folder to serve, relative to the repository. Defaults to the root. |
description | No | One line about the app, up to 200 characters. |
icon | No | A relative path to an .svg or .png in the repository, up to 256 KB. |
platforms | No | "linux", "darwin" or both. Leave it out for both. |
Cube ignores any other field. The smallest app is a name and a command:
{ "name": "Hello", "start": "node server.mjs" }The rules
- Listen on
$PORT. Cube picks a free port and passes it in thePORTenvironment variable. Serve on127.0.0.1:$PORT. - Stay in the foreground.
startmust keep running; don't send the server to the background. Cube treats the app as Running once the port answers, and as failed if it doesn't within a minute. A crashing app is restarted, and stopped after five crashes in two minutes. - Keep your data outside the app's folder. An update replaces the folder. Use a place such as
~/.config/<your-app>. - Runs as you. The app runs as you on the machine, with access to its files, its tools and the agents you've signed in to. Cube gives it no other API.
- Shown in a frame. Cube shows the app in a frame inside its window. Links that open a new tab
open in your browser. Paths that start with
/__cube/are reserved for Cube.
If cube.json is refused
Cube checks cube.json when it installs or updates an app, and says what's wrong:
| Message | Fix |
|---|---|
| cube.json is not valid JSON. | Check for a trailing comma or a missing quote. |
| "name" is required and must be a non-empty string. | Add a name. |
| "root" cannot be combined with "start" | Use root only for an app that's just files. |
| "icon" must be a relative path inside the repository to an .svg or .png file. | Point icon at a file in the repository, without a leading /. |
| "platforms" must be a list containing only "linux" and "darwin". | Use ["linux"], ["darwin"] or leave it out. |
Change an installed app
Customise in Manage app copies an installed app into your repositories, so you and your agents can change it in Studio. The app then runs from that copy, and Cube stops offering updates for it.
While you work on it, Studio shows the app's repository under a striped bar with Play, to open it as an app, and a button for a new terminal in the app's folder.