Blueprint Studio for Home Assistant 🚀
!Home Assistant
!Maintenance
!Downloads
Blueprint Studio for Home Assistant
A modern, feature-rich file editor with AI-powered assistance and full Git integration.
📖 Table of Contents
- Why Blueprint Studio? 🌟
- Screenshots 📸
- Keyboard Shortcuts
- ✨ Features
- 🔧 Installation
- ⚙️ Configuration
- 🚀 Usage
- 📄 Supported File Types
- 🔒 Security
- 🛠️ Troubleshooting
- ❓ FAQ
- 🔍 Technical Details
- 🤝 Contributing
- 📞 Support
- 📄 License
- 🙌 Acknowledgments
- ⚖️ Comparison with Other Solutions
- Support the Project
- ⭐ Star History
Why Blueprint Studio? 🌟
Tired of juggling external editors, SSH, or add-ons just to tweak your Home Assistant configs? Blueprint Studio brings the power of a full-fledged IDE right into your HA dashboard. Here's why it's a game-changer:- No External Tools Required - Edit local Home Assistant config files directly in Home Assistant without SSH or file shares 🚫
- Professional Editor - Full-featured code editor with syntax highlighting and linting 💻
- Safe & Secure - Built-in protection against path traversal and unauthorized access 🛡️
- Multi-File Editing - Work with multiple files simultaneously using tabs 📁
- File Management - Create, delete, rename, copy, upload, and download files and folders 📂
Screenshots 📸
The supported workspace is verified at desktop, tablet, and phone sizes in both light and dark themes. See frontend visual baselines and the release quality gates for the repeatable checks used for shipped interface changes.
Main Editor Interface
Edit your Home Assistant configuration files with syntax highlighting and professional tools!Blueprint Studio Main Interface
File Tree & Multi-Tab Support
Navigate your config directory and work with multiple files simultaneouslyReal-Time YAML Validation
Catch errors before saving with built-in YAML lintingMulti-Tab Editing in Action
Work efficiently with multiple files open at onceGitHub Integration 🔗 NEW!
Complete Git workflow - stage, commit, and push directly from Blueprint StudioGit Settings & Authentication
One-click OAuth login or Personal Access Token authenticationCreate GitHub Repositories
Create new repositories without leaving Home AssistantComplete Git Workflow
Edit, stage, commit, and push - all in one place✨ Features
Editor Features 🎨
- AI Studio Copilot - Home Assistant-aware deterministic generation and optional Home Assistant, local, or cloud AI providers. Generated edits are parsed, validated, and shown as before/after proposals that require an explicit Apply action 🧠
- Syntax Highlighting - Support for YAML, JSON, Python, JavaScript, HTML, CSS, Markdown, and Shell scripts 🌈
- Code Folding - Collapse and expand code sections for better focus 📜
- Line Numbers - Easy navigation with line numbers 🔢
- Active Line Highlighting - See your cursor position clearly 🎯
- Bracket Matching - Automatic bracket highlighting 🧩
- Auto-close Brackets - Automatic bracket completion ⌨️
- Smart Autocomplete - Intelligent suggestions for Home Assistant entities (type
light.to see lights), keys, and values 🧠 - YAML Snippets - Templates for common HA patterns like Automations and Sensors (type
snip:) 🧩 - YAML Linting - Real-time YAML syntax validation with error highlighting ❌
- Jinja Template Support - Full syntax highlighting for Jinja2 templates with distinct coloring for brackets, keywords, and variables 📝
- Command Palette - Instant access to all features with
Ctrl+K⌨️ - UUID Generator - Instantly insert a random UUID v4 with
Ctrl+Shift+U🆔 - Split View - Edit two files side-by-side with pane-aware tabs and split controls 🪟
- Minimap - Optional VS Code-style minimap for fast navigation in long files 🗺️
- Professional Search - Floating Find/Replace widget with navigation controls (
Ctrl+F,Ctrl+H) 🔎 - Global Search - Search across all files with Regex and Case Sensitivity support (
Ctrl+Shift+F). Now optimized to skip binary files and hidden folders for lightning-fast results 🌐 - Entity Explorer Mode - New mode in Global Search to browse the entity registry, view states, and copy IDs directly into your code 🔍
- Filter by Content - Sidebar toggle to filter the file tree by text content (e.g., find all files containing
input_boolean.test) 📂
Editor Customization ⚙️ NEW in v2.0.0!
- Font Size - Adjustable from 10px to 24px to suit your preference 🔤
- Font Family - Choose from 7 popular programming fonts (SF Mono, Fira Code, JetBrains Mono, Cascadia Code, Source Code Pro, Ubuntu Mono) 🔡
- Word Wrap - Toggle line wrapping for long lines ↩️
- Line Numbers - Show or hide line numbers #️⃣
- Show Whitespace - Display spaces and tabs visually ␣
- Auto-Save - Automatically save files after a configurable delay (500ms - 5000ms) 💾
- Tabbed Settings - New organized settings interface with General, Appearance, Editor, and Features tabs 🗂️
UI Features 🎨
- 6 Theme Presets - Choose from Dark, Light, High Contrast, Solarized Dark, Solarized Light, Ocean, and Dracula themes 🎨
- Custom Accent Colors - Personalize the accent color with 8 vibrant options 🔵🟣🔴🟢
- Onboarding Wizard - Step-by-step tour for new users to initialize and connect 🎓
- File Tree Explorer - Navigate your config directory with an expandable folder tree 🌳
- File Type Icons - Different colored icons for various file types (toggle on/off) 🎨
- Compact File Tree Mode - Dense layout option for smaller screens 📱
- Multiple Tabs - Open and edit multiple files simultaneously 🗂️
- Recent Files - Quickly reopen recently edited files from the sidebar 🕘
- Resizable Sidebar - Drag to resize the file explorer 📏
- Breadcrumb Navigation - Move through folders without losing context 🧭
- File Search - Filter files in the explorer 🔍
- Status Bar - Shows cursor position, file type, and connection status 📊
- Toast Notifications - Elegant success/error messages with persistent error display 🔔
- Custom Editor Colors - Customize font colors for syntax highlighting (Comments, Keywords, Strings, etc.) in Settings 🎨
File Management 📁
- Create Files & Folders - Right-click context menu for creating new items ➕
- Bulk Operations - New selection mode to pick multiple files and folders for batch actions 📦
- Drag & Drop Reorganization - Move files and folders by dragging them 📦
- Upload Files - Drag & drop files directly into the file tree or use the upload button ⬆️
- Download Files - Download individual files, multiple selected items, or entire folders as ZIP ⬇️
- Copy & Paste - Duplicate files and folders 📋
- Rename & Move - Rename files or move them to different locations 🔄
- Delete - Remove files and folders (with protection for critical files) 🗑️
- Folder Operations - Upload/download entire folder structures as ZIP files 📦
- Folder Sizes - View directory sizes directly in the file explorer 📊
- Asset Preview - View images, PDFs, videos, and audio files directly in the editor 🖼️
- Pin Favorites - Pin frequently used files for quick access at the top of the sidebar 📌
Remote Access & Terminal 🖥️ NEW!
- SFTP Browser - Connect to remote servers, browse folders, and edit files through the same editor 🔐
- Shared SSH Hosts - Reuse saved hosts between SFTP and the embedded terminal 🔁
- Password or SSH Key Auth - Store password-based or PEM key-based connection profiles 🔑
- Remote File Operations - Create, rename, copy, move, delete, upload, download, and ZIP remote folders 📦
- Streaming Media Preview - Preview remote images, PDFs, audio, and video through tokenized streams 🎬
- Embedded Terminal - Run commands in an xterm.js terminal panel or move it into an editor tab ⌨️
- ZIP Progress UI - Track large local and SFTP folder downloads without blocking the interface 📊
Git Integration 🔗 NEW!
- Easy Authentication - One-click OAuth Device Flow or manual PAT 🔐
- Create GitHub Repos - One-click repository creation directly from Blueprint Studio 🚀
- Gitea Support - Connect to self-hosted Gitea servers with repository creation and sync controls 🏠
- Stay Logged In - Credentials persist across restarts ✨
- Push & Pull - Sync your configs with GitHub 🔄
- Commit History - Dedicated panel to browse past commits and view full diffs 📜
- Stage & Commit - Manage changes with visual Git panel 📝
- Explorer-Integrated Diff - Click the "Difference" icon in the file tree for instant side-by-side reviews 🔍
- Visual Diff Viewer - Compare changes side-by-side before committing with color-coded highlighting 🌈
- Smart Commit Messages - Auto-generates messages based on staged files (e.g., "Update config") 🧠
- Advanced Sync Recovery - One-click tools to "Abort" stuck syncs or resolve "Diverged" history 🛡️
- Branch Management - Intelligent tools to repair local
master->mainmismatches 🔄 - Visual Sync Status - Real-time arrows (↑/↓) showing commits ahead/behind remote 🔄
- Advanced .gitignore - Manage exclusions with a full interactive tree and automated redundancy filtering 🛡️
- Safety Checks - Proactively prompts to commit unstated changes before pushing 🛡️
- Auto-Repair - Detects and fixes "index.lock" and corrupt index errors with one click 🔧
- Manage Remotes - Add or remove remote repositories from Settings 🗑️
- Automatic Status Updates - Git panel updates automatically after file operations ⚡
- Periodic Polling - Detects changes made outside Blueprint Studio (every 30s) 🔄
- Real-time Status - See modified, added, deleted files instantly 👁️
- GitHub Octicons - Professional Git icons matching GitHub's UI 🎨
Toolbar 🛠️
New Restart Button - Quickly restart HA from the toolbar
- Save / Save All 💾
- Undo / Redo ↶↷
- Cut / Copy / Paste ✂️📋
- Search / Replace 🔍🔄
- Bulk Select Mode ☑️
- YAML Validation ✅
- Restart Home Assistant 🔄
- Refresh file list 🔄
- Collapse/Expand all folders 📂📁
- Upload/Download files and folders ⬆️⬇️
- Developer Tools 🧰
- Terminal ⌨️
- Git Pull / Push / Status / Settings 🔗
Keyboard Shortcuts ⌨️
| Shortcut | Action | |----------|--------| |Ctrl+E / Cmd+E | Quick File Switcher 🔍 |
| Ctrl+B / Cmd+B | Toggle Sidebar 📂 |
| Ctrl+Shift+] | Next Tab ➡️ |
| Ctrl+Shift+ | Previous Tab ⬅️ |
| Ctrl+F / Cmd+F | Find in file 🔎 |
| Ctrl+Shift+F / Cmd+Shift+F | Global Search 🌐 |
| Ctrl+Shift+U / Cmd+Shift+U | Insert UUID 🆔 |
| Ctrl+H / Cmd+H | Replace in file 🔄 |
| Ctrl+S / Cmd+S | Save file 💾 |
| Ctrl+Shift+S / Cmd+Shift+S | Save all files 💾📁 |
| Ctrl+G / Cmd+G | Go to line 📍 |
| Ctrl+/ / Cmd+/ | Toggle comment 💬 |
| Alt+W | Close tab ❌ |
| Ctrl+Z / Cmd+Z | Undo ↶ |
| Ctrl+Y / Cmd+Shift+Z | Redo ↷ |
| Enter | Next Search Match (when search open) ⬇️ |
| Shift+Enter | Previous Search Match (when search open) ⬆️ |
| Esc | Close Modal / Search / Quick Switcher ✖️ |
🔧 Installation
This integration is best installed via the [Home Assistant Community Store (HACS).HACS (Recommended) 🛠️
- Add the Custom Repository:
https://github.com/ha-china/blueprint-studio
* Select the category Integration and click Add.
- Install the Integration:
- Restart Home Assistant:
- Add the Integration:
Manual Installation 📥
- Download the latest release from the releases page 📦
- Extract the
blueprint_studiofolder to yourcustom_componentsdirectory 📂 - Restart Home Assistant 🔄
- Go to Settings → Devices & Services → Add Integration → Blueprint Studio ⚙️
⚙️ Configuration
Blueprint Studio requires no configuration! After installation:- The integration will appear in Settings → Devices & Services 📋
- A new "Blueprint Studio" menu item will appear in your Home Assistant sidebar 📂
- Click it to start editing your files 🚀
🚀 Usage
Getting Started 🎓
New in v1.3.0! First-time users are greeted with a guided tour to set up the editor. You can choose to enable Git integration for version control or keep it simple with just the file editor.
Onboarding Wizard - Guided setup with optional Git integration
Opening Files 📂
- Click on any file in the file tree to open it in the editor 🖱️
- Files open in new tabs, allowing you to work with multiple files simultaneously 🗂️
- Use the file search box to quickly find files 🔍
Editing Files ✏️
- Make your changes in the editor 🎨
- Press
Ctrl+S(orCmd+Son Mac) to save 💾 - Use
Ctrl+Shift+Sto save all open files at once 📁
Creating New Files ➕
- Right-click in the file tree where you want to create the file 🖱️
- Select "New File" or "New Folder" 📄
- Enter the name and the file will be created ✨
Uploading Files ⬆️
- Use the upload button in the toolbar 📤
- Drag and drop files directly into the upload dialog 🖱️
- Choose whether to overwrite existing files ❓
Downloading Files ⬇️
- Right-click on a file or folder 🖱️
- Select "Download" 📥
- Folders are downloaded as ZIP files 📦
YAML Validation ✅
- Click the YAML validation button in the toolbar 🔍
- Any syntax errors will be highlighted in red ❌
- Hover over errors to see the error message 💡
Pinning Favorites 📌
- Pin files - Click the pin icon next to any file in the tree to add it to favorites
- Quick access - Pinned files appear at the top of the sidebar for instant access
- Persistent - Your favorites are saved and persist across restarts
- Unpin - Click the pin icon again to remove from favorites
- Visual indicator - Pinned files show an orange pin icon
AI Studio Copilot 🧠
New in v2.5.0! Senior Home Assistant Configuration Expert with advanced intelligence.- Enable in Settings: Go to Settings and toggle "AI Studio Copilot".
- Choose Processing: Use built-in rule-based generation, a Home Assistant conversation agent, a configured local endpoint, or a supported cloud provider. Available model IDs are fetched from the provider rather than fixed by Blueprint Studio.
- Grounded Discovery: Relevant installed entities and actions are selected from the running Home Assistant instance. Unknown references remain explicit instead of being silently invented.
- Intelligent Scene Generation: Create scenes with natural language - "Create a morning scene for bedroom" generates 100% brightness at 4000K cool white. Supports 7 presets: morning, evening, movie, reading, romantic, party, relax.
- Advanced Script Generation: Create multi-step scripts with delays, notifications, and mode detection (single, parallel, restart, queued). Say "Turn on lights, wait 5 minutes, then turn them off."
- Jinja Template Support: Edit
.jinja,.jinja2, and.j2files with syntax validation and error detection. - YAML Error Detection: Automatically detects 7+ common YAML errors (legacy syntax, indentation, missing colons) with line-by-line solutions.
- Multi-File Support: Generate code specifically for
automations.yaml,scripts.yaml, orscenes.yaml. - Reviewed Changes: File edits remain immutable proposals until you inspect the before/after values and explicitly apply them. Stale or unsafe targets are rejected.
📖 See Full Guides: AI_CAPABILITIES.md • SCENE_SCRIPT_GUIDE.md
GitHub Integration 🔗
Sync your Home Assistant configuration with GitHub!
Git Settings - One-click OAuth login or Personal Access Token
Quick Setup (30 seconds) ⚡
OAuth is pre-configured - no setup needed!- Click Git Settings button (GitHub icon in toolbar)
- Click "Login with GitHub OAuth" (recommended)
- Visit the URL shown and enter the code
- Authorize Blueprint Studio
- Done! You're logged in permanently ✅
GitHub OAuth Device Flow - Simple and secure authentication
Or use Personal Access Token (PAT):
- Create token at: https://github.com/settings/tokens
- Enter username and token in Git Settings
- Click "Save Credentials"
Creating a New Repository 🚀
NEW! Create GitHub repositories without leaving Blueprint Studio:- Click Git Settings button
- Click "Create New GitHub Repository" button
- Enter repository details:
- Click "Create Repository"
- Blueprint Studio automatically:
Create GitHub Repository - One-click repo creation
Advanced Management 🛠️
Visual Sync Status & Exclusions
Visual Sync Status - See exactly how many commits to Push (↑) or Pull (↓)
Advanced .gitignore - Manage exclusions with a full interactive file tree
Using Git Features
Git Changes Panel - Stage, commit, and push your changes
- Git Status - Automatically updates when you save, create, delete, or modify files
- Stage Files - Click + icon next to files to stage
- Commit - Write commit message and commit
- Push - Upload changes to GitHub
- Pull - Download changes from GitHub
- Auto-Refresh - Git panel updates automatically every 30 seconds to catch external changes
Complete Workflow - Edit, stage, commit, and push in one place
Your credentials persist across restarts! No need to re-login.
Note: The Git Changes panel appears automatically when you have uncommitted changes and disappears when everything is committed. No manual refresh needed!
📖 Full Guide: See GITHUB_AUTH_QUICKSTART.md for complete instructions.
SFTP & Embedded Terminal 🖥️
Blueprint Studio can manage files outside your Home Assistant config directory through saved SSH/SFTP hosts.- Enable SFTP Integration and SSH (Terminal) Integration in Settings → Integrations
- Add a host with password authentication or a private key
- Browse remote folders from the SFTP sidebar
- Open remote text files in normal editor tabs and save them back over SFTP
- Preview remote media files through secure short-lived stream links
- Use the embedded terminal for local commands or SSH sessions to saved hosts
Gitea Integration 🏠
Use Gitea when you prefer a self-hosted Git server instead of GitHub.- Enable Gitea Integration in Settings → Integrations
- Configure your server URL, username, and token
- Create repositories, add remotes, stage files, commit, pull, push, and recover stuck syncs from the Gitea panel
Developer Tools 🧰
Blueprint Studio includes Home Assistant-aware tools for quick testing while you edit:- Action caller with form and YAML modes
- Template renderer for Jinja testing
- Entity/state browser
- Config check and YAML reload helpers
📄 Supported File Types
| Extension | Language | Icon | |-----------|----------|------| |.yaml, .yml | YAML | 🟡 |
| .json | JSON | 🔵 |
| .py | Python | 🐍 |
| .js | JavaScript | ⚡ |
| .html | HTML | 🌐 |
| .css | CSS | 🎨 |
| .md | Markdown | 📝 |
| .sh | Shell | 🐚 |
| .txt, .log | Plain Text | 📄 |
| .conf, .cfg, .ini | Config | ⚙️ |
| .jinja, .jinja2, .j2 | Jinja2 Template | 📄 |
| .pem, .crt, .key | Certificate/Key | 🔒 |
| .cpp, .h | C++ (ESPHome) | 🇨 |
| .db, .sqlite | Database (Binary) | 🗄️ |
| .bin, .ota, .der | Binary/Firmware | 💾 |
| .tar, .gz, .zip | Archive | 📦 |
🔒 Security
Blueprint Studio includes multiple layers of security protection to keep your HA instance safe:- Path Traversal Protection - Prevents access to files outside your Home Assistant config directory 🚫
- Admin Only Access - Only users with administrator privileges can use the editor 👑
- Allowed File Extensions - Only text-based configuration files can be edited (see Supported File Types) 📄
- Excluded Directories - Sensitive directories like
.storage,deps, and__pycache__are hidden 🕶️ - Protected Files - Critical files like
configuration.yamlandsecrets.yamlcannot be deleted (but can be edited) 🛡️ - Input Validation - All file operations are validated to prevent malicious input 🔍
- Authentication Required - All API endpoints require Home Assistant authentication 🔐
- Always backup your configuration before making major changes 💾
- Use YAML validation before saving configuration files ✅
- Test changes in a development environment when possible 🧪
- Keep regular backups of your Home Assistant configuration 🔄
🛠️ Troubleshooting
Integration doesn't appear in sidebar ❓
- Ensure you've restarted Home Assistant after installation 🔄
- Check that you're logged in as an administrator 👑
- Clear your browser cache and refresh the page 🧹
- Check the Home Assistant logs for any errors 📋
Files not showing in the tree 📂
- Some directories are excluded for security (
.storage,deps,.cache,.git, etc.) 🛡️ - Hidden files (starting with
.) are not shown unless "Show Hidden" is enabled 🕶️ - Only files with supported extensions are displayed 📄
- Empty folders are now visible (v1.2.0+) 📁
- Try clicking the refresh button in the toolbar 🔄
Cannot save files 💾
- Ensure you have write permissions on the config directory 🔑
- Check that the file extension is in the allowed list 📄
- Verify there's enough disk space 💾
- Check the Home Assistant logs for permission errors 📋
YAML validation shows errors ❌
- Review the error message by hovering over the red highlighted area 💡
- Common issues: incorrect indentation, missing colons, unquoted special characters 📝
- Use an online YAML validator for complex debugging 🌐
- Check the Home Assistant documentation for proper YAML syntax 📚
Upload/Download not working ⬆️⬇️
- Check browser console for JavaScript errors 🛠️
- Ensure files are within size limits 📏
- Verify file extensions are allowed 📄
- Try a different browser if issues persist 🌐
GitHub Login / Git Issues 🔗
- Cannot login: Check internet connection to github.com
- Login expired: Device code expires in 15 minutes, try again
- Push/Pull fails: Verify credentials are saved in Git Settings
- Empty Git panel: Click "Git Status" to refresh
- Permission denied: Check your GitHub PAT has
reposcope - Credentials lost after restart: This is fixed in v1.2.0+ with persistent storage
❓ FAQ
Q: Can I edit files outside the Home Assistant config directory? A: Local file editing is restricted to your Home Assistant config directory for security reasons. Remote files can be edited through saved SFTP connections. 🛡️Q: Why can't I see .storage or other hidden directories?
A: These directories are excluded for security. Editing files in .storage can corrupt your Home Assistant installation. ⚠️
Q: Can non-admin users access Blueprint Studio? A: No. Blueprint Studio requires administrator privileges to ensure only trusted users can edit configuration files. 👑
Q: Does Blueprint Studio backup files automatically? A: No. You should maintain your own backup strategy using Home Assistant's backup features or external tools. 💾
Q: Can I use Blueprint Studio on mobile devices? A: Yes, but the experience is optimized for desktop. A larger screen is recommended for editing. 📱
Q: Will my changes take effect immediately? A: Most configuration changes require reloading the affected integration or restarting Home Assistant. Blueprint Studio only saves files, it doesn't reload configurations. 🔄
Q: Can I install multiple instances? A: No. Blueprint Studio allows only one instance per Home Assistant installation. 🔒
Q: Is syntax highlighting available for all file types? A: Yes, for all supported file types listed in the Supported File Types section. 🌈
Q: Can I customize the theme or editor settings? A: Yes! Blueprint Studio v2.2.0+ offers extensive customization:
- 6 Theme Presets: Dark, Light, High Contrast, Solarized Dark, Solarized Light, Ocean, and Dracula
- 8 Accent Colors: Choose your preferred highlight color
- Font Options: Adjust font size (10-24px) and family from 7 popular programming fonts
- Editor Behavior: Toggle word wrap, line numbers, whitespace visibility, and auto-save
- File Tree: Compact mode and icon visibility options
Q: Is the AI Copilot always on? A: No. For privacy and performance, the AI Copilot is disabled by default. You can enable it in the Settings modal when you need help. 🧠
Q: Does autocomplete or validation send my files to an AI provider? A: No. YAML context, autocomplete, and validation remain local. Only an AI request explicitly sent to a Home Assistant agent, configured model endpoint, or cloud provider crosses that provider boundary, using a bounded and redacted excerpt.
Q: Does Blueprint Studio support GitHub integration? A: Yes! Blueprint Studio v1.2.0+ includes full GitHub integration with OAuth Device Flow, persistent credentials, and visual Git operations (stage, commit, push, pull). 🔗
Q: Do I need to re-login to GitHub after Home Assistant restart? A: No! Starting with v1.2.0, credentials persist across restarts. You stay logged in permanently. ✨
Q: Can I see empty folders in the file tree? A: Yes! Starting with v1.2.0, empty folders are now visible in the file explorer. 📁
Q: Which is better: OAuth Device Flow or PAT? A: OAuth Device Flow is recommended for easier setup. Both methods work equally well and persist credentials. See GITHUB_AUTH_QUICKSTART.md for comparison. 🔐
🔍 Technical Details
Blueprint Studio is a Home Assistant custom integration with an admin-only panel, a modular JavaScript frontend, and a domain-split Python backend.Integration Layout
custom_components/blueprint_studio/
├── __init__.py, config_flow.py, const.py, manifest.json
├── backend/
│ ├── api.py # HTTP API orchestrator and upload/stream views
│ ├── api_files.py # Local file CRUD, search, streaming, downloads
│ ├── api_git.py # Git, GitHub, and Gitea actions
│ ├── api_misc.py # Settings, HA metadata, syntax checks, reloads, AI actions
│ ├── api_sftp.py # SFTP dispatcher and remote streaming
│ ├── api_terminal.py # Terminal command API
│ ├── file_manager.py # Safe local filesystem operations
│ ├── git_manager.py # Repository, credentials, remotes, branches, conflicts
│ ├── sftp_manager.py # Paramiko-backed remote filesystem operations
│ ├── terminal_manager.py # Embedded terminal session management
│ ├── ai_*.py # AI providers, generators, NLP, and validators
│ ├── websocket.py # Update/settings websocket subscriptions
│ └── zip_utils.py # Streaming ZIP helpers
└── www/
├── modules/ # Frontend ES modules
├── styles/modules/ # Split CSS modules
└── vendor/ # Bundled CodeMirror, xterm.js, PDF.js, Prettier, etc.
Frontend Modules
- Boot and state -
main.js,initialization.js,app.js,state.js,constants.js,event-bus.js,translations.js - Editor experience -
editor.js,tabs.js,split-view.js,minimap.js,search.js,global-search.js,command-palette.js,ha-autocomplete.js,editorconfig.js,status-bar.js - File UI -
file-tree.js,file-operations.js,file-operations-ui.js,downloads-uploads.js,zip-progress.js,asset-preview.js,favorites.js,recent-files.js,breadcrumb.js,context-menu.js,selection.js,sidebar.js,toolbar.js - Integrations -
git.js,git-operations.js,git-ui.js,git-diff.js,github-integration.js,gitea-integration.js,gitea-ui.js,sftp.js,terminal.js,ai-ui.js,dev-tools.js - Settings and coordination -
settings.js,settings-ui.js,settings-sync.js, plus coordinator modules for files, Git, SFTP, terminal, dialogs, settings, and UI
Backend API Surface
/api/blueprint_studiohandles authenticated JSON actions for files, Git/GitHub/Gitea, SFTP, terminal, AI, settings, Home Assistant metadata, config checks, template rendering, and service calls/api/blueprint_studio/uploadstreams large multipart uploads to local storage or SFTP without relying on Home Assistant's default request size limit/api/blueprint_studio/streamserves token-protected file, folder ZIP, search, and SFTP media streams for browser downloads/previews- WebSocket commands publish file update and settings change events to keep multiple tabs and the PWA in sync
Security Model
- The panel and backend API require Home Assistant authentication and administrator privileges
- Local paths are resolved through safe-path helpers to prevent traversal outside the configured root
- Streaming endpoints use Home Assistant access tokens or short-lived opaque stream IDs so remote credentials are not exposed in URLs
- Dangerous operations such as hard reset, force push, delete, service calls, template rendering, and Home Assistant restart are explicitly admin-gated
🤝 Contributing
Contributions are welcome! Here's how you can help: 🌍Reporting Issues 🐛
- Check existing issues before creating a new one 🔍
- Include Home Assistant version, browser, and OS information 📋
- Provide steps to reproduce the problem 📝
- Include relevant log entries if available 📄
Pull Requests 🔄
- Fork the repository 🍴
- Create a feature branch (
git checkout -b feature/amazing-feature) 🌿 - Make your changes ✏️
- Test thoroughly with Home Assistant 🧪
- Commit your changes (
git commit -m 'Add amazing feature') 💾 - Push to the branch (
git push origin feature/amazing-feature) 🚀 - Open a Pull Request 📤
Development Setup 🛠️
- Clone the repository into your Home Assistant's
custom_componentsdirectory 📥 - Restart Home Assistant 🔄
- Make changes to the code ✏️
- Restart Home Assistant to test changes 🔄
- Check the Home Assistant logs for any errors 📋
Code Style 📐
- Follow PEP 8 for Python code 🐍
- Use type hints where appropriate 💡
- Add comments for complex logic 📝
- Test all file operations thoroughly 🧪
📞 Support
If you encounter any issues or have feature requests:- Open an issue on GitHub Issues 🐛
- Provide as much detail as possible 📝
- Check existing issues first to avoid duplicates 🔍
📄 License
This project is licensed under the MIT License - see the LICENSE file for details. 📜🙌 Acknowledgments
Blueprint Studio is built with and inspired by:- CodeMirror - The powerful code editor that powers the editing experience 💻
- Material Icons - Beautiful icons for file types and UI elements 🎨
- VS Code - Design inspiration for the interface and user experience 🌟
- Home Assistant Community - For feedback, testing, and feature suggestions 👏
⚖️ Comparison with Other Solutions
| Feature | Blueprint Studio | File Editor (Official) | Studio Code Server | SSH/SFTP | Configurator | |---------|------------------|------------------------|--------------------|----------|--------------| | Installation | HACS/Custom Component | Add-on | Add-on | External Client | Deprecated | | Interface | VS Code-like, Multi-tab | Simple, Single-file | Full VS Code | Terminal | Basic | | Resource Usage | Lightweight | Low | High | Minimal | Low | | Security | Built-in Restrictions | Basic | Full Access | Full Access | None | | File Management | Full (Upload/Download/ZIP) | Basic | Full | Full | Limited | | Maintenance | Active | Official | Community | N/A | Deprecated |Support the Project
This integration is developed and maintained in spare time and is provided free to the Home Assistant community.
If you find it useful and would like to support ongoing development, maintenance, and improvements, any contribution is appreciated — but never required ❤️
Ways to Support
- Ko-fi
- PayPal
- Alipay
- Bitcoin (BTC)
bc1qvu8a9gdy3dcxa94jge7d3rd7claapsydjsjxn0
- Solana (SOL)
4jvCR2YFQLqguoyz9qAMPzVbaEcDsG5nzRHFG8SeaeBK
You can also help by:
- Reporting bugs
- Submitting pull requests
- Suggesting features
- Helping other users
- Starring the repository ⭐
⭐ Star History
If you find Blueprint Studio useful, please consider giving it a star on GitHub! 🌟Maintained by HA China
MIT License • Report Bug • Update Changelog