Philosophy & Motivation

runnem was born from a simple philosophy: development tools should be lightweight, straightforward, and get out of your way.

Core Principles

1. Keep It Simple

• Uses screen for process management - a battle-tested, reliable Unix tool
• No complex containerization required
• Run services directly in your development environment
• Easy to understand what's happening under the hood

2. Developer-First Experience

• Start services with a single command
• View logs easily with native screen commands
• Quick project switching without container overhead
• Maintain your usual development workflow

3. Flexibility Over Rigidity

• Run services however you want (npm, poetry, docker, etc.)
• Mix and match different types of services
• No forced containerization
• Use Docker only when it makes sense for your service

Why Not Docker for Everything?

While Docker is an excellent tool, it's not always the best choice for local development:

1. Development Speed

   • No container build times
   • Instant code reloading
   • Native performance
   • Direct access to local tools

2. Resource Efficiency

   • Lower memory usage
   • Less CPU overhead
   • Faster startup times
   • No container layer overhead

3. Debugging Simplicity

   • Direct access to processes
   • Native debugging tools
   • Clear log output
   • No container abstraction layer

Real-World Use Case

Here's a typical development scenario that inspired runnem:

services:
  api:
    command: cd ~/projects/myapp/api && poetry run uvicorn main:app --reload
    url: http://localhost:3000

  frontend:
    command: cd ~/projects/myapp/frontend && npm run dev
    url: http://localhost:3001
    depends_on: ["api"]

  worker:
    command: cd ~/projects/myapp/worker && poetry run python worker.py
    depends_on: ["api"]

With this setup, you can:

1. Start everything with runnem up
2. View logs with runnem log api
3. Switch to another project easily
4. No containers, no overhead, just your code running natively

Multiple Projects Support

One of the key motivations was handling multiple projects efficiently:

• Switch between projects seamlessly
• Prevent port conflicts automatically
• Keep project services isolated
• Remember how to run each project

When to Use Docker

runnem doesn't prevent you from using Docker - it encourages using the right tool for the job:

services:
  # Use Docker for databases or complex dependencies
  postgres:
    command: cd ~/projects/myapp/db && docker-compose up
    url: postgresql://localhost:5432

  # Run development services natively for better performance
  api:
    command: npm run dev
    url: http://localhost:3000
    depends_on: ["postgres"]