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.

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.

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

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

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

Pour tester des modifications ou contribuer :

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

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

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.

# 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)

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

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

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

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.

# 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

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.

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"

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

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.

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.

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.

• 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

• 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

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

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

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

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

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

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

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

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

• 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)

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.

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

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.

# 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

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

npm install
npm run dev

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

npm run build

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

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

docker volume ls | grep freebox

Les contributions sont les bienvenues !

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

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

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

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