환경 설정하기
환경은 한 스페이스의 실행 스택입니다. 브랜치에 필요한 서비스가 다른 모든 스페이스와 격리되어 실행되고, 사이드바에 표시되며, 에이전트가 접근할 수 있습니다. PR에는 이미 자체 스페이스가 있으므로 풀 리퀘스트도 환경을 갖습니다.
워크스페이스 관리자가 정의를 한 번 작성합니다. 그러면 멤버는 스페이스나 PR 사이드바의 환경 섹션에서 시작을 누릅니다. 정의는 워크스페이스 데이터베이스에 저장되므로 기능 브랜치가 Control Center의 실행 내용을 바꾸는 일은 없지만, 도구는 여전히 그 브랜치의 코드를 실행합니다.
정의 만들기
섹션 제목: “정의 만들기”- 설정 → 워크스페이스 → 환경을 엽니다. 워크스페이스 관리자만 정의를 변경할 수 있으며, 서버 호스트에서 실행되는 정의는 서버 소유자만 저장할 수 있습니다(누가 무엇을 저장할 수 있는지 참고).
- 새 정의를 클릭한 다음 빈 정의 또는 저장소에서 초안 만들기를 클릭합니다. 초안은 저장소에서 compose 파일,
Procfile,package.json스크립트를 찾으며 결과는 직접 검토합니다. - 양식을 채우거나 JSON 탭을 사용합니다. 이 페이지의 예제가 바로 그 JSON입니다.
- 테스트 실행를 클릭합니다. 일회용 환경을 시작하고 준비될 때까지 기다린 뒤 삭제합니다.
저장할 때 정의는 엄격하게 검사됩니다. 알 수 없는 필드, 잘못된 형식의 값, 철자가 틀린 선택지는 거부되며, 경로와 가장 가까운 유효한 이름이 함께 표시됩니다. 예: repos.app.requird: Unknown field. Did you mean "required"?. 최상위 $schema는 허용됩니다.
정의를 저장소에 두려면 저장소 파일 연결을 사용합니다. Control Center는 기본 브랜치에서만 파일을 읽고 승인된 버전만 실행합니다. 승인하는 사람은 워크스페이스 관리자이며, 정의가 호스트에서 실행될 때는 서버 소유자입니다. 새 버전은 업데이트 있음을 표시하며 승인될 때까지 아무것도 바꾸지 않습니다.
누가 무엇을 저장할 수 있는지
섹션 제목: “누가 무엇을 저장할 수 있는지”환경 정의는 서버 호스트에서 서버 자신의 사용자로 명령을 실행할 수 있습니다. 이는 워크스페이스 역할이 아니라 서버 소유자가 정할 일입니다:
- 정의는 호스트 배치를 가지거나, 명령을 실행하는 검사를 가지거나,
provision또는archive작업을 가지면 호스트에서 실행됩니다. 이 작업들은 배치와 관계없이 호스트에서 스페이스의 워크트리 안에서 실행됩니다. - 호스트에서 실행되는 정의는 서버 소유자만 저장하거나 승인할 수 있습니다. 여기에는 연결된 저장소 파일의 새 버전을 승인하는 것도 포함됩니다. 이를 시도하는 워크스페이스 관리자에게는 “서버 호스트에서 실행되는 환경은 서버 소유자만 저장하거나 승인할 수 있습니다. 워크스페이스 관리자는 리그에서 실행되는 환경을 사용할 수 있습니다.“가 표시됩니다.
- 워크스페이스 관리자는 리그에서만 실행되는 정의를 저장하고 승인할 수 있습니다.
"placement": "rig"이고 검사 명령이나provision또는archive작업이 없는 정의입니다. - 구성원은 어느 쪽이든 환경을 시작하고, 중지하고, 사용합니다.
- 호스트에서 실행되는 정의는 현재 서버 소유자가 저장하거나 승인한 뒤에만 실행됩니다. 서버는 그 승인을 직접 기록하고, 시작, 검사, 작업, PR 헤드 동기화 전마다 이를 확인합니다. 현재 소유자가 승인하지 않은 정의(예: 이전 소유자가 저장한 정의)는 환경 목록과 편집기에서 해당 행 아래에 대기합니다. 서버 소유자에게는 “이 서버에서 실행됩니다. 시작하려면 승인하세요.“가 승인 버튼과 함께 표시되며, 이 버튼은 정의를 바꾸지 않고 그대로 저장합니다. 그 밖의 사람에게는 “이 서버에서 실행됩니다. 시작하려면 서버 소유자가 승인해야 합니다.“가 표시됩니다.
- 그 승인을 기다리는 환경에는 “서버 소유자가 아직 이 환경을 승인하지 않아서 이 서버에서 실행할 수 없습니다.“라고 표시됩니다. 서버 소유자에게는 대신 “아직 이 환경을 승인하지 않았습니다. 이 서버에서 실행되므로 정의를 승인하면 시작됩니다.“가 표시되며, 함께 있는 검토 후 승인은 정의를 엽니다.
- 환경의 프로세스 터미널과, 시작 시 사용자의 조치가 필요할 때 열리는 터미널은 서버 호스트에서 실행됩니다. 이 터미널에 입력하거나, 크기를 바꾸거나, 닫으려면 스페이스가 노출하는 모든 저장소에 대한 쓰기 권한이 있어야 하며(본인의 forge 로그인으로 읽을 수 있어야 합니다), 이는 환경을 시작하는 것과 같은 요건입니다. 그 밖의 사람은 이 터미널에 전혀 닿을 수 없습니다.
가장 작은 정의
섹션 제목: “가장 작은 정의”단순한 compose 저장소라면 이것으로 충분합니다.
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}나머지는 모두 기본값이 있습니다. compose 파일을 찾고, 모든 서비스를 실행하고, 포트를 할당하고, HTTP 엔드포인트를 감지하며, 환경 이름은 브랜치를 따릅니다.
구성 요소 종류
섹션 제목: “구성 요소 종류”환경은 구성 요소의 순서 있는 목록입니다. after가 다른 것을 지정하지 않는 한 각 구성 요소는 이전 구성 요소가 준비될 때까지 기다리고, 중지는 역순으로 진행됩니다. enabledWhen은 opt.seed, !opt.seed, repo.web처럼 옵션이나 역할에 따라 구성 요소를 켭니다. 역할이 선택 사항이고 스페이스에 없는 구성 요소도 같은 방식으로 제외되며, enabledWhen은 필요하지 않습니다. 그 구성 요소는 시작되지 않고 {port.*}나 {url.*}도 가지지 않으므로, 이를 읽는 다른 구성 요소는 시작에 실패합니다.
| 종류 | 실행 주체 | 용도 |
|---|---|---|
compose |
Control Center의 compose 드라이버 | 모든 compose 파일, 환경당 하나 |
cli |
사용자의 도구. Control Center가 매핑된 동사를 호출하고 JSON을 읽습니다 | 수명 주기, 도메인, 데이터를 직접 관리하는 도구 |
process |
Control Center, 감독되는 터미널 세션에서 | 개발 서버와 워커 |
task |
Control Center, 트리거당 한 번 | 설치, 마이그레이션, 테스트 |
app |
Control Center, 누군가 실행을 클릭할 때 | 데스크톱 앱 |
task 구성 요소는 when 목록을 받습니다.
| 트리거 | 실행 시점 |
|---|---|
provision |
워크트리가 만들어질 때(아래 워크트리 작업 참고) |
create |
환경당 한 번, 그리고 재설정 후 다시 |
start |
시작할 때마다 |
change |
동기화 후 변경된 경로가 onChange와 일치할 때 |
manual |
요청 시: 실행, cc-env run <id> 또는 environment_run_task |
archive |
워크트리가 삭제되기 직전 |
시작할 때 할 일이 없는 작업은 유휴로 표시되며, 환경이 시작되는 동안 표시되는 단계 목록에서 빠집니다. manual 또는 change 작업, 또는 이미 실행된 create 작업이 여기에 해당합니다.
배열로 지정한 명령은 argv이므로 옵션 값이 셸을 거치지 않습니다. 문자열이나 줄 배열이 있는 script는 bash -lc로 실행됩니다. {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>}, {url.<role>} 같은 자리 표시자는 argv에서만 확장됩니다. 셸 명령은 같은 값을 $CC_ENV_PORT_WEB 같은 CC_ENV_* 변수로 읽습니다. 이 스페이스의 환경에 속한 구성 요소에 알 수 없는 자리 표시자가 있으면, 아무것도 실행되기 전에 시작이 중단됩니다.
모든 명령과 스페이스 터미널은 CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE>도 받으며, PR 스페이스에서는 CC_PR_NUMBER와 CC_PR_IS_FORK도 받습니다. compose 구성 요소가 있으면 COMPOSE_PROJECT_NAME과 COMPOSE_FILE도 받으므로 작업 안의 docker compose exec가 올바른 프로젝트에 닿습니다.
역할과 작업 디렉터리
섹션 제목: “역할과 작업 디렉터리”정의는 역할을 워크스페이스 저장소에 연결하므로 하나의 스택이 여러 저장소에 걸칠 수 있습니다.
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: 스페이스에 앵커 역할이 하나 이상 있으면 환경을 시작할 수 있습니다. 두 정의가 일치하면 시작하는 사람이 고릅니다.required: 이 저장소 없이는 스택이 실행되지 않습니다.whenMissing: 스페이스에 역할이 없을 때의 동작입니다.addToSpace는 기본 브랜치의 저장소를 추가하며required역할의 기본값입니다.useSource는 등록된 체크아웃을 전달하며 읽기 전용으로 다뤄야 합니다.skip은 변수를 설정하지 않으며 그 밖의 경우의 기본값입니다.- 시작하려면 스페이스의 앵커 저장소에 대한
write권한과 연결된 다른 모든 저장소에 대한 읽기 권한이 필요합니다.
명령은 repos에 선언된 첫 번째 역할에서 실행되며, 스페이스가 우연히 가진 다른 역할에서는 실행되지 않으므로 저장소가 하나인 정의에는 이를 적을 필요가 없습니다. 모든 구성 요소는 "cwd": { "role": "e2e", "path": "packages/ui" }로 이를 재정의할 수 있습니다. 두 필드는 모두 선택 사항입니다. 첫 번째 역할이 스페이스에서 빠질 수 있는 경우(required가 아니고 유일한 앵커도 아닌 경우)에는 모든 구성 요소가 역할을 명시해야 합니다.
포트와 URL
섹션 제목: “포트와 URL”Control Center는 무언가 시작되기 전에 호스트 전체에 공통인 범위(기본값 42000에서 49999, 32개 단위 블록)에서 호스트 포트를 할당합니다. 포트는 환경이 존재하는 동안 그대로이며, compose 포트는 127.0.0.1에만 바인딩됩니다.
- compose 포트는 선언할 필요가 없습니다.
{port.postgres.5432}또는CC_ENV_PORT_POSTGRES_5432로 읽습니다. - 다른 포트는 사용하는 곳에서
"port": "web"또는"ports": ["web", "hmr"]로 선언하고{port.web}으로 읽습니다. 포트가 있는 프로세스는PORT와HOST=127.0.0.1도 받습니다.
HTTP 엔드포인트는 하나의 루프백 포트에서 수신하는 서버 라우터의 URL을 받습니다.
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>은 브랜치의 슬러그이고, PR 스페이스에서는pr-<n>입니다.<project>는naming.project이며 없으면 정의의 이름입니다.*.localhost이름은 루프백을 가리키므로 hosts 항목이나 DNS가 필요 없고, 호스트 이름이 환경 간 쿠키를 분리합니다.- HTTP에 응답하는 compose 포트는 감지되며 구성 요소의
http가 이 추측을 대체합니다. 프로세스에는"endpoint": { "role": "web", "primary": true }가 필요하고, 이는{url.web}도 사용할 수 있게 합니다. - 브라우저(VM)에서는 Browser (VM)에서 열기을 사용합니다. 거기서는
https://web--fix-login--shop.localhost/가 같은 경로에 닿습니다. - 전체 레이블은 63자 이내로 유지되므로 긴 이름은 해시로 줄어듭니다.
- 두 엔드포인트는 상위 도메인을 공유하지 않습니다. 둘에 걸쳐 하나의 쿠키가 필요한 앱은 하나의 엔드포인트에서 제공해야 합니다.
OAuth 리디렉션처럼 미리 등록해야 하는 URL에는 "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" }이 고정된 이름 집합을 제공합니다.
policy는 환경이 언제 실행되는지 결정합니다. autoCreate는 off, prSpaces, allSpaces 중 하나이고, idleStopMinutes의 기본값은 240이며, followPrHead는 head가 움직이면 PR 환경을 동기화하고, maxRunning(기본값 6)에 이르면 시작이 가장 오래 사용되지 않은 환경을 중지하도록 제안합니다.
예제: compose 앱
섹션 제목: “예제: compose 앱”하나의 compose 파일에서 실행되는 웹 앱과 Postgres에 git이 무시하는 .env, 마이그레이션, 테스트 작업을 더한 예제입니다. seedFiles는 등록된 체크아웃의 지정 파일을 새 워크트리마다 복사합니다.
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "shop" }, "seedFiles": [".env"], "components": [ { "kind": "compose", "id": "stack", "services": ["postgres", "web"], "healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } }, { "kind": "task", "id": "migrate", "when": ["create", "change"], "onChange": ["db/migrations/**"], "command": "docker compose exec -T web bin/migrate" }, { "kind": "task", "id": "test", "when": ["manual"], "command": "docker compose exec -T web bin/test" } ]}healthchecks를 쓰면 자체 상태 확인이 없는 서비스도 다음 구성 요소를 기다리게 할 수 있습니다. 없으면 실행 중인 컨테이너가 준비된 것으로 간주되어, 아직 시작 중인 데이터베이스보다 마이그레이션이 먼저 실행될 수 있습니다.
시작과 새로 고침 때마다 --remove-orphans와 함께 up을 실행하므로, compose 파일에서 제거된 서비스는 중지되고 포트를 해제합니다. 구성 요소에서 "build": false를 설정하지 않는 한, 시작과 새로 고침 시 이미지를 빌드합니다.
예제: 사용자 지정 CLI
섹션 제목: “예제: 사용자 지정 CLI”컨테이너, 도메인, TLS를 직접 관리하는 가상의 도구 acme입니다. Control Center는 {name}을 제공하고 나머지는 모두 status에서 알아냅니다. 도구의 호스트 이름을 추측하지 않으며 /etc/hosts도 편집하지 않습니다.
{ "contract": 1, "name": "Acme", "repos": { "server": { "repoId": "<server>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true } }, "routing": { "mode": "tool", "domain": "acme.test", "upstream": "127.0.0.1:443", "tls": true, "caFile": "~/.acme/tls/ca.crt" }, "components": [ { "kind": "cli", "id": "acme", "verbs": { "create": ["acme", "env", "create", "{name}", { "if": "!interactive", "args": ["--json"] }, { "if": "repo.web", "args": ["--web-dir", "{repo.web}"] }], "start": ["acme", "env", "start", "{name}"], "stop": ["acme", "env", "stop", "{name}"], "destroy": ["acme", "env", "destroy", "{name}", "--yes"], "reset": ["acme", "env", "reset-db", "{name}"], "status": ["acme", "env", "status", "{name}", "--json"], "list": ["acme", "env", "ls", "--json"], "logs": ["acme", "env", "logs", "{name}", { "if": "service", "args": ["{service}"] }, "--tail", "{tail}", { "if": "follow", "args": ["--follow"] }], "exec": ["acme", "env", "exec", "{name}", "{service}", "{command}"] }, "interactive": ["create"], "keepsDataOnStop": false, "statusMap": { "state": [ { "when": { "path": "/status/ready", "equals": true }, "state": "ready" }, { "when": { "none": "/status/containers", "where": { "state": "running" } }, "state": "stopped" }, { "when": { "path": "/status/phase", "equals": "failed" }, "state": "failed" }, { "state": "starting" } ], "detail": "phase: {/status/phase}", "warnings": [ { "when": { "path": "/status/dnsWorking", "equals": false }, "message": "Not resolvable on this host" } ], "endpoints": [ { "role": "app", "label": "App", "url": "/urls/app", "primary": true }, { "role": "db", "hostPort": "/ports/db" } ], "services": "/status/containers/*/service", "list": "/*/slug", "missingErrorCodes": ["env.not-found"] } } ]}create,status,destroy는 필수입니다. Control Center는 읽은 상태에 따라create또는start를 고릅니다. 모든 동사는 argv 대신{ "shell": "…" }일 수 있습니다.interactive는 터미널에서 필요한 입력을 요청할 수 있는 동사를create,start,reset중에서 지정합니다. 시작을 누른 사람에 대해 그런 동사가 종료 코드 3으로 끝나면, Control Center는 같은 동사를 터미널 탭에서 다시 실행하고, 종료 코드 0으로 끝나면 시작을 이어 갑니다. 그곳에서는 조건interactive가 참이 되고CC_ENV_INTERACTIVE=1이 설정되므로,{ "if": "!interactive", "args": ["--json"] }는 파이프를 위해 기계용 출력을 유지합니다. 에이전트가 시작하거나 자동으로 시작하는 경우에는 터미널이 열리지 않으며, 환경은 조치 필요로 표시되고 기다립니다.destroy가 실패하더라도 이어서status가missing을 보고하면 환경은 삭제되므로, 도구가 더 이상 가지고 있지 않은 환경은 언제나 삭제할 수 있습니다.list를 사용하면 Control Center는 도구가 잃어버린 환경을 알아챌 수 있습니다. 이름이list에 없고status가missing이라고 응답할 때에만 사라진 것으로 표시됩니다. 목록으로 읽을 수 없는 출력은 아무것도 바꾸지 않습니다.logs와exec의{service}는-로 시작하지 않는 한 단어여야 하며, 도구가 무언가를 보고한 적이 있다면 도구가 마지막으로 보고한 서비스 중 하나여야 합니다.statusMap은 도구 자체의 JSON을 JSON 포인터로 읽으며,*는 모든 항목과 일치합니다. 상태 규칙에는 순서가 있고 처음 일치한 규칙이 적용됩니다. 조건은path와equals, 또는any나none과where입니다.keepsDataOnStop: false는 유휴 중지를 끄고 중지에 데이터 손실 경고를 추가합니다. 중지하면 데이터가 사라질 때 설정합니다.routing.mode: "tool"은 도구의 호스트 이름을 브라우저(VM)와 에이전트에 연결합니다. 도메인은.test,.localhost,.internal중 하나로 끝나야 하며, 그 밖의 보고된 URL은 버려집니다.
직접 만든 도구라면 statusMap을 생략하고 이 페이지 끝에 설명된 상태 계약을 출력할 수 있습니다.
예제: pnpm 모노레포
섹션 제목: “예제: pnpm 모노레포”프로세스와 작업만 있고 컨테이너는 없습니다. 웹 앱은 {url.api}를 통해 API를 찾습니다.
{ "contract": 1, "name": "Monorepo", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "mono" }, "options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ], "components": [ { "kind": "task", "id": "install", "when": ["provision", "change"], "onChange": ["pnpm-lock.yaml"], "command": ["pnpm", "install", "--frozen-lockfile"] }, { "kind": "process", "id": "api", "label": "API", "port": "api", "cwd": { "path": "apps/api" }, "command": ["pnpm", "dev"], "endpoint": { "role": "api" }, "ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 }, "restartOn": ["pnpm-lock.yaml"] }, { "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed", "cwd": { "path": "apps/api" }, "command": ["pnpm", "db:seed"] }, { "kind": "process", "id": "web", "label": "Dev server", "port": "web", "cwd": { "path": "apps/web" }, "env": { "API_URL": "{url.api}" }, "command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"], "endpoint": { "role": "web", "primary": true }, "ready": { "http": "http://127.0.0.1:{port.web}/" } }, { "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] } ]}- 각 프로세스는 열고, 읽고, 입력할 수 있는 터미널 탭입니다. 스페이스의 모든 저장소에 대한 쓰기 권한이 있을 때에만 가능합니다(누가 무엇을 저장할 수 있는지 참고). 탭을 닫아도 멈추지 않습니다.
ready는http(전체 URL),tcp(host:port),logMatch(정규 표현식)를 받습니다.restart는on-failure(기본값),always,never중 하나입니다.restartOn은 변경된 경로가 일치하면 프로세스를 다시 시작합니다.options는 시작의 양식이 되고,agentDefault는 에이전트가 시작한 실행에 적용됩니다.
예제: 데스크톱 앱
섹션 제목: “예제: 데스크톱 앱”빌드 단계가 있는 데스크톱 앱입니다. Control Center는 OS 창 수준에서 동작하며 앱에 훅이나 SDK가 필요 없으므로, 앱은 무엇으로 만들어졌든 똑같이 동작합니다.
{ "contract": 1, "name": "Studio", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "task", "id": "build", "when": ["manual"], "command": ["pnpm", "build"] }, { "kind": "app", "id": "desktop", "label": "Studio", "prepare": "build", "command": ["dist/mac-arm64/Studio.app/Contents/MacOS/Studio"], "isolate": "home" } ]}앱은 환경과 함께 시작되지 않습니다. 누군가 실행을 클릭하면 prepare가 먼저 실행됩니다. 다시 빌드 후 재실행은 이 쌍을 다시 실행합니다. enabledWhen은 앱과 그 prepare 작업 모두에 적용되며, 둘 중 하나가 꺼져 있으면 실행이 거부됩니다. 앱은 프로세스 그룹의 어떤 프로세스든 실행되는 동안 실행 중으로 간주되므로, 앱을 실행하고 종료하는 런처도 문제없습니다. 실행을 누른 뒤 약 5초 안에 모든 프로세스가 사라지면, 앱은 마지막 로그 줄과 함께 실패로 표시됩니다. 그 후 정상 종료는 닫힘으로 표시되고, 충돌은 마지막 로그 줄을 보여 줍니다. 둘 다 앱을 다시 시작하지는 않습니다. 서버를 다시 시작하면 앱은 닫히며 다시 실행되지 않고, 유휴 중지는 실행 중인 앱을 건드리지 않습니다.
데스크톱 앱 권한과 제한
섹션 제목: “데스크톱 앱 권한과 제한”- macOS에서는 시스템 설정에서 Control Center에 화면 기록과 손쉬운 사용 권한을 한 번 부여합니다. 서버 호스트에는 GUI 세션이 필요하며, 헤드리스 서버는 앱 실행을 거부합니다.
- 바이너리를 직접 실행합니다.
open -a는 앱을 LaunchServices에 넘기므로 Control Center가 추적하는 프로세스 트리를 벗어나므로, 실행 직후 앱이 실패로 표시됩니다. - 창은 디스플레이에 남습니다. macOS는 모든 디스플레이 밖에 놓인 창을 캡처하지 않으므로, 에이전트가 사용하는 앱은 서버 화면에 보입니다. 포커스는 필요 없습니다.
"isolate": "home"은HOME,XDG_*,CFFIXED_USER_HOME을 통해 앱에 전용 홈을 제공하므로 두 스페이스의 사본이 나란히 실행될 수 있습니다.NSUserDefaults는 격리되지 않으므로 Cocoa 환경설정과 Flutter의shared_preferences는 사본 간에 공유됩니다.isolate는 실행된 프로세스에만 적용됩니다.flutter run같은 도구 체인 실행기는 실제 홈이 필요하므로isolate는 빌드된 바이너리와 함께 사용합니다.--user-data-dir처럼 앱 자체 설정이 있으면 그것을 우선합니다.- 에이전트는
app_use로 창을 조작하며, 이 환경의 프로세스 트리에만 닿을 수 있습니다. 에이전트는 데스크톱이 아니라 창을 봅니다. 에이전트의 실행은 작업 정책을 거치고 기본적으로 확인을 요청하며, 사람이 제어권을 가진 동안 에이전트 입력은 멈춥니다. "input": "background"(기본값)는 이벤트를 프로세스로 보냅니다."foreground"는 창을 활성화하고 커서를 넘겨받습니다.
워크트리 작업
섹션 제목: “워크트리 작업”provision과 archive 작업은 저장소의 설정과 정리를 해당 워크트리와 함께 실행합니다. 설정 → 워크스페이스 → 리포지토리에서 저장소 행의 아이콘을 누르면 저장소의 정의가 열립니다.
이 작업들은 환경이 아니라 워크트리를 따르므로, 아무도 시작을 누르지 않는 스페이스에서도 실행됩니다.
provision |
archive |
|
|---|---|---|
| 실행 | 역할의 워크트리가 만들어질 때, 모든 스페이스에서 | 그 워크트리가 삭제되기 직전 |
| 실패 시 | 프로비저닝이 실패하고 워크트리가 삭제됨 | 기록되며 삭제를 막지 않음 |
| 기본 제한 시간 | 5분 | 2분 |
| 보이는 값 | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
동일 |
스택이 없는 저장소는 작업을 담은 정의만 있으면 됩니다. 시작할 것이 없으므로 앵커 역할은 필요 없습니다.
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- 아직 환경이 없으므로 이 작업들은
{name},{port.*},{url.*},{opt.*},enabledWhen을 쓸 수 없고, 정의의env도 받지 않습니다. - 한 저장소의
provision과archive작업은 하나의 정의만 가질 수 있습니다. 다른 정의는 그 밖의 용도로 연결할 수 있습니다. "when": ["provision", "change"]는 잠금 파일이 바뀔 때도 다시 설치합니다.- 작업은
cwd역할의 워크트리에 대해 실행되므로, 여러 저장소를 쓰는 정의는 저장소별로 따로 설정할 수 있습니다. - 테스트 실행은
CC_SCRIPT_TEST=1을 설정합니다. 재시도는 깨끗한 워크트리에서 시작하므로 다시 실행해도 문제없는 작업을 작성합니다.
에이전트
섹션 제목: “에이전트”에이전트는 Docker 소켓을 받지 않습니다. 해당 정의가 있는 스페이스에서는 실행의 PATH에 cc-env가 들어갑니다. 스페이스는 실행에서 결정되므로 에이전트는 자기 환경에서만 작업할 수 있고, 각 명령은 작업 정책을 거칩니다.
cc-env statuscc-env upcc-env downcc-env resetcc-env destroycc-env restart <process>cc-env logs <name>cc-env exec <service> -- <cmd>cc-env run <task> -- <args>compose 구성 요소가 있으면 docker 심이 ps, logs, exec, port, restart, top을 쓰는 docker compose도 허용하며, 이 환경 자신의 compose 프로젝트에 대해서만 허용합니다. 동사 앞에는 플래그를 둘 수 없고, 각 동사는 짧은 옵션 목록만 받습니다. logs는 출력을 따라갈 수 없으며, exec는 -T(또는 --no-tty)만 받습니다. compose가 다른 파일이나 프로젝트를 가리키게 하는 옵션(-f, -p, --project-directory, --env-file, --profile)은 어디에 있든 거부됩니다. 그 밖의 경우는 코드 5와 “not available in Control Center agent runs”로 종료됩니다.
스킬이 자체 도구를 호출하는 저장소는 계속 그렇게 할 수 있습니다. cli 구성 요소의 agentPassthrough 블록은 에이전트가 실행할 수 있는 명령을 선언합니다. 승인된 정의가 선언한 명령만 통과하며, 각 명령은 호스트에서 실행되므로 호스트에서 명령 실행 규칙이 적용됩니다. 이 규칙은 기본적으로 먼저 묻습니다:
"agentPassthrough": { "binary": "acme", "allow": [ { "argv": ["env", "ls"], "maps": "status", "nameFilter": true }, { "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 }, { "argv": ["env", "create"], "maps": "up", "positionalName": 2, "pathFlags": ["--web-dir"], "denyFlags": ["--force"] }, { "argv": ["env", "logs"], "maps": "logs", "positionalName": 2, "denyFlags": ["--follow"] } ]}maps는 정책이 적용될 작업을 지정합니다. positionalName은 해당 인수를 이 스페이스의 환경으로 강제하고, nameFilter는 JSON 출력을 그 환경으로 필터링하며, 모든 pathFlags 값은 실행의 워크트리 안으로 해석되어야 합니다. 어떤 규칙과도 일치하지 않는 명령은 코드 5로 종료됩니다.
같은 작업을 도구로도 쓸 수 있습니다: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app, environment_stop_app. 샌드박스의 에이전트는 포트에 직접 닿고 환경의 호스트 이름에는 실행의 프록시를 통해 닿으므로, URL을 추측하지 말고 environment_status에서 엔드포인트를 읽도록 지시합니다.
포크 풀 리퀘스트
섹션 제목: “포크 풀 리퀘스트”포크 PR의 코드는 신뢰할 수 없으며, 호스트 배치에서는 서버의 OS 사용자로 실행됩니다. policy.forkPrs가 동작을 결정합니다.
| 값 | 효과 | 기본 적용 대상 |
|---|---|---|
rig |
compose 파일이 확인 없이 VM에서 실행됨 | compose와 task 구성 요소만 있는 정의 |
approval |
시작할 때마다 관리자가 필요함 | 다른 모든 정의 |
deny |
거부됨 | 없음 |
seedFiles는 보통 비밀 정보이므로 포크에는 복사되지 않습니다. 이를 바인딩하는 compose 파일은 누락된 파일을 이름으로 알려 줍니다.provision과archive작업은 건너뜁니다. 정책이rig이면 VM에서 실행됩니다.- 호스트 배치에서는 포크의
privileged, 호스트 네임스페이스, Docker 소켓 바인드,devices, 스페이스 워크트리 밖의 바인드가 거부됩니다. 신뢰된 스페이스에서는 경고만 표시됩니다.
리그 배치
섹션 제목: “리그 배치”"placement": "rig"는 compose와 task 구성 요소를 전용 microVM에서 실행합니다. process, cli, app 구성 요소가 있는 정의는 대상이 아닙니다. compose 파일은 수정 없이 실행되며, 호스트 Docker 소켓과 운영자 자격 증명이 없고, 네트워크 접근은 이미지에 필요한 레지스트리로 제한됩니다. 워크트리는 라이브로 마운트됩니다.
- arm64 게스트. Apple Silicon에서 게스트는 arm64이므로 amd64 전용 이미지는 실행되지 않습니다.
- 비공개 레지스트리는 거부됩니다. 게스트에는 레지스트리 자격 증명이 없으므로, 알려진 공개 레지스트리 밖의 이미지는 VM이 부팅되기 전에 거부됩니다. 공개 레지스트리의 비공개 저장소는 게스트가 가져올 때 실패합니다.
- 16GiB 스토리지. 스택의 모든 이미지와 볼륨이 하나의 16GiB 디스크를 공유하며 늘릴 수 없습니다.
- 첫 부팅은 느립니다. 이미지 레이어는 VM별이므로 첫 부팅에서 모두 가져옵니다. 중지된 리그는 디스크를 유지합니다.
- 기본 이미지를 읽을 수 있어야 합니다. 기본 이미지를 변수로 지정하는 Dockerfile은 계획할 수 없습니다. 네트워크 접근이 부팅 시 고정되기 때문입니다.
- 수명.
policy.rigTtlHours가 VM을 종료하며 기본값은 24시간입니다.
도구 작성자를 위한 상태 계약
섹션 제목: “도구 작성자를 위한 상태 계약”statusMap이 없는 cli 구성 요소는 기본 계약 cc-env/1을 기대합니다. status 동사는 이 객체를 stdout에 출력합니다.
{ "state": "ready", "detail": "migrations applied, HTTP 200", "endpoints": [ { "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true }, { "role": "postgres", "label": "Postgres", "hostPort": 49213 } ], "services": ["server", "postgres"], "needsRecreate": false, "error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }}state는ready,starting,stopped,failed,missing중 하나입니다.missing은create로,stopped와failed는start로 이어집니다.missing은 종료 코드 0으로 보고합니다. 실패한status는failed로 간주됩니다.state만 필요합니다. 알 수 없는 필드는 무시되고, 구문 분석할 수 없는 출력은 원문을 세부 정보로 하여 저하 상태로 표시됩니다.- URL은 루프백,
*.localhost또는routing.domain아래여야 하며, 그렇지 않으면 버려집니다. needsRecreate: true는 데이터를 버리는 다시 만들기을 표시합니다. Control Center는 이 값만으로 스스로 동작하지 않습니다.list동사는 이름 또는name이 있는 객체의 JSON 배열을 출력합니다.
종료 코드는 모든 동사에 적용됩니다.
| 코드 | 의미 |
|---|---|
| 0 | 정상 |
| 3 | 터미널에서 응답이 필요합니다(예: sudo 암호). interactive에 나열된 동사는 시작을 누른 사람의 터미널 탭에서 다시 실행됩니다. 그 밖의 경우 터미널에서 실행은 도구의 command가 입력만 되고 실행되지 않은 스페이스 터미널을 열고, 이후 재시도가 다시 시도합니다. Control Center는 sudo를 실행하지 않으며, 프롬프트에 응답하지도 않습니다 |
| 4 | 로그인이 필요합니다. 도구의 command에 방법이 나와 있습니다 |
| 5 | 의존하는 대상을 사용할 수 없습니다(예: 실행되지 않는 컨테이너 런타임) |
| 기타 | 실패 |
코드 3, 4, 5는 실패가 아닙니다. 환경은 조치 필요로 표시되고 기다리며, 다음 시작은 그 전에 멈춘 지점부터 이어집니다. 이 중 하나로 종료되는 작업도 같은 뜻입니다.
진행 상황은 줄바꿈으로 구분된 JSON으로 stderr에 출력합니다.
{"type":"step","id":"images","label":"Pull images","state":"running"}{"type":"log","stream":"stdout","line":"postgres Pulled"}{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}환경이 시작되는 동안 패널에는 시작 과정에서 거치는 구성 요소가 나열되며, 각 항목에 스피너, 체크 표시 또는 X 표시가 붙습니다. step 줄은 도구가 지금 무엇을 하고 있는지 알려 주며, 그 label은 도구 자체 행 아래에 표시됩니다. 단계가 행을 추가하지는 않습니다. 단계의 state는 pending, running, done, failed 중 하나이며, state가 없는 단계는 실행 중입니다. 같은 id(문자열 또는 숫자, 없으면 같은 label)로 다시 보고된 단계는 이전 내용을 대체하므로, 스피너가 하나뿐인 도구는 id를 유지하고 label만 바꿀 수 있습니다. id가 없으면 단계는 순서대로 이어지며, 새 단계가 이전 단계를 끝냅니다. 명령이 종료되면 아직 실행 중인 단계는 명령의 결과와 같은 방식으로 끝납니다.
log 줄은 도구가 JSON으로 감싼 출력 한 줄을 담고 있으며, 일반 출력 텍스트로 읽힙니다. note는 실행 출력으로 가고, "level": "warn"이 있는 것은 경고로서 환경에도 남습니다. 마지막 줄이 error 유형이면 구조화된 오류가 되며, command를 복사할 수 있고, 출력의 마지막 12줄이 message 아래에 표시됩니다. 없으면 Control Center는 stderr의 마지막 20줄을 표시합니다. JSON이 아닌 것은 모두 일반 로그 출력입니다.