Managed Applications

Applications installed in a project from the catalogue, each made of the project's own Cube resources (apps, Volumes, secrets and buckets), changed through its installation alone and billed in Cube's meters. Not open to accounts yet.

Trang này chưa được dịch sang Tiếng Việt: đây là bản tiếng Anh.

Not open yet. Managed Applications are not open to accounts yet. These pages say how they work as they are built, ahead of their opening, and may change before then.

A Managed Application is an application your project installs from the catalogue: Rivet is the first. An installation of it is made of what your project already has: Cube apps for its services, Volumes for their disks, secrets for what it generates, and buckets for what it keeps in object storage. Each of them is labelled with the installation and changed through it alone, and you are billed for them as for any other, in Cube’s meters. An application has no price of its own.

When to use Managed Applications

An open-source service you would rather not run yourself: its versions, its settings and its disks are looked after, and it sleeps when nothing asks anything of it, as a Cube does.
One per environment, customer or agent: one call installs one, one call deletes it with everything it is made of.
To know what it costs before you install it: each application’s calculator says what a month of it comes to in Cube’s meters.

How it works

Choose. GET /v1/catalogue lists the applications; GET /v1/catalogue/{app} shows one: its versions, the parameters an installation takes (a JSON Schema), the outputs it gives, and what a month of it comes to in Cube’s meters at its calculator’s defaults.
Install. POST /v1/installations with the application’s name and its parameters makes every part, waits until its apps are up and the application has taken them (150 seconds at the most), and answers with its outputs: its address, and what to reach it with.
Use. Your apps and sandboxes reach it at its address, or on the project’s private network at its apps’ names.
Delete. DELETE /v1/installations/{id} deletes every part: its apps, its Volumes and what they hold, its secrets, its buckets and what they hold.

POST /v1/installations
{"app": "rivet", "parameters": {"disk_gib": 20}}

The calls

Call	What it does
`GET /v1/catalogue`, `GET /v1/catalogue/{app}`	The catalogue’s applications, each at its newest version; one, at its newest version or the one `?version=` names, with the definition it was published as.
`POST /v1/installations`	Installs an application (201); or answers the installation the same create made (200).
`GET /v1/installations`, `GET /v1/installations/{id}`	The project’s installations, the newest first (`?app=` keeps those of one application); one, by its id (`ins-…`) or its name.
`PATCH /v1/installations/{id}`	Changes its version or its parameters.
`DELETE /v1/installations/{id}`	Deletes it, with everything it is made of.
`/v1/managed/{app}/…`	An application’s own API, where it has one, answered by the platform for it (Rivet’s).

Installing, changing and deleting take a key with the write scope; reading, read. The console has them too: Managed Applications, under Applications, lists the project’s installations and the catalogue, installs an application from a form made of its parameters, and shows and deletes an installation. So do the CLI (glac install rivet), the SDKs and the MCP server.

Installing

Every field but app may be left out:

Field	What it is
`app`	The application’s name in the catalogue.
`name`	The installation’s name in the project: up to 24 lower-case letters, digits and hyphens, a letter first, no hyphen last or two in a row. The application’s name unless you say. Its apps are named after it, `<name>-<service>`, and a name an app of the project has is refused.
`version`	A version of the application; its newest unless you say. One that was withdrawn is refused (409 `version_withdrawn`).
`region`	`na`, `eu` or `ap`; the project’s home unless you say.
`parameters`	What the application’s parameters schema takes. Those you leave out are at their defaults; a value out of the schema is refused (400 `invalid_parameter`), its path in `param` (`parameters.size.vcpus`).
`requires`	For an application that requires another (a database, say): the installation of the project to use for it, by requirement, `{"db": "shop-db"}`. One you do not name is installed with it, as `<name>-<requirement>`, and goes with it.

The create makes every part and waits for its apps, and for the application itself where it has a part of its own to play once they are up (Rivet makes its default pool of runners: Rivet), 150 seconds at the most: it answers the installation ready, or installing where its first start goes on, then GET it until it is ready. A part that cannot be made fails the create, which takes apart what it made. A create is idempotent by name: one that names an installation of the project answers it (200) where it asks for what it is, and is refused (409 name_taken) where it asks for something else.

What an installation has

