환경

에이전트가 웹 앱을 다루면 결과물은 열어서 확인하는 것인 경우가 많습니다. 개발 서버, 미리보기, 데스크톱 앱 같은 것입니다. 태스크 사이드바의 환경 영역은 이 태스크의 실행이 띄워 둔 것을 실행 중인 기기별로 묶어 보여 주고, 각각을 바로 열 수 있게 합니다.

환경은 두 가지 경로로 나타납니다.

자동 감지 덕분에 설정 없이도 이 영역을 쓸 수 있습니다. 선언하면 환경을 반복해서 띄울 수 있습니다. 모든 실행이 같은 방식으로, 자기 포트에서 시작하고, 로그도 사이드바에서 읽을 수 있습니다.

자동 감지된 서버Copy Anchor Link

macOS와 Linux에서 데몬은 약 30초마다 TCP 포트를 열고 있는 프로세스를 확인합니다. 다음 조건을 만족하는 프로세스가 사이드바에 표시됩니다.

• 작업 디렉터리가 이 태스크의 어떤 실행 디렉터리 안에 있음
• 두 번 연속 스캔에서 발견됨(잠깐 떴다 사라지는 테스트 서버는 표시되지 않음)

다음은 제외됩니다.

• AI 코딩 도구 자체와 multica CLI
• 프로젝트의 로컬 디렉터리에서 실행되는 서버(실행이 아니라 사용자가 직접 띄운 것)
• 이미 선언된 환경에 속한 서버(그 환경 아래에 한 번만 표시)
• 채팅 세션처럼 태스크에 속하지 않은 실행의 서버

데스크톱 앱(예: Electron 앱)은 포트별이 아니라 하나의 앱으로 표시됩니다. URL은 없으며, 같은 기기의 Multica Desktop에서 창으로 전환을 누르면 앞으로 가져올 수 있습니다. 원격 디버깅 포트는 링크로 표시되지 않습니다.

자동 감지된 서버는 실행이 끝난 뒤에도 포트를 열고 있는 동안 계속 표시됩니다. 멤버는 사이드바에서 중지할 수 있지만, 데몬이 시작 방법을 모르기 때문에 로그가 없고 재시작할 수도 없습니다. 이런 기능이 필요하면 선언하세요.

환경 선언하기Copy Anchor Link

저장소 루트에 .multica/environments.toml을 추가하고, 실행이 체크아웃하는 브랜치에 커밋합니다. 사이드바는 체크아웃의 루트나 그 바로 아래 디렉터리에 있는 파일만 찾으며, 오류가 있는 파일은 건너뜁니다. 무엇이 잘못됐는지는 multica env start가 알려 줍니다. [environments.<name>] 테이블 하나가 환경 하나입니다.

[environments.web]
label = "Web app"
start = "npm ci && npx vite --port $MULTICA_PORT --strictPort"
ttl = "24h"

에이전트는 자기 체크아웃 안에서 이렇게 시작합니다.

multica env start web

명령은 환경이 응답할 때까지 기다린 뒤 URL을 출력합니다. 환경은 사이드바에 표시되고, 실행이 끝나도 계속 실행되며, TTL이 끝나면 중지됩니다.

필드Copy Anchor Link

환경 이름은 environments. 뒤의 부분입니다. 소문자, 숫자, -, _만 쓸 수 있고, 영문자나 숫자로 시작하며 최대 40자입니다.

포트와 변수Copy Anchor Link

환경마다 전용 빈 포트 10개, MULTICA_PORT부터 MULTICA_PORT+9까지가 할당됩니다. 같은 기기의 두 실행이나 두 태스크가 충돌하지 않으니 포트를 고정해서 쓰지 마세요.

start와 stop에는 다음 변수가 전달됩니다.

데몬의 환경 변수도 물려받지만 MULTICA_* 변수(자격 증명 포함)는 빠집니다. 환경은 실행의 권한으로 동작할 수 없습니다. url과 ready에서는 $MULTICA_PORT(또는 ${MULTICA_PORT})만 치환됩니다. 두 번째 포트가 필요하면 API_PORT=$((MULTICA_PORT + 1))처럼 셸에서 계산하세요.

start는 포그라운드에 두기Copy Anchor Link

start는 새 프로세스 그룹의 리더로 실행됩니다. 그룹에 프로세스가 하나라도 남아 있는 동안 환경이 유지되고, 중지하면 그룹 전체에 신호가 갑니다. 따라서:

• 메인 서버는 포그라운드에 둡니다. &로 백그라운드에 띄운 보조 프로세스는 괜찮습니다. 같은 그룹에 남습니다.
• docker compose up -d, 시스템 서비스, setsid처럼 작업을 그룹 밖으로 넘기지 마세요. 환경은 바로 종료됨이 되고, 중지해도 그 작업에 닿지 않습니다. 이런 도구는 포그라운드로 실행하고 stop 명령을 추가하세요.
• 실행의 체크아웃에는 의존성이 설치되어 있지 않습니다. start 안에서 설치하세요. 데몬이 준비를 기다리는 10분에 그 시간도 포함됩니다.

예시Copy Anchor Link

각 예시는 .multica/environments.toml 전체입니다. 저장소에 맞게 npm ci를 사용하는 패키지 매니저의 설치 명령(pnpm install --frozen-lockfile, yarn install --immutable)으로 바꾸세요.

[environments.web]
label = "Web app"
start = "npm ci && npx next dev --port $MULTICA_PORT"
ttl = "24h"

환경을 여러 개 선언하려면 같은 파일에 테이블을 더 추가합니다. 각 환경의 프로세스는 그 환경과 함께 멈춥니다. 같은 체크아웃의 다른 환경이 그것을 쓰고 있어도 마찬가지입니다. 웹 앱과 그 API처럼 함께 계속 실행되어야 하는 서버는 Web + API 예시처럼 하나의 환경에 넣으세요.

CLI로 시작·중지하기Copy Anchor Link

세 명령 모두 --output json을 지원합니다. multica environment는 multica env의 긴 형태입니다.

시작 명령이 준비되기 전에 종료되면 multica env start가 실패하고 로그의 마지막 몇 줄을 출력합니다. 10분이 지나도 응답이 없으면 명령은 돌아오고, 환경은 시작 중으로 남으며 이유("not answering at http://localhost:41000" 등)가 함께 표시됩니다.

환경은 개별 실행이 아니라 태스크에 속합니다. 같은 태스크의 이후 실행은 이전 실행이 시작한 환경을 나열하고 중지할 수 있습니다. 같은 이름으로 다시 시작할 때 실행 중인 환경을 재사용하는 것은 이 기기에서 같은 체크아웃으로 실행 중일 때뿐입니다. 다른 체크아웃을 쓰는 실행은 같은 이름으로 자기 포트에서 두 번째 인스턴스를 시작하므로, 시작하기 전에 multica env list로 확인하세요.

사이드바에서 관리하기Copy Anchor Link

각 환경에는 상태, 시작·종료 시각, 만료 시각, 시작한 사람이 표시됩니다. 열기는 URL을 열고 URL 복사는 URL을 복사합니다. 종료된 환경은 "종료됨 N개" 아래에 접혀 있습니다.

• 시작: 환경 옆의 **+**를 클릭합니다. 각 기기에서 최근 실행이 선언한 환경이 나열되며, 고른 환경을 그 실행의 코드로 시작합니다. 태스크가 아직 실행되지 않았거나 그 코드가 정리되었다면 대신 에이전트에게 맡기도록 제안합니다. 에이전트는 코드를 준비해 multica env start를 실행하고, 선언이 없으면 시작 방법을 스스로 판단합니다.
• 중지, 재시작, 로그 보기: 환경의 추가 작업 메뉴를 엽니다. 재시작은 체크아웃의 선언을 다시 읽으므로 체크아웃과 그 안의 .multica/environments.toml이 남아 있어야 합니다. 자동 감지된 서버는 확인 후 중지만 할 수 있습니다.

