Configuration

devmux is configured via a devmux.config.json file in your project root.

Basic Structure

{
  "project": "myapp",
  "services": {
    "api": {
      "command": "pnpm dev",
      "cwd": "./api",
      "port": 8787
    },
    "web": {
      "command": "pnpm dev",
      "cwd": "./web",
      "port": 3000
    }
  }
}

Configuration Options

`project` (required)

The project name used in tmux session naming. Sessions are named omo-{project}-{service}.

{
  "project": "waypoint"
}

This creates sessions like omo-waypoint-api, omo-waypoint-web.

`services` (required)

A map of service names to their configurations.

{
  "services": {
    "api": { ... },
    "web": { ... },
    "worker": { ... }
  }
}

Service Options

`command` (required)

The command to run when starting the service.

{
  "command": "pnpm dev"
}

For complex commands, you can use shell syntax:

{
  "command": "DATABASE_URL=postgres://localhost/dev pnpm dev"
}

`cwd` (optional)

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

{
  "cwd": "./packages/api"
}

If not specified, defaults to the project root.

`port` (optional)

The port the service listens on. Used for health checks.

{
  "port": 8787
}

When specified, devmux ensure will wait for this port to be available before returning.

`healthCheck` (optional)

Custom health check configuration.

{
  "healthCheck": {
    "type": "http",
    "path": "/health",
    "timeout": 30000
  }
}

Options:

type: "port" (default) or "http"
path: HTTP path to check (for http type)
timeout: Maximum wait time in milliseconds (default: 30000)

Full Example

Here’s a complete configuration for a typical monorepo:

{
  "project": "acme",
  "services": {
    "api": {
      "command": "pnpm dev",
      "cwd": "./apps/api",
      "port": 8787,
      "healthCheck": {
        "type": "http",
        "path": "/health",
        "timeout": 60000
      }
    },
    "web": {
      "command": "pnpm dev",
      "cwd": "./apps/web",
      "port": 3000
    },
    "docs": {
      "command": "pnpm dev",
      "cwd": "./apps/docs",
      "port": 3001
    },
    "worker": {
      "command": "pnpm dev",
      "cwd": "./apps/worker"
    }
  }
}

Environment-Specific Configs

You can create environment-specific configurations:

devmux.config.json - Default
devmux.config.local.json - Local overrides (add to .gitignore)

The local config is merged on top of the default config.

Generating Config

From Turbo.json

If you use Turborepo, generate config automatically:

devmux discover turbo

This scans your turbo.json for dev tasks and creates the config.

Interactive Init

Create a basic config interactively:

devmux init

This prints a template you can customize.

Validation

devmux validates your config on startup. Common errors:

Error	Cause	Fix
`Missing project name`	No `project` field	Add `"project": "myapp"`
`No services defined`	Empty `services` object	Add at least one service
`Invalid port`	Port is not a number	Use a number like `8787`