환경 변수

Multica는 프로세스를 시작할 때 환경 변수를 읽습니다. 수정 후에는 보통 해당 API, Web 또는 데몬을 다시 시작해야 합니다. Docker Compose의 docker compose restart는 .env를 다시 읽지 않으므로 up -d로 컨테이너를 다시 만들어야 적용됩니다.

이 페이지에는 배포자를 위한 설정만 나열하며 테스트 변수와 내부 실행 변수는 다루지 않습니다. 여기서는 그룹별 참조를 제공하고 전체 배포 단계는 자체 호스팅 빠른 시작을 참고하세요.

프로덕션 최소 설정

DATABASE_URL=postgres://user:password@postgres:5432/multica?sslmode=require
JWT_SECRET=<long-random-secret>
APP_ENV=production
FRONTEND_ORIGIN=https://multica.example.com
MULTICA_APP_URL=https://multica.example.com
MULTICA_PUBLIC_URL=https://api.multica.example.com

이메일 서비스도 하나 선택해야 합니다. 설정하지 않으면 인증 코드와 초대가 서버 로그에만 기록됩니다.

API와 데이터베이스

Kubernetes에서 shutdown hold를 설정하면 terminationGracePeriodSeconds가 hold와 실제 종료에 필요한 시간의 합보다 커야 합니다.

primary와 복제본의 연결 한도는 서로 독립적입니다. 모든 API 프로세스의 연결 합계가 PostgreSQL 클러스터 연결 한도 내에 있도록 설정해야 합니다. 복제본 연결은 기본적으로 5분 후 재생성되어 승격 뒤 읽기 전용 상태를 다시 검증합니다. 연결 실패 시 인프라가 투명하게 primary로 폴백하고 짧은 수동 회로 차단기를 열며, 백그라운드 데이터베이스 점검은 추가하지 않습니다. 애플리케이션은 복제본 데이터의 최대 지연을 보장하지 않으므로 데이터베이스 계층에서 복제 지연을 모니터링하고 일관성이 중요한 읽기는 primary에 유지하십시오.

공개 주소와 브라우저 접근

프런트엔드와 API가 서로 다른 host를 사용하고 브라우저가 API 도메인에 직접 접근한다면 COOKIE_DOMAIN을 설정해야 합니다. 설정하지 않으면 브라우저가 CSRF cookie를 읽지 못해 모든 쓰기 요청이 403 CSRF validation failed를 반환하고 읽기 요청만 정상 작동합니다. 두 host를 모두 포함하는 가장 좁은 상위 도메인을 사용하세요(.example.com보다 .agent.example.com이 더 적합). 이 설정은 로그인 세션 cookie를 해당 도메인의 모든 host로 확장하므로 모든 host를 같은 신뢰 주체가 운영할 때만 사용할 수 있습니다. 수정 후 두 host에서 이전 cookie를 삭제하고 다시 로그인해야 합니다. 자체 호스팅 빠른 시작의 same-origin 구성을 사용해 브라우저가 app 도메인에만 접근한다면 비워 두세요. IP 주소는 입력하지 마세요. 브라우저가 IP Domain이 포함된 cookie를 무시합니다.

이메일과 로그인

Resend

SMTP

SMTP_HOST가 비어 있지 않으면 SMTP가 Resend보다 우선합니다.

Google OAuth

가입 범위

allowlist의 정확한 판단 순서는 로그인과 가입을 참고하세요.

첨부 파일 저장소

S3_BUCKET을 설정하지 않으면 Multica가 로컬 디스크를 사용합니다.

S3 또는 호환 저장소

내부 네트워크의 MinIO처럼 브라우저에서 endpoint에 직접 접근할 수 없다면 ATTACHMENT_DOWNLOAD_MODE=proxy를 사용하세요.

로컬 디스크

CloudFront

Redis와 rate limit

reverse proxy 뒤에 배포한다면 실제 proxy 네트워크를 입력해야 합니다. 모든 출처를 그대로 신뢰하지 마세요. 클라이언트가 전달 IP를 위조할 수 있습니다.

인증 rate limit에는 REDIS_URL이 필요하며, 설정하지 않으면 시작 로그에 인증 rate limit이 비활성화되었다고 표시됩니다. 초대 제한은 Redis 없이도 프로세스 메모리에서 동작하고, Redis를 설정하면 여러 replica가 할당량을 공유합니다. 설정된 Redis를 일시적으로 사용할 수 없으면 인증 rate limit은 fail-open하지만, 초대 생성은 보호 없이 이메일을 보내지 않고 재시도 가능한 503을 반환합니다.

외부 연동

GITHUB_APP_ID와 private key를 설정하지 않아도 PR 연결, 미러링, merge 시 done 전환은 정상적으로 작동합니다. 다만 카드에 CI와 merge 가능 상태가 표시되지 않고 "GitHub에서 선택" 저장소 메뉴도 비활성화됩니다.

설정 단계는 GitHub 연동, Feishu Bot, Slack Bot, Telegram Bot을 참고하세요.

서버 측 LLM

이 설정 그룹은 대화 제목 같은 서버 측 보조 생성 기능에 사용됩니다. 에이전트 실행에 사용하는 AI 코딩 도구의 자격 증명이 아닙니다.

