# Sam

Sam is the assistant that comes with every ElfHosted account. Ask him about your apps in plain language and he can check their status, read their logs, restart them, and explain what he finds. He can also install onto your phone as an app, so you get a push notification when something needs your attention.

Sam is bundled with [ElfBot](<https://docs-internal.elfhosted.com/app/elfbot/>), so there is nothing to buy and nothing to enable. He is already there.

## How do I use Sam?

Sam lives at [https://your-username-elfbot.elfhosted.com/sam](<https://your-username-elfbot.elfhosted.com/sam>), and in the corner of your apps dashboard.

Ask him things the way you would ask a person:

- *Why won't my streams play?*
- *Can you check my AIOStreams setup?*
- *Is my stack healthy?*
- *Help me set up an app*

Sam can see your stack and nothing else. He cannot see other customers, and he cannot see the platform. The first time you talk to him he explains what is sent to the model and asks you to agree before anything is.

## What can Sam fix?

More than a restart. He helps you get your apps going in the first place, and when something goes wrong he looks at your actual apps, then does something about it:

- **Helps you set up an app.** Just added something new? Ask Sam to help you get it going. He walks you through it step by step from ElfHosted's own docs, and can fill in the settings for you.
- **Explains errors.** He reads an app's logs and tells you, in plain words, what went wrong and what to do about it.
- **Sorts out disk space.** When storage fills up, he finds what's using it and helps you clear it; for some apps he can clear safe, regenerable caches and old backups himself.
- **Changes settings.** For apps whose documentation lists environment variables you can set with ElfBot, he can set them for you.
- **Restarts apps.** One app, or your whole stack.

Nothing changes without you. Every action appears as an **Approve** card in the chat, and he only goes ahead when you tap it.

Already use Claude, ChatGPT or another AI agent? You can [connect it to your apps](</ai-agents/>) too, so it can do much of the same from the chat you already use.

## Can I install Sam on my phone?

Yes. Sam is a progressive web app, which means your phone can install him from the browser without an app store.

On your phone, open ElfBot and switch Sam to full screen (or go straight to [https://your-username-elfbot.elfhosted.com/sam](<https://your-username-elfbot.elfhosted.com/sam>)), and Sam offers to install himself. On iPhone, use **Share**, then **Add to Home Screen**.

Installing gets you:

- **A home screen icon**, and a full screen app with no browser chrome
- **Push notifications**, which only work inside the installed app on iPhone
- **Faster starts**, because the app shell is cached on the device
- **Offline tolerance**, so a brief loss of signal does not lose your place

Sam works fine in a browser tab if you would rather not install him. You just cannot have notifications on an iPhone that way, because Apple only allows them for installed apps.

## What are push notifications through Sam?

Once Sam is installed, he can offer to turn on notifications. Say yes, and when something in your account needs attention, your phone tells you.

Three things make this better than being emailed, or than wiring an app straight to a push service:

**Nothing buzzes you until you say so.** The first alert from any app is held, not delivered. Sam shows you what it was and asks whether you want alerts from that app. Say no and you never hear from it again. This matters because a monitoring tool fires on every state change, and an unfiltered feed of those is something people turn off within a day.

**Every app gets its own switch.** Tell Sam *stop telling me about Plex* and only Plex goes quiet. You can ask him what is currently allowed at any time.

**Tapping an alert opens a conversation about it.** The notification deep links into Sam with the question already written, so you can ask what a failure means instead of going to hunt for logs yourself.

If you miss one, open Sam and recent alerts are waiting under **While you were away**.

## Will Sam tell me when an app goes down?

Yes, once you've said you want to hear about that app. ElfHosted's health checks watch every app in your stack, and when one stops answering, Sam can send a push notification to your phone, then another when it's back.

Nothing buzzes you by default. The first time an app goes down, Sam holds the alert and asks whether you want alerts from that app in future. Say yes and you'll hear about it next time; say no and it stays quiet. If a whole group of apps blips at once, you get one summary, not a wall of alerts.

Tap an alert and Sam opens a conversation about it: he can check the app's status, read its logs, tell you what went wrong, and restart it if you ask.

## Which apps can notify me this way?

Most of them, and they need no new software. If an app has a notification settings screen, it almost certainly speaks one of the formats below already, and pointing it at Sam is a one-line change on that screen.

The addresses below only work from inside your account. They are not reachable from the internet, which is why they need no password.

### If your app supports Discord

This covers nearly everything, including Sonarr, Radarr, Lidarr, Readarr, Prowlarr, Overseerr and Uptime Kuma.

Add a **Discord** connection and use this as the webhook URL, changing the last part to whatever you want the app called in Sam:

```
http://elfbot:3000/v1/push/discord/sonarr
```

No Discord account is involved. That last word is the name Sam gives the app, and it is what gets its own on and off switch.

### If your app supports ntfy

Set the **server URL** to `http://elfbot:3000/v1/push/ntfy` and the **topic** to whatever you want the app called in Sam.

Priority works as you would expect: `min` or `low` files the message in Sam without buzzing your phone.

### If your app supports Gotify

Set the **server URL** to `http://elfbot:3000/v1/push/gotify`, and put the **app name** where it asks for an app token.

Gotify normally uses that token to tell its apps apart, and nothing inside your own account needs a password, so Sam reads it as a name instead. That is what gives each app its own switch. Priority below 4 files without buzzing.

### If your app supports Apprise

Use one of these as the Apprise URL, changing the last part to the name you want in Sam:

```
ntfy://elfbot:3000/sonarr
gotify://elfbot:3000/radarr
```

Bazarr is the common one here, since its notifications are Apprise-based.

### What to expect

- **The first alert from a new app is held.** Look in Sam for **Want alerts from these?** and answer it. This is not a fault, it is Sam checking before letting something new start buzzing you.
- **Links point back at ElfHosted.** If an alert carries a link to another site, Sam drops the link. The alert still arrives.
- Sam delivers alerts to you. He does not replace a monitoring tool, and he does not keep a permanent archive of everything your apps have ever said.
- If you have something that does not speak any of these, [ask us](</get-help/>) and we will help you point it at Sam.

## Is Sam included?

Yes, with every ElfHosted account, at no extra cost.

> [!NOTE]
>
> **Info**
>
> Sam is an open-source tool. ElfHosted provides hosting infrastructure only. Users are responsible for their use of this service in compliance with applicable laws and third-party terms of service.

## Sam also works with

- [x] [Sonarr](</app/sonarr/>)
- [x] [Radarr](</app/radarr/>)
- [x] [Bazarr](</app/bazarr/>)
- [x] [Prowlarr](</app/prowlarr/>)
- [x] [Overseerr](</app/overseerr/>)
- [x] [Plex](</app/plex/>)

## How do I get support for Sam?

1. Sam is an ElfHosted-exclusive, proprietary tool with no third-party upstream. For general usage questions, refer to the documentation above.
2. For specific support re your ElfHosted configuration / account, see the [ElfHosted support options](</get-help/>)!