Menu
Generate architecture diagrams with draw.io in headless/server environments (WSL2, VPS, Docker)
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.
Tests in real browsers. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data via Chrome DevTools MCP.
Automates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies.
Conducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensions before it enters the main branch.
Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity.
Optimizes agent context setup. Use when starting a new session, when agent output quality degrades, when switching between tasks, or when you need to configure rules files and context for a project.
| name | drawio-headless |
| description | Generate architecture diagrams with draw.io in headless/server environments (WSL2, VPS, Docker) |
| version | 1.0.0 |
| dependencies | ["draw.io desktop (snap or .deb)","xvfb (X virtual framebuffer)"] |
| platforms | ["linux"] |
| tags | ["diagrams","architecture","visualization","headless","wsl2"] |
| origin | unknown |
| source_license | see upstream |
| language | en |
Generate professional architecture diagrams from .drawio XML files in headless environments (WSL2, VPS, Docker) where GUI is not available.
Required packages:
# Install draw.io (snap - easiest)
sudo snap install drawio
# Install Xvfb (virtual framebuffer for headless rendering)
sudo apt-get update
sudo apt-get install -y xvfb
Alternative: .deb package
# Download latest .deb
wget https://github.com/jgraph/drawio-desktop/releases/download/v28.2.5/drawio-amd64-28.2.5.deb
# Install
sudo dpkg -i drawio-amd64-28.2.5.deb
sudo apt-get install -f # Fix dependencies
# Check draw.io installation
which drawio
# Expected: /snap/bin/drawio or /usr/bin/drawio
# Test with xvfb-run
xvfb-run -a drawio --version
# Expected: draw.io version number (e.g., 28.2.5)
# Export .drawio to PNG
xvfb-run -a drawio -x -f png -o output.png input.drawio
# Export to SVG
xvfb-run -a drawio -x -f svg -o output.svg input.drawio
# Export to PDF
xvfb-run -a drawio -x -f pdf -o output.pdf input.drawio
xvfb-run -a — Run in virtual framebuffer (headless)-x — Export mode-f <format> — Output format (png, svg, pdf, jpg)-o <output> — Output file path<input> — Input .drawio fileProblem: Snap-installed draw.io cannot access /tmp or arbitrary directories due to confinement.
Solution: Use home directory or snap-accessible paths:
# ❌ FAILS (snap cannot access /tmp)
xvfb-run -a drawio -x -f png -o /tmp/diagram.png /tmp/input.drawio
# ✅ WORKS (home directory accessible)
cd ~/diagrams
xvfb-run -a drawio -x -f png -o diagram.png input.drawio
Snap-accessible paths:
~/ (home directory)/home/<user>//media/ (removable media)/mnt/ (mounted filesystems)Symptoms: Errors like:
libGL error: No matching fbConfigs or visuals found
dbus[]: Failed to connect to socket
Impact: These are warnings only — export still succeeds. Safe to ignore in headless environments.
Suppress (optional):
xvfb-run -a drawio -x -f png -o output.png input.drawio 2>/dev/null
Symptom:
Error: Cannot open display: :99
Fix:
sudo apt-get install -y xvfb
Problem: Complex diagrams with many elements may consume significant memory.
Solution: Monitor memory usage, increase if needed:
# Check available memory before export
free -h
# For very large diagrams, consider SVG (vector, smaller memory footprint)
xvfb-run -a drawio -x -f svg -o output.svg input.drawio
Problem: Deleting diagram files immediately after generation but before user confirms receipt.
Symptom: User reports "diagram not received" but files already deleted.
Root cause: Telegram/messaging platforms may have delivery lag. Deleting before send confirmation = data loss.
Solution:
# ❌ WRONG — Delete immediately after MEDIA: path returned
xvfb-run -a drawio -x -f png -o diagram.png diagram.drawio
echo "MEDIA:/path/to/diagram.png"
rm diagram.png diagram.drawio # TOO EARLY!
# ✅ CORRECT — Keep files, cleanup weekly
xvfb-run -a drawio -x -f png -o ~/diagrams/analysis_$(date +%Y%m%d).png diagram.drawio
echo "MEDIA:~/diagrams/analysis_20260505.png"
# Files remain for user reference
# Weekly cleanup (manual or cron)
find ~/diagrams -name "*.png" -mtime +7 -delete
Policy: Never auto-delete diagrams after sending. User may need to reference them later or delivery may fail silently.
<mxfile host="app.diagrams.net">
<diagram name="Example">
<mxGraphModel dx="1200" dy="900">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<!-- Add your diagram elements here -->
<mxCell id="box1" value="Service A"
style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;"
vertex="1" parent="1">
<mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
xvfb-run -a drawio -x -f png -o diagram.png diagram.drawio
ls -lh diagram.png
file diagram.png
# Expected: PNG image data, ...
When generating diagrams in Hermes workflows:
MEDIA:/path/to/diagram.png for TelegramTypical export times:
Memory usage:
Cause: Invalid XML structure or missing geometry.
Fix: Validate .drawio XML structure, ensure all cells have geometry.
Cause: Snap bin directory not in PATH.
Fix:
# Add to ~/.bashrc
export PATH="/snap/bin:$PATH"
# Or use full path
xvfb-run -a /snap/bin/drawio -x -f png -o output.png input.drawio
Cause: Output directory not writable or snap confinement.
Fix: Use home directory or check permissions:
# Use home directory
cd ~/diagrams
# Or check permissions
ls -ld /path/to/output/directory
references/system-services-diagram-pattern.md — Pattern for mapping running services to comprehensive diagramsreferences/electricity-consumption-analysis.md — Household/office electricity analysis with AC-focused breakdown and savings scenariosarchitecture-diagram skill — Dark-themed SVG architecture diagrams as HTMLexcalidraw skill — Hand-drawn style diagrams (JSON format)