Freebox OS Ultra Dashboard

Version BETA - Ce projet est en cours de developpement. Des bugs peuvent etre presents et certaines fonctionnalites peuvent ne pas fonctionner comme prevu. N'hesitez pas a signaler les problemes rencontres.

Compatibilite

Apercu

Freebox OS Ultra Dashboard est une interface web alternative pour gerer votre Freebox. Construit avec React 19 et Express 5, il offre une experience utilisateur fluide et moderne avec des donnees en temps reel.

Captures d'ecran

Installation Docker (Recommandee)

Docker est la methode recommandee pour deployer sur NAS (Synology, QNAP), Raspberry Pi ou serveurs.

Prerequis

• Docker et Docker Compose installes
• Acces au meme reseau local que la Freebox

Deux methodes de deploiement

Production (Image pre-construite - Recommande)

Utilise l'image officielle depuis GitHub Container Registry :

# Lancer le conteneur avec l'image pre-construite
docker-compose up -d

Avantages :

• Demarrage ultra-rapide (pas de compilation)
• Image testee et validee
• Mises a jour automatiques avec docker-compose pull

Developpement local (Build depuis les sources)

Pour tester des modifications ou contribuer :

# Build et lancement local
docker-compose -f docker-compose.local.yml up -d --build

Mode developpement avec Hot Reload

Pour developper avec recompilation automatique et rafraichissement du navigateur :

# Lancer le mode dev avec hot reload
docker compose -f docker-compose.dev.yml up --build

Exemple avec des ports alternatifs

DASHBOARD_PORT=5777 SERVER_PORT=5776 docker compose -f docker-compose.dev.yml up --build

• Frontend : http://localhost:3000 (Vite HMR - rafraichissement instantane)
• Backend API : http://localhost:3001 (redemarrage auto avec tsx watch)

Les modifications de fichiers sources sont automatiquement detectees et appliquees sans redemarrer le conteneur.

Note: En mode developpement local (sans Docker), Vite utilise le port 5173 par defaut.

Lancement rapide

# Cloner le depot
git clone https://github.com/HGHugo/FreeboxOS-Ultra-Dashboard.git
cd FreeboxOS-Ultra-Dashboard

# Lancer avec l'image pre-construite (PRODUCTION)
docker-compose up -d

# OU build local (DEVELOPPEMENT)
docker-compose -f docker-compose.local.yml up -d --build

Le dashboard sera accessible sur :

• http://localhost:7505 - depuis la machine hote
• http://IP_DU_SERVEUR:7505 - depuis un autre appareil du reseau (remplacez IP_DU_SERVEUR par l'adresse IP de la machine ou Docker est installe, ex: 192.168.1.100)

Configuration Docker

Personnalisez le deploiement avec des variables d'environnement :

# Changer le port (defaut: 7505)
DASHBOARD_PORT=8080 docker-compose up -d

# Ou avec un fichier .env
echo "DASHBOARD_PORT=8080" > .env
docker-compose up -d

Mise a jour Docker

# Production (image pre-construite)
docker-compose pull
docker-compose up -d

# Developpement local (rebuild)
docker-compose -f docker-compose.local.yml up -d --build

Persistance du token

Le token d'authentification est automatiquement sauvegarde dans un volume Docker (freebox_dashboard_data). Il persiste entre les redemarrages et mises a jour du conteneur.

Commandes Docker utiles

# Voir les logs en temps reel
docker-compose logs -f

# Redemarrer le conteneur
docker-compose restart

# Arreter le conteneur
docker-compose down

# Mettre a jour vers la derniere version
git pull
docker-compose build --no-cache
docker-compose up -d

Securite Docker

L'image Docker est configuree avec les bonnes pratiques de securite :

• Utilisateur non-root (freebox)
• Health check automatique
• Variables d'environnement configurables (pas de secrets hardcodes)

Merci à Loule95450 & Rayandri pour la pull-request.

Integration MCP — Piloter la Freebox via Claude AI (Optionnel)

Le dashboard peut etre complete par un serveur MCP (Model Context Protocol) qui permet de piloter votre Freebox en langage naturel depuis Claude Desktop.

Exemples de commandes possibles :

• "Quels appareils sont connectes en ce moment ?"
• "Montre-moi les telechargements en cours"
• "Quelle est la temperature de ma Freebox ?"
• "Ouvre le port 8080 vers mon serveur 192.168.1.10"
• "Demarre la VM Ubuntu"

