> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Multiplex — 로컬 개발 프로세스를 함께 관리하는 TUI

> laravel/multiplex의 초기 조사. Laravel 13의 php artisan dev가 사용하는, 여러 프로세스의 탭 표시·검색·자동 재시작에 대응한 터미널 UI를 해설합니다.

## 시작하며

[`laravel/multiplex`](https://github.com/laravel/multiplex)는, 여러 명령을 동시에 실행하기 위한 터미널 UI(TUI)입니다. Laravel 13의 `php artisan dev`에서 이용되고 있으며, PHP 개발 서버, 큐 워커, 로그 감시, Vite 등, 로컬 개발에 필요한 프로세스를 하나의 터미널에서 관리할 수 있습니다.

탭마다 프로세스의 출력을 표시할 수 있어, 출력의 검색과 스크롤에도 대응합니다. 종료 시에는 각 프로세스의 출력이 통상의 터미널의 스크롤백에 되돌아오기 때문에, TUI를 종료한 후에도 로그를 확인할 수 있습니다.

## 인스톨과 직접 실행

Laravel 애플리케이션에서는 `php artisan dev`가 필요한 설정을 실시하기 때문에, 통상은 Multiplex를 직접 인스톨할 필요는 없습니다. 단독으로 사용하는 경우는, Node.js 22.13 이상을 준비해 npm으로 인스톨합니다.

```bash theme={null}
npm install -g @laravel/multiplex
```

명령은 `label,command` 형식으로 전달합니다.

```bash theme={null}
multiplex 'server,php artisan serve' 'queue,php artisan queue:listen' 'vite,npm run dev'
```

## TUI와 인라인 모드

표준 입력과 표준 출력이 TTY의 경우는 탭 형식의 TUI가 기동합니다. `s`로 스트림 표시로 전환, `/`로 출력을 검색, `r`로 선택 중의 프로세스를 재시작할 수 있습니다. `q`로 종료합니다.

TTY가 없는 CI나 파이프 처리에서는, 인라인 모드로 자동적으로 전환됩니다. 각 행에 프로세스의 라벨이 붙어, 출력이 도착한 순서로 표시됩니다. 명시적으로 인라인 모드를 사용하는 경우는 `-i`를 지정합니다.

```bash theme={null}
multiplex -i 'build,npm run build' 'test,npm test'
```

인라인 모드에서는 마지막 프로세스가 종료되면 실행도 종료되어, 명령의 실패를 종료 코드에 반영합니다. JSON 형식으로 처리 결과를 다루는 경우는 `--json`을 사용합니다.

```bash theme={null}
multiplex --json 'build,npm run build' 'test,npm test'
```

## 자동 재시작과 종료 처리

크래시한 프로세스는 1초 기다린 뒤 최대 5회까지 자동적으로 재시작됩니다. 기동으로부터 1초 이내에 종료된 프로세스는, 실행 파일의 부족이나 포트 경합 등, 처음부터 기동할 수 없을 가능성이 있기 때문에 재시도되지 않습니다. 빌드나 마이그레이션과 같은 한 번만 실행하는 명령에서는 `--no-restart`를 지정합니다.

```bash theme={null}
multiplex --no-restart 'build,npm run build'
```

Multiplex는 종료 시나 시그널 수신 시에 자식 프로세스의 프로세스 그룹을 종료시킵니다. 개발 서버만이 남아 포트를 점유하는 상태를 막기 위해, 여러 프로세스를 함께 정지할 수 있습니다.

## 주의점

자식 프로세스에는 표준 입력이 전달되지 않습니다. 그 때문에, `php artisan tinker`나 마이그레이션의 확인 프롬프트 등, 입력을 요구하는 명령은 Multiplex에서 실행할 수 없습니다. 대화적인 명령은 별도의 터미널에서 실행해 주세요.

Multiplex의 프로그램 API도 제공되어 있지만, 명령은 `sh -c`로 실행됩니다. 설정 파일이나 리퀘스트 등, 신뢰할 수 없는 값을 명령 문자열에 삽입하지 말아 주세요.

## 참고 자료

* [Laravel 공식 문서: Artisan - The Dev Command](https://laravel.com/docs/13.x/artisan#the-dev-command)
* [laravel/multiplex README](https://github.com/laravel/multiplex)


## Related topics

- [Artisan 콘솔](/ko/artisan.md)
- [프로세스](/ko/processes.md)
- [Laravel Cloud — Laravel 전용 PaaS의 전모](/ko/blog/laravel-cloud.md)
- [Laravel AI 에이전트가 MCP 서버 지원](/ko/blog/ai-sdk-mcp-client.md)
- [Laravel Reverb](/ko/reverb.md)