ATLAS File Studio

The interface language selector includes French. In this release, French covers the main header and toolbar controls plus upload-limit notices; deeper file dialogs and workflow messages still need full localization.

ATLAS File Studio is the second independent ATLAS plugin. It is intended to edit files in approved Home Assistant paths without allowing free root access by default.

Trash and history across App updates

From ATLAS 0.1.312, backend-managed stores default to ATLAS_PLUGIN_DATA_ROOT/.file-studio/{trash,history}. Docker must retain the plugin-data volume; the HA App uses /data/atlas-plugins. Existing Linux installer paths and ATLAS_FILE_STUDIO_TRASH_ROOT / ATLAS_FILE_STUDIO_HISTORY_ROOT overrides remain valid. Custom paths also need persistent mounts and backups.

First upgrade from an older container: Back up its old trash/history folders and persistent data first. Pause File Studio writes until the update. Copy the standalone helper from the reviewed ATLAS release into the still-existing old container:

docker cp scripts/atlas-file-studio-retention.mjs OLD_CONTAINER:/tmp/atlas-file-studio-retention.mjs
docker exec OLD_CONTAINER node /tmp/atlas-file-studio-retention.mjs --app-root /app --plugin-root /data/atlas-plugins

These paths apply to the standard image; check custom installations. For the HA App, run the same helper in its existing App terminal before updating. It adopts accessible legacy stores once, retains sources/entry IDs and refuses differing destination files. Review conflicts using the backup. After success, back up the persistent store too, then replace the container. A migration marker prevents restored entries from being imported again on restart.

Files already discarded with an old container still require an existing backup. After isolated qualification, the 0.1.311 to 0.1.312 update was also verified on Proxmox and Pi 5 on 2026-10-16: fresh HA backups, migration inside the old container and PC backups of both old and prepared stores first. Both original trash entries and all twelve history files survive on each host, together with settings, active files, projects and plugins. This is not a full HAOS backup restoration test.

A separate full HAOS restore was subsequently verified with owned test data: save the encrypted full backup on the PC, upload it to a fresh Hyper-V HAOS instance and restore through Supervisor. Settings, project, six plugins, trash, history and 154 checked files survive. The test address was retained; Pi 5 and Proxmox remain untouched. A second fresh HAOS target was also verified at a different IP address: all154 files and existing credentials survive. Stored addresses are not rewritten automatically. After restoration, change only the Home Assistant URL in the ATLAS App configuration and restart the App. Under Settings → Devices & services → ATLAS Runtime → Configure, enter the new Runtime address including port 4176. The existing HA token does not need replacement in this qualified full restore. Plugin links automatically use the new ATLAS address. Then check connectivity, projects, trash and history.

These isolated checks do not replace recovery testing of a production backup on different hardware; ARM64 and physical devices remain separate qualification.

Repository

• GitHub: https://github.com/rockbaer2007/atlas-file-studio-plugin
• Install page: https://rockbaer2007.github.io/atlas-file-studio-plugin/install.html
• Repository file: https://raw.githubusercontent.com/rockbaer2007/atlas-file-studio-plugin/main/repository.json

Current State

File Studio is published as an installable ATLAS plugin and can be tested through the demo repository in Administration and Hub.