Activation

Le serveur MCP est un profil Docker Compose optionnel — les utilisateurs qui n'en veulent pas ne sont pas impactes.

# Production (image pre-construite)
docker-compose --profile mcp up -d

# Developpement local (build depuis les sources)
docker-compose -f docker-compose.local.yml --profile mcp up -d --build

Configuration Claude Desktop

Editez le fichier de configuration Claude Desktop :

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows : %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "freebox": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "freebox_mcp_data:/app/data",
        "-e", "FREEBOX_HOST=mafreebox.freebox.fr",
        "ghcr.io/leto1210/mafreebox-mcpserver:latest"
      ]
    }
  }
}

-i et non -it : Claude Desktop communique via stdio sans TTY.

Premiere connexion MCP

1. Dans Claude Desktop, demandez : "Connecte-toi a ma Freebox"
2. Claude appellera freebox_authorize
3. Sur votre Freebox : un message s'affiche sur l'ecran LCD
4. Appuyez sur > pour autoriser l'application
5. Demandez a Claude : "Verifie si l'autorisation est accordee"
6. Le token est sauvegarde — les prochaines sessions sont automatiques

Pour plus de details, consultez le README du serveur MCP.

Premiere connexion

Au premier lancement, vous devrez autoriser l'application sur la Freebox :

