Skip to main content

🧪 Development Branch Guide

Want to try the latest features before they're officially released? The dev branch contains cutting-edge improvements and experimental features that will eventually make it to the main release.

Experimental Software

The dev branch is experimental and may contain bugs, incomplete features, or breaking changes. Use it only if you're comfortable with potential instability and want to help improve Libre WebUI.

🎯 What is the Dev Branch?​

The development branch (dev) is where new features are tested before being merged into the stable main branch. It includes:

  • Latest features not yet in stable releases
  • Bug fixes being tested
  • Experimental improvements to the UI and functionality
  • Performance optimizations under development

🚀 How to Use the Dev Branch​

The standard development image is suitable for Chat and the rest of Libre WebUI, but it does not include the Docker CLI or mount the host Docker socket. It therefore cannot exercise the new Work runtime by default. Use the from-source setup below when testing Work, with Docker available to the native backend process.

With External Ollama:

# Clone the repository
git clone https://github.com/libre-webui/libre-webui.git
cd libre-webui

# Switch to dev branch
git checkout dev

# Start the dev image with external Ollama
docker compose -f docker-compose.dev.external-ollama.yml up -d

Simple Docker:

# Use the dev branch image
docker run -d -p 3000:8080 -v libre-webui:/app/backend/data --name libre-webui-dev --restart always ghcr.io/libre-webui/libre-webui:dev

From Source​

# Clone and switch to dev branch
git clone https://github.com/libre-webui/libre-webui.git
cd libre-webui
git checkout dev

# Install dependencies
npm install

# Start development server
npm run dev

Testing Work​

  1. Start Docker and confirm docker info succeeds as the same user running the backend.
  2. Start Libre WebUI from source with npm run dev.
  3. Sign in as an administrator.
  4. Select Work and use a tool-capable Ollama, Ollama Cloud, or configured plugin-backed model.

Run the focused backend provider and container-policy tests with:

npm run test:work

The tests validate the generated Docker policy, path containment, lifecycle and capacity behavior, and OpenAI-compatible, Anthropic, and Gemini tool adapters. See Work: Isolated Workspaces for the full runtime boundary.

🔄 Staying Updated​

The dev branch is updated frequently. To get the latest changes:

# Update your local dev branch
git pull origin dev

# Refresh the dev Compose stack
docker compose -f docker-compose.dev.external-ollama.yml pull
docker compose -f docker-compose.dev.external-ollama.yml up -d

# Or restart simple Docker
docker pull ghcr.io/libre-webui/libre-webui:dev
docker stop libre-webui-dev && docker rm libre-webui-dev
docker run -d -p 3000:8080 -v libre-webui:/app/backend/data --name libre-webui-dev --restart always ghcr.io/libre-webui/libre-webui:dev

🐛 Found a Bug? Help Us Improve!​

Your bug reports are incredibly valuable! Here's how to report issues effectively:

Before Reporting​

  1. Check existing issues: Search GitHub Issues to avoid duplicates
  2. Try the stable version: Confirm the bug exists only in dev (not in main branch)
  3. Reproduce consistently: Can you make the bug happen again?

How to Report Bugs​

🐛 Report a Bug on GitHub

Include this information:

**Environment:**

- Branch: dev
- Version: [git commit hash or date]
- OS: [Windows/macOS/Linux]
- Browser: [Chrome/Firefox/Safari version]
- Setup: [Docker/Source/etc.]
- Docker: [version and whether `docker info` succeeds, for Work issues]
- Work model/provider: [exact route, when applicable]

**Bug Description:**
Clear description of what went wrong

**Steps to Reproduce:**

1. Go to...
2. Click on...
3. See error...

**Expected Behavior:**
What should have happened

**Actual Behavior:**
What actually happened

**Screenshots/Logs:**
[If applicable, add screenshots or error logs]

**Work Activity:**
[Relevant tool call/result or preview output, with secrets removed]

Get Your Git Commit Hash​

# Find your current dev branch commit
git rev-parse HEAD

# Or get a short version
git rev-parse --short HEAD

🏆 Contributing & Recognition​

Using the dev branch makes you part of our testing community! Contributors are recognized in several ways:

Recognition for Contributors​

  • Listed in CONTRIBUTORS.md
  • Mentioned in release notes for significant contributions
  • Co-author attribution in commit messages
  • Special thanks in project announcements

Current Contributors​

Our amazing community includes:

  • rob - Project Maintainer
  • jm - Network Access Enhancement
  • And more contributors! Check the full list

Want to Contribute Code?​

  1. Fork the repository
  2. Create a feature branch from dev: git checkout -b feature/amazing-feature dev
  3. Make your changes
  4. Submit a Pull Request against the dev branch

See our Contributing Guidelines for detailed instructions and our Community Charter for the project's ethical guidelines and governance model.

⚠️ Important Notes​

Data Safety​

  • Backup your data before switching to dev branch
  • Work task files live in separate libre-work-* Docker named volumes. Back those up separately from the SQLite data directory before testing destructive task or user lifecycle changes.
  • Use a separate Docker volume for dev testing: 
    # Use different volume name for dev
    docker run -d -p 3000:8080 -v libre-webui-dev:/app/backend/data --name libre-webui-dev ghcr.io/libre-webui/libre-webui:dev

Potential Issues​

  • Breaking changes may require configuration updates
  • Features may be incomplete or change without notice
  • Performance may vary as optimizations are tested
  • UI elements might look different or behave unexpectedly

When to Use Stable​

Switch back to the stable main branch if you:

  • Need reliability for important work
  • Experience too many bugs
  • Want a tested, stable experience
# Switch back to stable
git checkout main
docker compose -f docker-compose.external-ollama.yml pull
docker compose -f docker-compose.external-ollama.yml up -d

🌟 Join the Community​

Ready to help shape the future of Libre WebUI? 🚀

Your testing, feedback, and contributions on the dev branch directly improve the experience for all users. Thank you for being part of our development community!