• current plugin version: 0.1.52
• French UI coverage: DE/EN/FR selector, header, main toolbar controls and upload-limit notices; dialogs and other workflow messages are not fully translated yet
• upload limit: files up to 64 MiB can be uploaded directly; larger files are directed to the Samba add-on
• documented Home Assistant App/Add-on version: 0.1.312 (2026-10-16)
• image preview: open SVG, PNG, JPG/JPEG and WebP files directly in the separately installed ATLAS Icon Studio. Raster files open as previews; simple SVG path files import into its monochrome icon set.
• The handoff uses a short-lived browser-local key and File Studio's approved file access. Both plugins must be installed on the same ATLAS server; the file is not uploaded or duplicated.
• file tree for the approved /config area
• flexible two-column surface with optional maximum width and height limits
• compact toolbar below Dateibaum /config, keeping icons out of the right file list in narrower layouts
• file and folder actions next to the path: create file, create folder, refresh and collapse all folders
• editor surface with a locally bundled CodeMirror 6 editor
• large files scroll inside the editor surface so the lower status row stays visible
• direct links open files even when they are deeper than the initially loaded file tree, for example Automation Exporter outputs
• syntax highlighting for YAML, JSON, JavaScript, TypeScript and Markdown
• YAML validation before saving with Home Assistant hints for common files such as configuration.yaml, automations.yaml, scripts.yaml and packages, including common root keys, automation/script structure and directly entered secret values
• save the currently opened file
• automatic backups before saving, a history list of recent backups, comparison with the current state and restore of a selected backup
• save locally, drag-and-drop upload, multi-file upload and download
• uploads are saved in the currently selected folder
• the file tree refreshes after upload without automatically opening the uploaded file
• download names are counted up in the browser, for example configuration.yaml, configuration-1.yaml, configuration-2.yaml
• upload conflicts can be replaced, renamed or cancelled in a File Studio dialog
• multi-select delete, copy and move actions
• trash restore instead of immediate permanent deletion; the right-side toolbar icon is gray when empty and red when entries exist
• favorites bar for frequently used files and folders
• colored file-type icons with compact type badges
• search with type filters, optional content search, matching line and content preview
• opt-in problem report in a File Studio dialog with preview and a prepared GitHub issue link; the report does not include Home Assistant tokens, provider API keys or file contents
• upload files up to 64 MiB directly to an approved destination folder using a binary transfer instead of Base64 JSON
• stop uploads above that limit before transfer and direct users to the Home Assistant Samba add-on
• ZIP, TAR, TAR.GZ and TGZ content preview
• extract individual files directly from an archive preview without unpacking the entire archive
• extract complete TAR archives with path validation and per-file and total size limits
• /config as default root
• additional path approvals for www, custom_components, addons and parent-of-config
• compact access notice in smaller, regular-weight text; each approved path has a distinct color for easier scanning
• add-on directory only after Administration or Add-on approval
• no free root access by default

The editor library is shipped with the plugin. File Studio therefore does not need a CDN for the code editor and remains traceably versioned in the Home Assistant add-on runtime.

Security Model

Version consistency from 0.1.52

Catalog, manifest, package and embedded manifest all report 0.1.52. The builder now synchronizes the catalog; a read-only CI check detects stale artifacts before publication. The previous catalog 0.1.50/package 0.1.51 mismatch is fixed without UI or data-format changes. Update, package recovery, re-update and restart pass in isolation with test settings, files, project, another plugin, trash and history preserved. Native checks followed on 2026-10-16 after fresh local HA backups: Proxmox 0.1.50 → 0.1.52 → 0.1.50 → 0.1.52, Pi 5 0.1.51 → 0.1.52 → 0.1.51 → 0.1.52. Guarded Administration recovery and another repository update passed on ATLAS 0.1.312 with HA 2026.10.1. Existing files, projects, other plugins, trash and history were preserved; the file editor and YAML basic validation worked. No App/HA restart was needed. This is not a complete HA restore test.

The first plugin contract describes a fixed access policy:

Path	Default	Approval
/config	active	no additional approval
/config/www	visible as capability	through Atlas Administration or Add-on option
/config/custom_components	visible as capability	through Atlas Administration or Add-on option
/addons	disabled	through Atlas Administration or Add-on option
parent-of-config	disabled	only through deliberate admin approval
/	disabled	not allowed by default

/config is the normal Home Assistant configuration area. It contains files such as configuration.yaml, automations.yaml, dashboards, themes, blueprints, scripts and local web files under www.

/addons is used for local Home Assistant add-ons. It can contain custom add-on folders with files such as config.yaml, Dockerfile, startup scripts, icons and documentation. Because changes there can directly affect installable add-ons, File Studio keeps this area locked by default and only shows it after explicit approval in Atlas Administration.

In Home Assistant App/Add-on mode, these approvals come from the Add-on configuration. In Docker or Linux installs, Atlas Administration controls the same file capabilities. Plugins receive approved path context only, not raw long-lived secrets.

Home Assistant Update Note

Every visible ATLAS update bumps the Home Assistant App/Add-on version. Home Assistant compares the installed version (old) with the repository version (target). This documented App version is 0.1.312. If Home Assistant still shows an older target version, reload repository information in the App/Add-on Store and then update or restart ATLAS. The independently released HACS integration remains 0.1.306.

The plugin and the ATLAS app have separate versions. Documentation changes do not modify Home Assistant files.

Next Expansion Steps

• further Home Assistant YAML assistance, for example real schema/service checks against a connected Home Assistant instance
• optional RAR support, including RAR5, if a freely usable backend is available
• saving icon SVGs under /config/www/custom_local_icons/ when the matching Home Assistant integration is used
• show a switch between /config and the Automation Exporter output folder when ATLAS Automation Exporter / Editor is installed