Dev Servers

AgentOS can start and manage development servers for your projects.

Supported Server Types

Node.js

Automatically detects package.json and runs:

• npm run dev
• yarn dev
• pnpm dev

Docker Compose

Runs docker compose up for projects with docker-compose.yml.

Starting a Server

1. Open the Dev Servers section in the sidebar
2. Click Start Server
3. Select your project
4. Choose server type (Node.js or Docker)

The server starts in the background with its own port.

Port Assignment

AgentOS assigns unique ports to each server:

• Range: 3100-3900
• Worktree sessions get dedicated ports (3100, 3110, 3120...)
• Main project uses 3000 or next available

Server Status

Viewing Logs

Click a running server to view its logs:

• Real-time log streaming
• Scroll through history
• Error highlighting

Stopping Servers

Click Stop on any running server. A confirmation dialog prevents accidental stops.

Restarting

Click Restart to stop and start the server. Useful after code changes that require a full restart.

Project Configuration

Configure dev servers per-project in .agent-os.json:

{
  "devServer": {
    "command": "npm run dev",
    "portEnvVar": "PORT",
    "env": {
      "NODE_ENV": "development"
    }
  }
}

Options

Multiple Servers

Run multiple servers simultaneously:

• API server on 3100
• Frontend on 3101
• Worker process on 3102

Each gets its own log viewer and controls.