MULTICA_LLM_MAX_RETRIES는 재시도 정책의 유일한 설정 소스입니다. 설정하지 않으면 기본값 2회, 0이면 호출당 요청을 정확히 한 번만 보내고, 1–5면 재시도를 최대 그 횟수까지만 합니다. 할당량이 아니라 상한입니다. 재시도 대상 실패만 이를 소모하며, 성공하거나 호출자 자신의 데드라인에 걸리면 더 일찍 끝납니다. 그 밖의 값(음수, 숫자가 아닌 값, 5 초과)은 조용히 보정되지 않고 시작에 실패합니다. 상한은 지연 예산입니다. 백오프는 0.5초에서 시작해 8초 상한까지 두 배씩 늘어나므로, 더 큰 예산은 호출자 자신의 타임아웃을 넘겨 재시도 가능한 실패를 타임아웃으로 바꿉니다. 재시도는 연결 실패와 HTTP 408, 409, 429, 5xx를 대상으로 하며 그 외 4xx는 그대로 반환됩니다. 서버는 시작 시 유효한 정책을 llm retry policy로 기록하며 해당 줄에는 자격 증명이 포함되지 않습니다.

이 레이어를 사용하는 기능은 두 가지이며, 둘 다 설정한 endpoint로 채팅 내용을 전송합니다.

• 대화 제목 자동 생성 — 새 채팅 세션에서 사용자가 보낸 첫 메시지를 그대로 전송합니다. 첨부 파일은 포함되지 않습니다.
• 후속 질문(에이전트 답변 아래의 버튼) — 대화의 마지막 부분을 전송합니다. 최대 6개 메시지이며, 대상 답변은 3000자, 그보다 오래된 메시지는 각각 800자로 제한됩니다.

API key와 base URL이 모두 비어 있으면 이 레이어가 꺼지고 업스트림 요청을 전혀 보내지 않습니다. 위 두 기능 모두 아무것도 전송하지 않습니다. 이 레이어가 채팅 내용을 배포 환경 밖으로 보내면 안 되는 정책이라면 이것이 지원되는 구성입니다. 세션은 클라이언트가 첫 메시지에서 만든 제목을 그대로 사용하고, 후속 질문 버튼은 표시되지 않으며, 나머지 기능은 영향을 받지 않습니다.

데몬 설정

아래 변수는 API 컨테이너가 아니라 에이전트를 실행하는 컴퓨터에서 읽습니다.

데몬이 에이전트 작업에 주입하는 내부 컨텍스트는 작업 런타임 환경을 참고하세요.

각 AI 코딩 도구는 MULTICA_<PROVIDER>_PATH로 명령 경로를 덮어쓸 수 있으며 모델 재정의를 지원하는 도구는 MULTICA_<PROVIDER>_MODEL도 사용할 수 있습니다. QwenPaw와 MiniMax Code에는 모델 변수가 없고 MiniMax Code의 경로 변수는 MULTICA_MCODE_PATH입니다. 자세한 내용은 AI 코딩 도구 비교를 참고하세요. DeepSeek Harness는 MULTICA_DSH_PATH와 MULTICA_DSH_MODEL을 지원합니다(값은 dsh 모델 카탈로그의 모델 ID, 예: deepseek-official/deepseek-chat). ZeroClaw는 MULTICA_ZEROCLAW_PATH를 지원하지만 모델 변수는 없습니다. 모델은 ZeroClaw의 에이전트 설정에서 관리합니다. 컴퓨터 전체 기본 인수 MULTICA_<PROVIDER>_ARGS는 현재 Claude Code, Codex, CodeBuddy, Qwen Code, QwenPaw 다섯 도구를 지원합니다. 해당 변수는 MULTICA_CLAUDE_ARGS, MULTICA_CODEX_ARGS, MULTICA_CODEBUDDY_ARGS, MULTICA_QWEN_ARGS, MULTICA_QWENPAW_ARGS입니다. 예시:

MULTICA_CLAUDE_PATH=/opt/bin/claude
MULTICA_CLAUDE_ARGS=--max-turns 40

우선순위는 명령줄 flag → 환경 변수 → ~/.multica/config.json → 내장 기본값입니다. watchdog 동작은 데몬과 런타임을 참고하세요.

데몬 설정 영속화

자주 사용하는 데몬 측 설정은 shell 환경 변수에 의존하지 않고 ~/.multica/config.json에 기록할 수도 있습니다. 이름 있는 profile의 설정 파일은 ~/.multica/profiles/<name>/config.json에 있습니다.

multica config set poll_interval 10s
multica config show

지원되는 key:

값에는 다음 규칙이 적용됩니다.

• duration key는 양의 Go duration(예: 10s, 2h)을 허용하며 0s와 음수는 거부합니다. 유일한 예외는 agent_timeout입니다. 0s가 유효하며 실행 시간 제한을 명시적으로 끕니다.
• 빈 문자열을 전달하면 저장된 값을 지우고 환경 변수 또는 내장 기본값으로 돌아갑니다. 예: multica config set poll_interval ""
• max_concurrent_tasks는 0 이상의 정수여야 합니다.
• 상대 workspaces_root 값은 저장할 때 절대 경로로 변환됩니다.

관측과 통계

다음 단계

• 로그인과 가입 — 로그인 방식과 가입 제한을 알아봅니다.
• 문제 해결 — 배포 문제의 증상을 확인합니다.
• 데몬과 런타임 — 데몬 측 대응 설정을 알아봅니다.