aboylabs/ai-agent-skills / skills/creative/drawio-headless
drawio-headless
VerifiedGenerate architecture diagrams with draw.io in headless/server environments (WSL2, VPS, Docker)
Draw.io Headless Diagram Generation
Generate professional architecture diagrams from .drawio XML files in headless environments (WSL2, VPS, Docker) where GUI is not available.
When to Use
- Server/VPS without X11 display
- WSL2 Ubuntu (no native GUI)
- Docker containers
- CI/CD pipelines
- Automated diagram generation
Prerequisites
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
Verification
# 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)
Usage
Basic Export
# 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
Flags Explained
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 file
Pitfalls
1. Snap Confinement (File Access)
Problem: 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)
2. OpenGL/dbus Warnings
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
3. Missing Xvfb
Symptom:
Error: Cannot open display: :99
Fix:
sudo apt-get install -y xvfb
4. Large Diagrams (Memory)
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
5. Premature Deletion (CRITICAL)
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.
Diagram Types Supported
- Architecture diagrams (microservices, cloud, infrastructure)
- Flowcharts (process flows, decision trees)
- Sequence diagrams (API calls, interactions)
- Network diagrams (topology, connections)
- ER diagrams (database schemas)
- UML diagrams (class, component, deployment)
Example Workflow
1. Create .drawio XML
<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>
2. Export to PNG
xvfb-run -a drawio -x -f png -o diagram.png diagram.drawio
3. Verify Output
ls -lh diagram.png
file diagram.png
# Expected: PNG image data, ...
Integration with Hermes
When generating diagrams in Hermes workflows:
- Create .drawio XML programmatically (Python, script, template)
- Export via xvfb-run in execute_code or terminal tool
- Return path via
MEDIA:/path/to/diagram.pngfor Telegram - DO NOT auto-delete — Keep diagrams for user reference (cleanup weekly, not per-send)
Performance
Typical export times:
- Simple diagram (5-10 elements): 2-3 seconds
- Medium diagram (20-50 elements): 4-6 seconds
- Complex diagram (100+ elements): 8-12 seconds
Memory usage:
- draw.io process: ~100-200 MB during export
- Xvfb overhead: ~10-20 MB
Troubleshooting
Export produces blank/empty PNG
Cause: Invalid XML structure or missing geometry.
Fix: Validate .drawio XML structure, ensure all cells have geometry.
"Command not found: drawio"
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
Permission denied
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
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 scenarios
See Also
architecture-diagramskill — Dark-themed SVG architecture diagrams as HTMLexcalidrawskill — Hand-drawn style diagrams (JSON format)- draw.io GitHub: https://github.com/jgraph/drawio-desktop
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |