프로젝트
프로젝트는 Control Zero에서 최상위 조직 단위입니다. 프로젝트는 특정 AI 에이전트 집합의 정책, API 키, 감사 로그를 하나로 묶습니다.
프로젝트란?
프로젝트는 거버넌스를 위한 논리적 경계를 나타냅니다. 일반적으로 환경별(예: production, staging) 또는 애플리케이션별(예: customer-support-agent, data-pipeline-agent)로 프로젝트를 하나씩 만듭니다.
각 프로젝트에는 다음이 있습니다.
- 고유한 프로젝트 ID(예:
proj_abc123). - SDK 인증을 위한 하나 이상의 API 키.
- 이 프로젝트의 에이전트에 대한 거버넌스 규칙을 정의하는 정책 집합.
- 이 프로젝트에 연결된 SDK가 내린 모든 정책 결정의 감사 로그.
프로젝트 만들기
Control Zero 대시보드 또는 API를 통해 프로젝트를 만들 수 있습니다.
대시보드
- 사이드바에서 Projects로 이동합니다.
- Create Project를 클릭합니다.
- 이름과 선택적 설명을 입력합니다.
- Create를 클릭합니다.
API
curl -X POST https://api.controlzero.ai/v1/projects \
-H "Authorization: Bearer YOUR_ORG_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "production-agents",
"description": "Production AI agent governance"
}'
응답:
{
"id": "proj_abc123",
"name": "production-agents",
"description": "Production AI agent governance",
"created_at": "2026-03-01T00:00:00Z"
}
API 키
각 프로젝트에는 SDK가 인증하고 정책 번들을 다운로드할 때 사용하는 API 키가 있습니다.
키 유형
| 유형 | 접두사 | 용도 |
|---|---|---|
| Live | cz_live_ | 프로덕션용. 전체 정책 적용과 감사 로깅. |
| Test | cz_test_ | 개발 및 테스트용. 정책은 평가되지만 액션은 차단되지 않습니다(로그 전용 모드). |
키 관리
프로젝트 설정 페이지에서 API 키를 만들고, 교체하고, 폐기할 수 있습니다.
- 만들기: 프로젝트용 새 키를 생성합니다. 여러 개의 활성 키를 동시에 둘 수 있습니다.
- 교체: 새 키를 생성하고 이전 키에 만료 시점을 설정합니다. 이렇게 하면 다운타임 없이 키를 교체할 수 있습니다.
- 폐기: 키를 즉시 무효화합니다. 폐기된 키를 사용하는 SDK는 다음 정책 새로 고침 시 접근 권한을 잃습니다.
영어 원문 -- 번역은 기술 검토 대기 중입니다
API keys are shown only once at creation time. Store them securely. If you lose a key, you must create a new one.
SDK에서 키 사용하기
SDK를 초기화할 때 API 키를 전달합니다.
# Python
from controlzero import Client
client = Client(api_key="cz_live_your_api_key_here")
// Go
client, err := controlzero.New(
controlzero.WithAPIKey("cz_live_your_api_key_here"),
)
환경 변수로 API 키를 설정할 수도 있습니다.
export CONTROLZERO_API_KEY="cz_live_your_api_key_here"
영어 원문 -- 번역은 기술 검토 대기 중입니다
The API key determines the project. Each key belongs to exactly one project, and
the project identity arrives inside the signed policy bundle — there is no
CONTROLZERO_PROJECT_ID environment variable. Run controlzero whoami to see
which project and org the key in your environment maps to.
정책 할당
정책은 프로젝트 수준에서 할당됩니다. 프로젝트 안에서 정책을 만들거나 수정하면, 해당 프로젝트용으로 컴파일되는 다음 정책 번들에 자동으로 포함됩니다.
활성 정책
게시된 정책만 정책 번들에 포함됩니다. 초안 정책은 적용되지 않습니다.
프로젝트에는 여러 개의 활성 정책이 있을 수 있습니다. 모든 활성 정책이 각 액션 검사마다 평가됩니다. 모든 정책의 규칙이 결합되어 표준 평가 순서에 따라 함께 평가됩니다.
정책 버전 관리
정책을 게시할 때마다 새 버전이 만들어집니다. 다음을 할 수 있습니다.
- 모든 정책 버전의 이력을 확인합니다.
- 필요하면 이전 버전으로 롤백합니다.
- 버전을 비교하여 무엇이 바뀌었는지 확인합니다.
프로젝트 설정
| 설정 | 설명 | 기본값 |
|---|---|---|
| 기본 효과(Default Effect) | 어떤 정책 규칙도 액션과 일치하지 않을 때 적용되는 효과. | deny |
| 번들 새로 고침 간격(Bundle Refresh Interval) | SDK가 새 정책 번들을 폴링하는 주기(초). SDK 기본값은 서로 다릅니다: Python 60, Node 300. | 60 |
| 로그 전용 모드(Log-Only Mode) | 활성화하면 정책이 평가되고 기록되지만 액션은 차단되지 않습니다. | false |
영어 원문 -- 번역은 기술 검토 대기 중입니다
Audit log retention is not a project setting. It is configured per organization, defaults to 30 days today, and an owner can set it between 1 and 2555 days; see Account Management.
프로젝트 구성
프로젝트를 구성하는 일반적인 패턴은 다음과 같습니다.
환경별: production, staging, development용 프로젝트를 각각 만드세요. 프로덕션에는 엄격한 정책을 적용하고 개발 환경은 더 느슨하게 유지할 수 있습니다.
애플리케이션별: 서로 다른 에이전트 애플리케이션마다 프로젝트를 하나씩 만드세요.
영어 원문 -- 번역은 기술 검토 대기 중입니다
This isolates policies and audit logs per application.
팀별: 팀마다 프로젝트를 만들어 정책 관리를 위임하면서 조직 차원의 감독을 유지하세요.
이 패턴들을 조합할 수도 있습니 다.
영어 원문 -- 번역은 기술 검토 대기 중입니다
For example, customer-support-production and customer-support-staging give you both application and environment isolation.