You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Foxhole is a read-only-first homelab diagnostic agent for self-hosters. It collects compact evidence from the services you already run, explains what looks wrong, and keeps write actions behind explicit safety gates.
3
+
Foxhole is an open-source, modular, read-only-first homelab diagnostic agent for self-hosters.
4
4
5
-
The project is built around opt-in integrations: if you do not enable an integration, Foxhole does not register its tools or spend agent context on it.
5
+
It collects compact evidence from the services you already run, explains what looks wrong, and keeps write actions behind explicit safety gates. Every service integration is opt-in: if you do not enable it, Foxhole does not register its tools or spend LLM context on it.
6
6
7
-
## Current Status
7
+
## Architecture And Status
8
8
9
-
Foxhole is early software. The default runtime is a single FastAPI process that serves the dashboard, API, in-process scheduled diagnostics, authenticated browser session flow, and SQLite-backed history. Tagged releases publish a production image to `ghcr.io/jacobthree/foxhole`; contributors can still build the same image locally from this repository.
9
+
Foxhole is early software. The default runtime is intentionally small: one FastAPI process serves the statically exported Next.js dashboard, REST API, authenticated browser session flow, in-process scheduled diagnostics, in-memory live events, and SQLite-backed history.
10
+
11
+
```text
12
+
Browser -> FastAPI on :8000 -> dashboard, API, scheduler, events, SQLite history
13
+
```
14
+
15
+
The Docker image serves the dashboard from `/app/ui/out`. Source-based LXC and systemd installs serve the same static export from `/opt/homelab-agent/ui/out` through `FOXHOLE_STATIC_UI_DIR`.
16
+
17
+
Redis, Celery, and Flower are not part of the default runtime. They remain available through a separate distributed Compose file for advanced installs that intentionally want separate API, worker, and beat processes.
10
18
11
19
## What Foxhole Can Inspect
12
20
13
-
| Area | Integrations |
21
+
| Area |Supported Integrations |
14
22
| --- | --- |
15
-
| Containers | Docker through a socket proxy, Portainer |
16
23
| Virtualization and storage | Proxmox VE, Proxmox backup job visibility |
17
-
| Media | Plex, Sonarr, Radarr, Tautulli, Overseerr |
24
+
| Containers | Docker through a read-only socket proxy, Portainer |
25
+
| Media automation | Plex, Sonarr, Radarr, Tautulli, Overseerr |
18
26
| Monitoring | Uptime Kuma |
19
27
| DNS and network | Pi-hole, Unbound, allowed-subnet LAN discovery |
20
28
| Reverse proxy | Caddy route and upstream diagnostics |
@@ -26,155 +34,154 @@ Foxhole is early software. The default runtime is a single FastAPI process that
| Stage 2 | Confirmed writes | Narrow write tools require an explicit confirmation token before execution. |
29
-
| Stage 3 | Policy-gated automation | Disabled by default. Intended for narrow remediation rules only. |
30
-
31
-
The default path is Stage 1. Worker diagnostics are read-only and should never perform mutations.
37
+
| Stage 3 | Policy-gated automation | Disabled by default. Reserved for narrow remediation loops only. |
32
38
33
-
## Quick Start: Self-Hosted Stack
39
+
The default path is Stage 1. Diagnostics should never mutate homelab state.
34
40
35
-
The included Compose stack runs the default single-process Foxhole app from the GHCR image:
41
+
## Quick Start: Docker Compose
36
42
37
-
- Static dashboard and FastAPI backend on `127.0.0.1:8000`
38
-
- In-process scheduled diagnostics
39
-
- In-memory live events
40
-
- SQLite durable history
41
-
- Optional internal read-only Docker socket proxy
43
+
The standard Compose stack pulls the production image from GHCR:
42
44
43
-
Redis, Celery worker, Celery beat, and Flower are not part of the default stack. They remain available only through the separate distributed Compose file for advanced installs.
45
+
```text
46
+
ghcr.io/jacobthree/foxhole:latest
47
+
```
44
48
45
-
Durable history is written to `iac/compose/data/foxhole.db` on the host. Settings changed through the dashboard or API are written to `iac/compose/config/foxhole.env`. Back up both files if you care about event history, audits, incidents, check results, and integration settings.
docker compose -f iac/compose/docker-compose.distributed.yml up -d
115
125
```
116
126
117
-
Detailed Compose notes live in [docs/deployment/docker-compose.md](docs/deployment/docker-compose.md).
118
-
119
-
Back up `iac/compose/data/` and `iac/compose/config/` for Compose installs. For LXC or systemd installs, back up `/opt/homelab-agent/data/` and `/etc/homelab-agent/foxhole.env`. The deployment docs include stop-copy-restore commands for each path.
120
-
121
-
To serve Foxhole behind HTTPS, proxy only the unified app port, for example Caddy `reverse_proxy 127.0.0.1:8000`, and set `FOXHOLE_SESSION_COOKIE_SECURE=true`. Do not expose the Docker socket proxy, Redis, Celery, or Flower services.
122
-
123
-
## Architecture
124
-
125
-
Production Foxhole is intentionally small:
127
+
Start Flower only when debugging distributed-mode Celery:
126
128
127
-
```text
128
-
Browser -> FastAPI on :8000 -> static dashboard, API, scheduler, SQLite history
129
+
```bash
130
+
docker compose -f iac/compose/docker-compose.distributed.yml --profile debug up flower
129
131
```
130
132
131
-
The Docker image copies the exported Next.js dashboard into `/app/ui/out` and FastAPI serves it directly. LXC and systemd installs serve the same export from `/opt/homelab-agent/ui/out` through `FOXHOLE_STATIC_UI_DIR`. In the default `single` runtime, scheduled checks run inside the app process and live events use an in-memory bus. Redis is only checked in `distributed` mode.
132
-
133
-
## Dashboard UI
133
+
### Local Image Builds
134
134
135
-
The production dashboard is statically exported into the backend image and served by FastAPI. Run the Next.js UI separately only during frontend development:
135
+
Contributors can build the same production image locally and point Compose at it:
136
136
137
137
```bash
138
-
cd ui
139
-
pnpm install
140
-
NEXT_PUBLIC_API_URL=http://localhost:8000 pnpm dev
138
+
docker build -t foxhole:local .
139
+
FOXHOLE_IMAGE=foxhole FOXHOLE_IMAGE_TAG=local docker compose -f iac/compose/docker-compose.yml up -d
141
140
```
142
141
143
-
Open `http://localhost:3000`. `NEXT_PUBLIC_API_URL` points the dev UI at the backend. Without it, the UI uses same-origin API paths for production. Use the Settings page to log in with the bearer token, then configure integrations under Settings > Integrations.
142
+
## Data Persistence And Backups
143
+
144
+
> Critical state lives in the database path and the editable settings file. Back up both before recreating, moving, or upgrading an install.
145
+
146
+
| Install Type | Database And History | Settings And Secrets |
| LXC or systemd |`/opt/homelab-agent/data/`|`/etc/homelab-agent/foxhole.env`|
144
150
145
-
The integrations page shows:
151
+
The database stores events, audits, generated incidents, scheduled check results, and history. The env file stores bearer tokens, integration credentials, cookie settings, and dashboard/API-edited settings.
146
152
147
-
- configured, incomplete, and disabled integrations
148
-
- stable capability IDs such as `containers.list` and `reverse_proxy.routes.diagnose`
149
-
- read-only vs confirmation-gated tool behavior
150
-
- generated integration manifest metadata and resource URIs
-**Default runtime:** One FastAPI process serves the dashboard, API, scheduler, event stream, and SQLite history.
155
-
-**Docker socket:** Foxhole uses `tecnativa/docker-socket-proxy` only when Docker diagnostics are enabled. Stage 1 exposes read-only Docker API groups and keeps `POST=0`.
156
-
-**Secrets:** API keys and tokens are represented as Pydantic secrets and redacted from readiness/config summaries.
157
-
-**LLM context:** Tools return compact structured evidence by default. Raw logs require explicit bounded output modes.
158
-
-**Integrations:** Tools are registered only when their integration is configured, which keeps agent context and permissions scoped to your environment.
159
-
-**Manifests:** Built-in integrations expose metadata through `/integration-manifests` for future plugin and MCP adapter work.
159
+
## Security Architecture
160
160
161
-
## Useful Endpoints
161
+
-**Single exposed app:** Proxy only the unified Foxhole app port, for example Caddy `reverse_proxy 127.0.0.1:8000`.
162
+
-**Docker socket boundary:** Compose uses `tecnativa/docker-socket-proxy` only when Docker diagnostics are enabled. Stage 1 exposes read-only Docker API groups and keeps `POST=0`.
163
+
-**Secret redaction:** API keys and tokens are Pydantic secrets and are redacted from readiness/config summaries.
164
+
-**Scoped tools:** Integrations register tools only after their required configuration is present.
165
+
-**LLM context control:** Tools return compact structured evidence by default. Raw logs require explicit bounded output modes.
166
+
-**Capability metadata:** Built-in integrations expose manifests through `/integration-manifests` for capability views and future MCP adapter work.
162
167
163
-
| Endpoint | Purpose |
164
-
| --- | --- |
165
-
|`GET /healthz`| Public process health |
166
-
|`GET /readyz`| Authenticated readiness and redacted settings summary |
167
-
|`POST /auth/login`| Validates bearer token and sets an HTTP-only browser session cookie |
0 commit comments