Repository navigation
Standalone
Barkley is an app (add-on), and apps need the Supervisor: Home Assistant OS or Supervised. You can still run it without one:
- Home Assistant Container or Core, which have no Supervisor and no app store.
- A small box, such as a Raspberry Pi with 1 or 2 GB, even one running Home Assistant OS. A scan needs 0.5 to 1.5 GB of memory for a minute or two, which a small box may not have to spare. Run Barkley on a NAS or PC and point it at Home Assistant. The Pi then only answers a few API calls.
Scans mostly wait on the processor, so a faster machine helps a lot. One test (2026-11-18): the same 17 real apps, one of them a card with over 100 JavaScript files, both with 2 scans at once and 2 Semgrep jobs each:
| Machine | How Barkley ran | All 17 sniffed |
|---|---|---|
| 2012 Intel NUC, Core i3, 16 GB | The app, on Home Assistant OS | about 12 minutes |
| MacBook Pro M5 | Standalone, in Docker Desktop | about 2.5 minutes |
It is the same signed image the app store installs, started differently. Everything works as it does in the app: the list, sniffing, update comparison, auto-sniff and notifications, advisory re-checks, and the AI explanations. AI explanations still go through Home Assistant's AI Task entity, so the AI provider you set up in Home Assistant is the one used, and Barkley stores no AI key of its own.
| The app | Standalone | |
|---|---|---|
| How it reaches Home Assistant | The Supervisor's proxy, no token to handle |
HA_URL and a long-lived access token of an administrator |
| Who can open it | Home Assistant's ingress (the sidebar) | Anyone who logs in with Home Assistant as an administrator |
| Containment | AppArmor profile, no open port, and the tool sandbox | The tool sandbox, and what you give the container (the compose file: non-root, read-only, no capabilities) |
| Where it shows up | The sidebar | Its own address, such as http://192.168.1.20:8099
|
- A Home Assistant administrator. Barkley needs an administrator's token, since the Marketplace's list is for administrators, and only administrators can log in to it.
-
The files. Copy
standalone/compose.yamlinto a new folder, then:mkdir -p data && sudo chown 1000:1000 data -
Two addresses in
compose.yaml:-
HA_URL: Home Assistant, as the container reaches it, such ashttp://homeassistant.local:8123. Usehttpsif Home Assistant has it: with plain http, the token crosses your network unencrypted. -
BARKLEY_URL: Barkley, as your browser reaches it, such ashttp://192.168.1.20:8099. The login and the links in notifications use it.
-
-
docker compose up -d, openBARKLEY_URLand log in with Home Assistant. The first time, a short setup follows: Create token or paste your own for Barkley's Home Assistant token (see below), then an optional GitHub token (Create token on GitHub, or Skip). Then you're on the list.
Three ways, the last one wins:
- Create token in the first-time setup, or later on the Settings page (one more login). Barkley uses your login to make a long-lived access token named "Barkley" and the date. The login's own tokens are revoked right after, as with every login.
- Paste a long-lived access token you made yourself (your profile → Security → Long-lived access tokens) on the same row. Barkley checks that it works and is an administrator's before keeping it.
-
HA_TOKEN_FILE(orHA_TOKEN) incompose.yaml: a token you manage. Barkley uses it as it is and never rotates it.
The token belongs to the Home Assistant account it was made for: the one that logged in, or whoever made the token you pasted. It lists under that account's profile → Security → Long-lived access tokens, where deleting it cuts Barkley off at once. Deleting the account deletes its tokens too, and Barkley needs the account to stay an administrator. If that changes, create or paste a new token on the Settings page.
A token made or pasted in the panel is rotated by Barkley: every 60 days by default (Settings → Token rotation: 30, 60, 90 or 180 days), it makes a new token with the current one, checks it, saves it, and then deletes the old one. Each token lasts twice the period plus a week, so a missed rotation breaks nothing. If a rotation fails, the current token keeps working, the panel shows why and you get a notification; it's tried again a day later. Rotate now does it at once.
Where it's kept: in its own file next to Barkley's database in data/ (mode 600), never
in the database, an export or Diagnostics, and out of reach of the scanner tools (the
sandbox lets them read only their own scan folder and caches). It isn't encrypted: the
key would have to sit next to it, on the same disk, readable by the same process, so it
would protect nothing. Protect the data/ folder instead.
Every page asks for a login with Home Assistant, using Home Assistant's own login page. It
shows the address that is asking (BARKLEY_URL). Only administrators get in, as with the
app. Barkley revokes the login's tokens straight away and keeps only a session of its own
(a cookie that lasts 12 hours, or until Barkley restarts). It never sees your password.
The one exception is the first login, while Barkley has no Home Assistant token: Barkley keeps that login until the setup's Home Assistant step is done, so Create token needs no second login. It's revoked as soon as you create or paste a token or skip the step, when you log out, when Barkley stops, and after 10 minutes at the latest. Should Barkley be killed in between, the login shows under your profile → Security → Refresh tokens until you delete it or Home Assistant expires it (after 90 days unused).
If your browser reaches Home Assistant at another address than the container does (for
example the container uses http://homeassistant:8123 on a Docker network), set
HA_BROWSER_URL to the browser's one.
Already have a reverse proxy that does its own login? Leave out BARKLEY_URL and set
BARKLEY_ALLOW to the proxy's address instead. Barkley won't start with neither, so the
panel is never open to the network by accident.
Barkley's own AppArmor profile is only for the app, and Docker doesn't load it. On Docker Desktop, or on a host without AppArmor, there may be no AppArmor at all. What protects you if a scanner tool is exploited by a file it reads is Barkley's tool sandbox, built on Landlock, a Linux kernel feature that needs nothing installed on the host. Each run of Semgrep, GuardDog, osv-scanner or uv:
- can write only that scan's own folder, and can't read the scan store, the token or other scans;
- can run only what the image ships, so nothing it downloaded or wrote;
- can connect only to port 443 (Semgrep nowhere), and can't listen;
- can't signal Barkley or read its environment.
It needs Linux 5.13 or later (the port limit 6.7 or later) with Landlock enabled; Docker
Desktop has it. To check a host, run cat /sys/kernel/security/lsm: the list includes
landlock when it's enabled. Diagnostics shows "Tool sandbox (Landlock)". Without it,
Barkley doesn't start standalone, because it would be parsing hostile code with nothing
around it. To run anyway, knowing that, add BARKLEY_UNSANDBOXED: "1" under
environment: in compose.yaml (the line is there, commented out) and start it again.
Environment variables. Settings you can change in the panel (the AI entity, AI mode, auto-sniff and the notify target) are kept there once you change them.
| Variable | What it does |
|---|---|
HA_URL |
Home Assistant, as the container reaches it: scheme, host and port only |
HA_TOKEN_FILE or HA_TOKEN
|
Optional: a long-lived access token you manage (a file is better: it stays out of docker inspect). Without one, create or paste Barkley's own on the Settings page |
HA_CA_FILE |
A CA certificate, when an https Home Assistant uses a private CA |
HA_BROWSER_URL |
Home Assistant, as your browser reaches it, if different |
BARKLEY_URL |
Barkley, as your browser reaches it |
BARKLEY_ALLOW |
Client addresses to let in, comma-separated (instead of the login, behind a proxy that does its own) |
BARKLEY_PORT |
The port inside the container (8099) |
BARKLEY_EXPOSURE, BARKLEY_PARALLEL, BARKLEY_JOBS
|
Starting values for the Settings page, as the app's options exposure, parallel_scans, jobs
|
BARKLEY_AI_ENTITY, BARKLEY_AI_MODE, BARKLEY_AUTO_SCAN, BARKLEY_NOTIFY_TARGET
|
Starting values for the panel's settings |
GITHUB_TOKEN_FILE or GITHUB_TOKEN
|
Optional, as the app's github_token
|
BARKLEY_UNSANDBOXED |
1 starts Barkley on a kernel without Landlock, with the scanner tools unsandboxed |
The memory guard reads the container's limit (mem_limit in the compose file) as well
as the machine's free memory, and goes by the lower one. Under 2 GB available it warns,
and under 1 GB it doesn't start a scan. Barkley counts 1.5 GB per scan: with Memory for
scans on Auto (Settings), the 3 GB in the compose file fits two scans at once. On a
machine with memory to spare, raise mem_limit and pick a fixed amount on the Settings
page (8 GB: up to 4 scans, the most Parallel scans allows).
Change the version in image: and run docker compose up -d. The scans in data/ are
kept. The image's signature can be checked as for the app; see
Installing and updating.