Help › Start here
bananana on TrueNAS SCALE
Install the brain from the TrueNAS community catalog and the agent as a Custom App: where the token and code go, what each setting does, updating, and common problems.
bananana-brain, your dashboard, is in the TrueNAS community catalog. bananana-node, the agent that connects the TrueNAS system to a brain, isn't: the catalog only takes apps that stay inside their container, and the agent has to see the machine around it. So it goes in as a Custom App. Neither opens a port. You need TrueNAS SCALE 24.10 or newer with a pool chosen for apps, and internet access.
Install the brain
- Go to bananana.dev/start and create a free account. Answer the questions and name your brain.
- At Where will you run your brain? choose TrueNAS SCALE and press Continue. The next page shows your setup token, which starts with
bst_. Press Copy and leave the page open. - In TrueNAS, open Apps, press Discover Apps, search for bananana-brain and press Install.
- Paste the token into Setup Token. Set your Timezone, and press Install.
- Go back to the setup page. It moves on by itself when the brain connects, usually within a minute or two, and then takes you to your brain at your-name.bananana.dev.
The token works once and expires after 24 hours. If it expired, press New token on the setup page.
The brain's settings
| Setting | Default | What it does |
|---|---|---|
| Timezone | Etc/UTC | Sets when the nightly backup runs (04:10) and the times in the logs. |
| Setup Token | empty (required) | The bst_ token from the setup page. It's used on the first start only, and ignored after that. |
| Additional Environment Variables | none | Rarely needed. The list is on Running bananana in Docker. |
| User ID, Group ID | 568 | Who the brain runs as. The default is the TrueNAS apps user. |
| Networks, Host Network | none, off | Leave these alone. The brain connects out by itself, so it needs no port and no host network. |
| Data Storage | ixVolume | The brain's identity, settings, users and history. Choose a Host Path if you want it on a dataset of your own. Keep it backed up. |
| Backups Storage | ixVolume | Where the brain's nightly backup goes. |
| Additional Storage | none | Not needed by the brain. |
| CPUs, Memory (in MB) | 2, 4096 | The most the brain may use. |
There's no web portal button: you reach the brain at your-name.bananana.dev and in the bananana.dev apps.
Install the agent
The agent lets the brain see and manage this TrueNAS system. If the brain runs here too, you still install the agent: the brain's container can't see the system around it.
- On your brain, open Nodes and press Onboard a device.
- Choose Install command, give it a name, and pick TrueNAS under System. Choose its features and press Create install code.
- The page shows the code, which starts with
bnn-, and below it the app's YAML with the code already inBANANANA_NODE_TOKEN. Press Copy next to the YAML. - In TrueNAS, open Apps, press Discover Apps, open the ⋮ menu and choose Install via YAML.
- Type
bananana-nodeas the Name, paste the YAML into Custom Config and press Save. - Watch the brain's page change to Connected.
The code works once and expires after 24 hours. Treat it like a password until it's used. It stays in the app's YAML afterwards, where it no longer does anything.
The YAML is node-compose.yaml with the code filled in. If you start from that file instead, replace ${BANANANA_NODE_TOKEN:-} with your code in quotes: TrueNAS has nowhere else to set it.
The agent's settings
| In the YAML | What it does |
|---|---|
BANANANA_NODE_TOKEN | The bnn- code from your brain. A remote code or deployment key works here too. It's used on the first start only. |
BANANANA_NODE_NAME | Optional, and not in the YAML unless you add it under environment:. The name shown on the brain. Without it, the name you gave the code is used, or the system's name. |
bananana-node:/data | The agent's identity and settings. Its private key stays here. |
Why the agent is privileged
The agent reports and manages the system itself, not just its own container, and each of these lines in the YAML is part of that:
| In the YAML | Why it's needed |
|---|---|
privileged: true | Reads disks and temperature sensors, and runs host commands such as docker and the terminal's shell. |
pid: host | Shows the system's processes, and reaches its files. |
network_mode: host | Reports the system's real network interfaces and traffic, and lets it join your bunch. |
uts: host | Reports the system's real name. |
Those lines are what the container can reach. What the agent may do (terminal, files, service control) is what you chose when you created the code, and the agent enforces it. Screen control isn't available in the container. The brain doesn't need any of this: it isn't privileged.
Updating
- The brain: TrueNAS offers Update on the app in Apps when the catalog has a new version. Your data stays in Data Storage. The catalog follows bananana releases with a delay, so the app can be a few versions behind the changelog.
- The agent: it updates itself like any other node.
Common problems
Setup Token says "The setup token starts with bst_"
Something else got copied. Press Copy on the setup page and paste again, with no spaces around it.
The setup page keeps waiting for the brain
Open the app in Apps and read its logs. setup didn't finish gives the reason. If the token expired or was already used, press New token on the setup page, then press Edit on the app, paste it into Setup Token and save.
There's no TrueNAS choice under System
Your brain is an older version. Until it's updated, pick Docker and copy the part of the command between the quotes that starts with bnn-. That's the same code: use it in place of ${BANANANA_NODE_TOKEN:-} in node-compose.yaml.
The node never connects
Open the bananana-node app's logs. If the code expired or was used, create a new one on the brain, press Edit on the app, replace the code in the YAML and save.
TrueNAS won't accept the YAML
Paste all of it, from services: to the last line, without changing the spaces at the start of each line.
The node is connected but says it's waiting
A remote code or deployment key can need your approval: Approving devices.
Removing them
Open the app in Apps and delete it. For the brain, TrueNAS asks whether to remove its ixVolumes too: that deletes its data, so keep them if you might come back. After removing the agent, press Remove on the device's page on the brain.