> ## 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.

# Install your first app

> Pick an app from the marketplace, fill in the form, click Deploy. The dashboard handles the rest.

Apps are installed **on top of an existing VM**. If you haven't created a VM yet, [do that first](/getting-started/first-vm) — apps don't get a VM by themselves.

## Pick an app

<Steps>
  <Step title="Open the marketplace">
    Dashboard sidebar → **Apps**.
  </Step>

  <Step title="Choose an app">
    The catalog lists curated open-source apps. Click any card to read the description, required config, recommended VM size, and license. Some examples:

    * **OpenClaw** — Multi-channel AI messaging bot (Telegram / Discord / WhatsApp / Slack).
    * **n8n** — Workflow automation.
    * **Ghost** — Modern blogging platform.
    * **NocoDB** — Airtable-like no-code database.
    * **Plausible** — Privacy-friendly analytics.
    * **Wiki.js** — Open-source wiki.
    * **Minecraft** — Managed Minecraft server with a web admin panel.

    See [Marketplace overview](/marketplace/overview) for the full list and per-app guides.
  </Step>

  <Step title="Click Install">
    On the app's detail page, click **Install**. You'll be asked which VM to install on.
  </Step>
</Steps>

## Fill in the install form

Every app's form is different — it comes from the app's `manifest.yaml`. Fields fall into a few common patterns:

* **Required secrets** — API keys / tokens you have to supply (e.g. an Anthropic API key, a Telegram bot token).
* **Auto-generated secrets** — gateway passwords / admin tokens that Suji fills with a random value if you leave them blank.
* **Selectors** — pick channels / providers / modes.
* **Subdomain** — for exposable apps. Suji prefills a unique suggestion based on the app's `subdomain_hint`; you can edit it. Final URL: `https://<your-subdomain>.suji.fr/`.

<Note>
  All secret fields are encrypted at rest. They're never shown back to you in plain text after save — only their existence.
</Note>

Click **Deploy**. The install runs in the background. Status flows: `installing` → `running`.

## After it's running

The install detail page in the dashboard shows:

* The public URL (if exposable).
* The app's logs, terminal, and files (the Logs / Terminal / Files tabs at the instance level — pick the install from the selector).
* The current version.
* Restart, Upgrade, Uninstall actions.
* Edit Install — change any field from the install form. Suji redeploys the container automatically.

## Common patterns

<AccordionGroup>
  <Accordion title="Webhooks need the app's public URL">
    For chatbots and integrations, you'll configure a webhook in the third-party service (Telegram, Discord, WhatsApp Cloud API, Slack) pointing at your app's `https://<subdomain>.suji.fr/...` URL. Set these up *after* the install reaches `running` — the URL only exists once the app is live.
  </Accordion>

  <Accordion title="Some apps need a one-time first-connect step">
    A few apps (notably OpenClaw) require a token-bearing URL or device pairing for the first connection. Check the app's marketplace page for any first-connect notes — for OpenClaw specifically, see [its full guide](/marketplace/openclaw).
  </Accordion>

  <Accordion title="Outbound SMTP is restricted">
    The underlying network blocks outbound mail on ports 25 and 465 to prevent spam. If your app sends email, point it at a relay over port 587 (SendGrid / Mailgun / Postmark / Resend) — adding a firewall rule won't help.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Marketplace overview" icon="grid" href="/marketplace/overview">
    Browse all available apps and their guides.
  </Card>

  <Card title="Managing your VM" icon="server" href="/manage-vm/terminal">
    Operate the VM that hosts your apps — terminal, files, firewall.
  </Card>
</CardGroup>