Field	What it is
`id`, `name`, `app`, `version`, `region`	`ins-…`; as it was made, or changed.
`status`	`installing`, `ready`, `updating`, `failed` (`failure` says why: its apps, Volumes and buckets are there until you delete it), `deleting`, `deleted`.
`parameters`	Every parameter: those you gave, and the rest at their defaults. A secret one is `null` to a key without the `admin` scope.
`outputs`, `secret_outputs`	What it gives you: its address, and what to reach it with. A secret one (named in `secret_outputs`) is in the create’s answer, and afterwards in what a key with the `admin` scope (or the console) reads; `null` to any other.
`apps`, `volumes`, `buckets`	What it is made of: its apps (Cube’s), by service; its Volumes (Drives), `<service>/<volume>`; its buckets, each with the objects and bytes it held when it was last measured (every five minutes) and its `ibk-…` id.
`requires`, `required_by`	The installations it requires, each bound to it (`bound`) or installed with it; the installation it was installed for, which it goes with.
`api`	The base of the application’s own API, where it has one.
`created_at`, `updated_at`, `deleted_at`	When.

What an installation is made of

Its apps and Drives are the project’s: GET /v1/apps and GET /v1/drives list them, with managed_by naming the installation ({"object": "installation", "id": "ins-…"}), and their logs, metrics and snapshots are read as any. Each app carries the installation in its metadata (installation_id, and installation_app, the application’s name). What it generates (an application’s admin token, its buckets’ keys) is a secret of the project’s, named INS_<ID>_<SERVICE>_<NAME>. Only the installation changes them: an update, a deploy, a rollback or a delete of its app, a rename, restore or delete of its Drive, a read-write mount of its Drive anywhere else, a delete or a change of its instance, and a change of its secret are refused (409 managed_by_installation).

Its buckets are kept in the platform’s own object store, in a bucket the platform keeps for the project, each under a prefix of its own (<installation id>/<bucket>/), with a key that reaches that prefix alone: an application is given its bucket’s address, its prefix and its key, and nothing else. A bucket is kept in the installation’s region where the platform’s object store is there, and otherwise in the first region it is in (North America, then Europe, then Asia-Pacific).

Keys held to an installation

A key made with installation (POST /v1/keys {"installation": "rivet", "scopes": ["read", "write"]}) reaches that installation alone: reading it, its apps and what is under them, its Drives, and its apps’ instances. Anything else is refused (403 installation_key_scope), and such a key never has the admin scope (400 invalid_field). It is revoked when the installation is deleted. Give one to a program that looks after an installation and should touch nothing else of the project.

What it costs

An installation is billed as what it is made of, at Cube’s prices: its apps’ instances by their CPU time and memory, its Volumes and its buckets as volume data, its traffic to the internet and its requests, its logs. What its buckets hold is measured every five minutes and booked hour by hour as volume data under each bucket’s ibk-… id. An application has no meter and no fee of its own.

GET /v1/usage?group_by=metadata.installation_id groups its instances’ use by installation, and GET /v1/usage?kind=volume&group_by=volume lists its Volumes and its buckets by their ids. An application’s calculator (calculator of GET /v1/catalogue/{app}) says what a month of it comes to in those meters, at the inputs it names: month is the amount of each meter at their defaults.

Changing

PATCH /v1/installations/{id} with another version, or with parameters as a merge patch: those given change, null takes one back to its default, the rest are kept. What changed of each app is deployed as a new version of it, waited for as a create is, and the installation is updating meanwhile. A Volume’s size is fixed once it is made (409 volume_size_fixed).

Deleting

DELETE /v1/installations/{id} deletes its apps, its Drives and what they hold, its secrets, and its buckets with what they hold, and revokes the keys held to it; an installation that was installed for it as what it requires goes with it, and one you bound to it stays. One another installation requires is refused (409 required_by_installation): delete that one first. The answer is the installation deleted, or deleting where what is left takes longer, which the platform finishes. The name is free once it is gone. It cannot be undone.

Events

installation.created, installation.ready (after it was made or changed), installation.failed (with failure), installation.updated and installation.deleted, each with the installation’s id, come to the project’s webhooks and GET /v1/events as any event.

Rivet: durable actors for AI agents and realtime apps, the first application of the catalogue.