> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suji.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Apps

> What an app install is on Suji, where its files live, how upgrades work, and how it relates to the VM hosting it.

An **app** in Suji is a marketplace template — a vetted compose file + manifest + icon, published in the public [suji-hq/suji-templates](https://github.com/suji-hq/suji-templates) repo.

An **app install** is one *running deployment* of that template on one of your VMs. You can install the same app multiple times (e.g. two n8n installs, one for dev and one for prod) on the same VM, or across different VMs.

## Anatomy

When you install an app, Suji:

1. Renders the app's compose file with your form input (API keys, channel tokens, subdomain…).
2. Ships the rendered compose to your VM over the encrypted management channel.
3. Runs `docker compose up -d` on the VM.
4. Wires the app's container into `suji-net` so cloudflared can reach it.
5. Updates the Cloudflare Tunnel ingress so `https://<subdomain>.suji.fr/` routes to this install.
6. Creates a per-install **named volume** for the app's persistent data.

The install gets a stable identifier like `install_<hash>`. You'll see this in URLs, file paths on the VM, and container/volume names.

## Status

| Status       | Meaning                                                                            |
| ------------ | ---------------------------------------------------------------------------------- |
| `installing` | Compose is being deployed                                                          |
| `running`    | App is up and healthy                                                              |
| `stopped`    | Containers are stopped                                                             |
| `restarting` | Containers are being bounced                                                       |
| `upgrading`  | Mid-deploy of a new version or new config                                          |
| `deleting`   | Install is being removed (containers + volume)                                     |
| `failed`     | Something broke — `last_error` field has the reason; Logs tab usually shows it too |

## What you can do with an install

From the install's detail page in the dashboard:

* **Restart** — bounces the containers (`docker compose restart`).
* **Upgrade** — re-deploys with the latest catalog version. For apps with `upgrade_policy: breaking-changes-flagged`, you'll see a diff to acknowledge first.
* **Uninstall** — stops and removes the containers. By default it also deletes the app's volume (irreversible) — or choose **keep data** during uninstall to preserve the volume so you can reconnect to it later.
* **Edit install** — change any of the form fields you filled in. Suji re-renders the compose and redeploys.
* **Rotate secrets** — regenerate any `auto_generate` secret (e.g. an admin token).

## App data

App state lives in a Docker **named volume** scoped to the install. On the VM you can find it under:

```
/var/lib/docker/volumes/<install-id>_<volume-name>/_data/
```

You can also browse and edit files in the volume directly from **Files** in the dashboard — no SSH required.

The volume survives:

* Container restarts
* App upgrades (to compatible versions)
* VM snapshot/restore

It does **not** survive:

* Uninstalling the app — unless you choose **keep data** during uninstall, which preserves the volume
* Destroying the VM (a snapshot covers this if you took one)

## Versions & upgrades

Each app pins a specific image tag (e.g. `ghcr.io/openclaw/openclaw:2026.2.3`). Two upgrade policies:

* **`automatic`** — safe to upgrade in place; the dashboard offers a one-click upgrade when a new version lands in the catalog.
* **`breaking-changes-flagged`** — stateful apps with schema migrations or known breaking changes. The dashboard surfaces a diff and waits for your confirmation.

We pin tags in the catalog, never `:latest`. Cataloged versions are immutable in spirit but mutable in practice — the Suji team may push a re-built catalog entry (same version tag, updated compose) when a packaging-layer fix is needed (e.g. correct volume mount path). Existing installs pick up the fix on the next upgrade.

## App-specific guides

Some apps need first-connect setup (token URL, device pairing, webhook config). The marketplace page for each app covers this. Start at [Marketplace overview](/marketplace/overview).

## Co-existing on a VM

Multiple apps on one VM share the VM's CPU/memory/storage. Each install:

* Has its own compose project (its own containers, network identity, volume).
* Has its own `*.suji.fr` URL if exposed.
* Shows up independently in the Logs / Terminal / Files selectors.

The Suji platform doesn't impose per-app resource limits — the underlying compose does. If you want strict isolation between unrelated workloads, give each its own VM.

## Next

<CardGroup cols={2}>
  <Card title="Browse the marketplace" icon="grid" href="/marketplace/overview">
    What apps exist and what each one is for.
  </Card>

  <Card title="VM management" icon="server" href="/manage-vm/terminal">
    Operate the machine your apps run on.
  </Card>
</CardGroup>