Skip to content

aboylabs/ai-agent-skills / skills/creative/drawio-headless

drawio-headless

Verified

Generate 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:

  1. Create .drawio XML programmatically (Python, script, template)
  2. Export via xvfb-run in execute_code or terminal tool
  3. Return path via MEDIA:/path/to/diagram.png for Telegram
  4. 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 diagrams
  • references/electricity-consumption-analysis.md — Household/office electricity analysis with AC-focused breakdown and savings scenarios

See Also

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall