Skip to main content

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.

An app in Suji is a marketplace template — a vetted compose file + manifest + icon, published in the public 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 the VM via the cloud-agent.
  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

StatusMeaning
installingCompose is being deployed
runningApp is up and healthy
upgradingMid-deploy of a new version or new config
failedSomething 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 the containers and deletes the volume. Irreversible.
  • 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
  • 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.

​
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

Browse the marketplace

What apps exist and what each one is for.

VM management

Operate the machine your apps run on.