1. Accedez au dashboard (http://localhost:7505 ou votre IP)
2. Cliquez sur "Connecter" dans l'interface
3. Sur votre Freebox : Un message s'affichera sur l'ecran LCD
4. Appuyez sur la fleche droite (>) de la Freebox pour autoriser
5. L'application est maintenant connectee !

Note: Pour certaines fonctionnalites (WPS, VPN, etc.), vous devrez peut-etre activer des permissions supplementaires dans Freebox OS > Parametres > Gestion des acces > Applications.

Fonctionnalites

Dashboard Principal

• Debit en temps reel - Surveillance du debit descendant/montant avec graphiques sparkline
• Statut de connexion - Etat de la ligne fibre, type de connexion, latence
• Informations systeme - Temperature CPU, utilisation memoire, uptime
• Appareils connectes - Liste des appareils sur le reseau local

WiFi

• Gestion des reseaux - Configuration des bandes 2.4GHz, 5GHz et 6GHz (Ultra uniquement)
• WPS - Activation/desactivation du WPS avec bouton push
• Filtrage MAC - Gestion de la liste blanche/noire
• QR Code - Generation de QR codes pour connexion rapide

VPN

• Multi-protocoles - Support OpenVPN (routed/bridge), PPTP, WireGuard
• Gestion des serveurs - Demarrage/arret des serveurs VPN
• Statistiques - Nombre de connexions actives

Telechargements

• Gestionnaire complet - Ajout de torrents, URLs directes
• Progression en temps reel - Vitesse, ETA, statut
• Controle - Pause, reprise, suppression

Fichiers

• Explorateur - Navigation dans les fichiers de la Freebox
• Operations - Copie, deplacement, renommage, suppression
• Partage - Creation de liens de partage

Telephonie

• Journal d'appels - Historique complet avec filtres
• Contacts - Gestion du repertoire
• Repondeur - Ecoute des messages vocaux

TV

• Guide des programmes - EPG en temps reel
• Chaines - Liste des chaines disponibles
• Enregistrements - Gestion des enregistrements programmes

Machines Virtuelles (Ultra/Delta uniquement)

• Gestion des VMs - Demarrage, arret, redemarrage
• Ressources - vCPU, memoire et disque alloues
• Creation - Assistant de creation de VMs

Controle Parental

• Profils - Creation de profils par utilisateur
• Filtres - Blocage de sites et categories
• Horaires - Plages horaires d'acces

Analytiques

• Historique bande passante - Graphiques sur 1h, 24h, 7j
• Temperatures - Evolution des temperatures du systeme
• Statistiques reseau - Donnees detaillees de connexion

Visualisation Reseau

• Topologie interactive - Carte du reseau avec la Freebox au centre, l'ISP et tous les appareils connectes
• Flux animes - Flux de particules animees pour le WiFi, lignes solides pour l'Ethernet
• Pan & Zoom - Navigation libre avec deplacement, zoom molette/boutons et reset
• Logos des appareils - Affichage automatique des logos des marques (Apple, Samsung, Google, etc.) via logo.dev (optionnel, voir configuration)
• Mode sans logo - Fonctionne sans cle API avec des icones generiques (Lucide Icons)

Logos des appareils (logo.dev)

La page Visualisation Reseau peut afficher les logos des marques (Apple, Samsung, Google, Raspberry Pi, etc.) a cote de chaque appareil connecte. Cette fonctionnalite utilise l'API logo.dev et est entierement optionnelle.

Avec logos (recommande)

1. Creez un compte gratuit sur logo.dev
2. Recuperez votre cle API publique depuis le tableau de bord logo.dev
3. Ajoutez-la dans votre fichier .env :

VITE_LOGO_DEV_TOKEN=pk_votre_cle_ici

4. Redemarrez l'application

Sans logos

Si aucune cle API n'est configuree (VITE_LOGO_DEV_TOKEN vide ou absent), la visualisation fonctionne normalement avec des icones generiques (Lucide Icons) a la place des logos de marques. Aucune erreur ne sera affichee.

Installation alternative (Node.js)

Option 1 : Lancement direct

# Cloner le depot
git clone https://github.com/HGHugo/FreeboxOS-Ultra-Dashboard.git
cd FreeboxOS-Ultra-Dashboard

# Installer les dependances
npm install

# Build du frontend
npm run build

# Lancer le serveur
npm start

Le serveur sera accessible sur http://localhost:3001

Option 2 : PM2 (Production)

PM2 permet de garder l'application en ligne 24/7 avec redemarrage automatique.

# Installer PM2
npm install -g pm2

# Build et lancer
npm run build
pm2 start npm --name "freebox-dashboard" -- start

# Demarrage automatique au boot
pm2 startup
pm2 save

Developpement

Mode Developpement

npm install
npm run dev

• Frontend : http://localhost:5173 (hot-reload)
• Backend API : http://localhost:3001

Build Production

npm run build

Architecture du projet

freebox-os-ultra-dashboard/
├── src/                          # Frontend React
│   ├── api/                      # Client API
│   ├── components/
│   │   ├── layout/               # Header, Footer, Sidebar
│   │   ├── modals/               # Modals (WiFi, VPN, VM, etc.)
│   │   ├── ui/                   # Composants reutilisables (Toggle, Card, etc.)
│   │   └── widgets/              # Widgets du dashboard
│   ├── hooks/                    # Hooks React personnalises
│   ├── pages/                    # Pages (Dashboard, TV, Phone, etc.)
│   ├── stores/                   # State management (Zustand)
│   ├── types/                    # Types TypeScript
│   └── utils/                    # Utilitaires (formatters, helpers)
│
├── server/                       # Backend Express
│   ├── middleware/               # Middlewares (error handler)
│   ├── routes/                   # Routes API
│   │   ├── auth.ts               # Authentification Freebox
│   │   ├── connection.ts         # Statut connexion
│   │   ├── wifi.ts               # Configuration WiFi
│   │   ├── lan.ts                # Appareils reseau
│   │   ├── downloads.ts          # Gestionnaire telechargements
│   │   ├── fs.ts                 # Systeme de fichiers
│   │   ├── vm.ts                 # Machines virtuelles
│   │   ├── calls.ts              # Journal d'appels
│   │   ├── tv.ts                 # TV et enregistrements
│   │   └── ...
│   ├── services/
│   │   ├── freeboxApi.ts         # Client API Freebox
│   │   └── modelDetection.ts     # Detection modele Freebox
│   └── types/                    # Types backend
│
├── dist/                         # Build frontend (production)
├── Dockerfile                    # Build Docker multi-stage
├── docker-compose.yml            # Configuration Docker Compose
└── package.json

Technologies

API Freebox

Ce projet utilise l'API officielle Freebox OS. Documentation : dev.freebox.fr

Endpoints implementes

FAQ

docker volume ls | grep freebox

Contribution

Les contributions sont les bienvenues !

Guidelines

• Respectez le style de code existant
• Ajoutez des types TypeScript pour tout nouveau code
• Testez vos modifications avant de soumettre
• Documentez les nouvelles fonctionnalites

Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de details.

Design

Le design de ce dashboard a ete realise par @powl_d. Merci pour ce magnifique travail !

Remerciements

• Free pour la Freebox et son API ouverte
• Freebox SDK pour la documentation
• La communaute open source pour les excellentes bibliotheques utilisees