시작, 중지, 재시작은 태스크에 접근할 수 있고 그 기기의 런타임을 사용할 수 있는 워크스페이스 멤버만 할 수 있습니다(데몬과 런타임 참고). 기기가 온라인이어야 하고, 그 기기의 Multica가 환경 조작을 지원하는 버전이어야 합니다. 조건이 맞지 않으면 버튼이 무엇이 부족한지 알려 줍니다. 로그를 보는 데는 태스크 접근 권한만 있으면 됩니다.

로그Copy Anchor Link

로그 보기는 선언된 환경의 출력 중 마지막 500줄(최대 256 KiB)을 보여 줍니다. 환경이 실행 중이면 약 5초마다 새 출력을 따라가며, 따라가기 일시 중지, 새로고침, 필터, 줄바꿈, 복사를 할 수 있습니다.

환경이 비정상 종료되면 마지막 두 줄의 출력이 환경과 함께 저장되므로, 기기가 오프라인이 되어도 사이드바에서 종료 이유를 볼 수 있습니다. 새로 읽으려면 기기가 온라인이어야 합니다.

전체 로그는 기기의 <workspaces root>/.environments/v1/ 아래에 남고, 환경이 끝난 뒤 7일간 보관됩니다. 경로는 multica env start와 multica env list가 출력합니다.

상태Copy Anchor Link

데몬이 멈춘 동안에는 아무것도 관리되지 않습니다. 데몬이 다시 시작되면 프로세스가 살아 있는 환경을 다시 맡습니다. 환경이 실행 중인 실행 디렉터리는 환경이 멈출 때까지 데몬의 워크스페이스 정리에서 삭제되지 않습니다.

에이전트에게 파일 맡기기Copy Anchor Link

에이전트는 이 형식을 알고 있습니다. 모든 에이전트가 받는 Multica 내장 플랫폼 스킬에 .multica/environments.toml 작성법과 검증 방법이 들어 있습니다. 태스크에서 이렇게 요청하면 됩니다.

이 저장소의 웹 앱을 multica env start로 시작할 수 있도록 .multica/environments.toml을 추가해 주세요. 한 번 시작해서 동작하는지 확인한 뒤 PR을 열어 주세요.

에이전트는 프로젝트를 띄우는 방법을 파악하고, MULTICA_PORT의 포트로 파일을 작성하고, 환경을 시작해 응답하는지 확인한 뒤, 다른 변경처럼 제출합니다. 병합되면 이후 모든 실행이 이 환경을 시작할 수 있고, 멤버도 사이드바에서 시작할 수 있습니다.

알려진 제한Copy Anchor Link

• macOS와 Linux만 지원합니다. Windows에서는 서버가 감지되지 않고, multica env start는 아직 지원하지 않는다고 알립니다.
• localhost URL은 실행 중인 기기에서만 열립니다. 빌드 서버나 동료의 컴퓨터처럼 다른 기기에서 실행 중이면 사이드바가 그렇게 표시합니다. 그 기기에서 열거나 직접 포트를 포워딩하세요.
• systemd에서의 데몬 재시작. Linux에서 로그인 시 자동 시작을 쓰면, 데몬을 재시작하거나 업데이트할 때 선언된 환경도 함께 멈춥니다. 그 뒤 다시 시작하세요.
• 환경은 한 기기에서만 실행됩니다. 환경은 그것을 시작한 실행의 기기에서 실행되며 태스크를 따라 옮겨 가지 않습니다.

다음 단계Copy Anchor Link

• 데몬과 런타임 — 환경을 감지하고 관리하는 데몬.
• CLI 사용 — multica env 명령과 다른 CLI 명령.
• 실행 — 실행 디렉터리가 어디서 오는지.