> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suji.cloud/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>