Configuration

DevAll uses JSONC (JSON with comments and trailing commas) for configuration. This guide covers all available options and best practices.

Configuration Files

DevAll looks for configuration files in this priority order:

1. devall.local.jsonc - Personal overrides (add to .gitignore)
2. devall.local.json - Personal overrides (JSON format)
3. devall.json - Team config (JSON format)
4. devall.jsonc - Team config (JSONC format, recommended)

You can also specify a custom config file:

devall path/to/custom-config.jsonc

Configuration Schema

Dashboard Configuration

{
  "dashboard": {
    "port": 7777,        // Dashboard web interface port
    "open": true         // Auto-open browser on start
  }
}

Service Configuration

Each service in the services array supports these options:

{
  "services": [
    {
      // Required
      "name": "My Service",        // Display name
      "command": "npm",            // Executable to run

      // Optional
      "args": ["run", "dev"],      // Command arguments
      "cwd": "./backend",          // Working directory (relative to config file)
      "port": 3000,                // Service port (set as PORT env var)
      "autostart": true,           // Start automatically on dashboard launch
      "watchFiles": true,          // Watch for file changes and restart
      "stealPort": true,           // Kill processes on port before starting
      "secondary": false,          // Hide by default (show via UI toggle)
      "background": false,         // Run silently without UI display
      "env": {                     // Additional environment variables
        "NODE_ENV": "development",
        "DEBUG": "*"
      }
    }
  ]
}

Configuration Options Explained

name (required)

Display name shown in the dashboard UI.

"name": "Frontend Dev Server"

command (required)

The executable or command to run. Can be:

• Package manager commands: npm, yarn, pnpm
• Direct executables: node, python, go
• System commands: redis-server, postgres
• Relative paths: ./scripts/start.sh

"command": "npm"

args (optional)

Array of arguments passed to the command.

"args": ["run", "dev"]
// Executes: npm run dev

cwd (optional)

Working directory for the command, relative to the config file location.

"cwd": "./services/api"

port (optional but recommended)

The port your service listens on. DevAll will:

• Set it as the PORT environment variable
• Monitor it for the service status
• Optionally steal it if stealPort is enabled

"port": 3000

autostart (optional, default: false)

Whether to start the service automatically when DevAll launches.

"autostart": true  // Start on dashboard launch

watchFiles (optional, default: true)

Whether to watch files and auto-restart the service on changes.

• Watches: src/, lib/, *.js, *.json
• Works with nodemon (detects restarts automatically)
• Set to false to disable

"watchFiles": false  // Disable file watching

stealPort (optional, default: false)

Automatically kill any process occupying the service’s port before starting.

How it works:

• macOS/Linux: Uses lsof -ti:PORT | xargs kill -9
• Windows: Uses netstat + taskkill

"stealPort": true  // Reclaim port before starting

Use case: Useful when development servers crash without releasing ports.

secondary (optional, default: false)

Hide the service by default in the UI. Users can toggle visibility via the header.

"secondary": true  // Hidden by default, can be shown

Use case: Utility services that don’t need constant monitoring (databases, cache servers).

background (optional, default: false)

Run the service silently without displaying it in the UI at all.

"background": true  // Runs invisibly

Use case: Essential background services that should always run (Redis, message queues).

env (optional)

Additional environment variables for the service.

"env": {
  "NODE_ENV": "development",
  "DEBUG": "express:*",
  "API_URL": "http://localhost:8080"
}

Note: The PORT environment variable is automatically set from the port field.

Icon Mappings (optional)

Customize service icons by type:

{
  "icons": {
    "react": "⚛️",
    "vue": "💚",
    "node": "🟢",
    "python": "🐍",
    "database": "🗄️"
  }
}

Then reference in services:

{
  "name": "React App",
  "type": "react",  // Uses ⚛️ icon
  "command": "npm",
  "args": ["start"]
}

Complete Example

Here’s a full-featured configuration for a microservices project:

{
  "dashboard": {
    "port": 7777,
    "open": true
  },
  "services": [
    // Primary services (always visible)
    {
      "name": "Frontend",
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "./apps/web",
      "port": 3000,
      "autostart": true,
      "stealPort": true,
      "env": {
        "VITE_API_URL": "http://localhost:8080"
      }
    },
    {
      "name": "API Gateway",
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "./services/gateway",
      "port": 8080,
      "autostart": true,
      "watchFiles": true
    },

    // Secondary services (hidden by default)
    {
      "name": "Auth Service",
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "./services/auth",
      "port": 3001,
      "autostart": true,
      "secondary": true
    },
    {
      "name": "User Service",
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "./services/users",
      "port": 3002,
      "autostart": true,
      "secondary": true
    },

    // Background services (invisible)
    {
      "name": "Redis",
      "command": "redis-server",
      "port": 6379,
      "autostart": true,
      "background": true,
      "watchFiles": false
    },
    {
      "name": "PostgreSQL",
      "command": "postgres",
      "args": ["-D", "data"],
      "port": 5432,
      "autostart": true,
      "background": true,
      "watchFiles": false
    }
  ],
  "icons": {
    "frontend": "⚛️",
    "api": "🚀",
    "database": "🗄️"
  }
}

CLI Arguments

Custom Config File

devall my-config.jsonc

Disable Browser Auto-Open

devall --no-open

Or in config:

{
  "dashboard": {
    "open": false
  }
}

Best Practices

1. Use Local Overrides

Keep team config in devall.jsonc and personal settings in devall.local.jsonc:

// devall.jsonc (team config, committed)
{
  "services": [
    {
      "name": "Frontend",
      "command": "npm",
      "args": ["run", "dev"],
      "port": 3000
    }
  ]
}

// devall.local.jsonc (personal overrides, gitignored)
{
  "dashboard": {
    "port": 8888,  // Use different port locally
    "open": false  // Don't auto-open browser
  },
  "services": [
    {
      "name": "Frontend",
      "port": 4000  // Override port
    }
  ]
}

2. Enable Port Stealing for Dev Servers

Development servers often leave ports occupied after crashes:

{
  "port": 3000,
  "stealPort": true  // Always reclaim the port
}

3. Organize Services by Visibility

• Primary: Core services you monitor constantly (autostart: true)
• Secondary: Utility services you check occasionally (secondary: true)
• Background: Infrastructure that should just run (background: true)

4. Set Appropriate Working Directories

Use relative paths from the config file:

{
  "cwd": "./backend",  // Relative to config file location
  "command": "npm",
  "args": ["start"]
}

5. Use Environment Variables

Avoid hardcoding URLs and ports:

{
  "env": {
    "API_URL": "http://localhost:8080",
    "DATABASE_URL": "postgresql://localhost:5432/dev"
  }
}

Troubleshooting

Service Won’t Start

1. Check the working directory exists: "cwd": "./path"
2. Verify command is in PATH: which npm
3. Try running command manually
4. Check logs in dashboard UI

Port Already in Use

Enable port stealing:

"stealPort": true

Or manually check what’s using the port:

# macOS/Linux
lsof -ti:3000

# Windows
netstat -ano | findstr :3000

File Watching Not Working

1. Verify watchFiles is not set to false
2. Check if service uses nodemon (auto-detected)
3. Ensure watch paths exist

Service Status Not Detected

DevAll looks for these patterns in stdout:

• “Server running”
• “Listening on”
• “Ready on”
• URLs with localhost

Ensure your service logs one of these patterns when ready.

Next Steps

• Learn about MCP integration for AI assistants
• Check the API reference
• See example configurations