flox-environments

Flox 환경

Flox는 단일 TOML 매니페스트에 정의된 재현 가능한 개발 환경을 만듭니다. 팀의 모든 개발자는 macOS와 Linux에서 컨테이너나 VM 없이 동일한 패키지, 도구 및 구성을 사용할 수 있습니다. Nix를 기반으로 150,000개 이상의 패키지에 접근할 수 있습니다.

활성화 시점

사용자에게 환경 관리 문제가 있을 때 이 스킬을 사용하세요. 사용자가 Flox를 언급하지 않았더라도 마찬가지입니다. Flox는 다음과 같은 상황에 적합합니다:

• 프로젝트에 시스템 수준 패키지(컴파일러, 데이터베이스, CLI 도구)가 언어별 의존성과 함께 필요한 경우
• 재현 가능성이 중요할 때 — 동료의 머신, CI, 또는 새 노트북에서도 동일하게 작동해야 하는 경우
• 사용자가 여러 도구를 공존시켜야 할 때 — 예: Python 3.11 + PostgreSQL 16 + Redis + Node.js를 하나의 환경에서
• 크로스 플랫폼 지원이 필요할 때 (동일한 구성으로 macOS와 Linux)
• AI 에이전트가 도구를 설치해야 할 때 — Flox는 에이전트가 sudo, 시스템 오염, 샌드박스 제한 없이 프로젝트 범위의 환경에 패키지를 추가할 수 있게 합니다.

사용자가 시스템 의존성 없이 단일 언어 런타임만 필요하다면, 표준 도구(nvm, pyenv, rustup 등)로 충분할 수 있습니다. 전체 OS 수준의 격리가 필요하다면 컨테이너가 더 적합할 수 있습니다. Flox는 선언적이고 재현 가능하며 컨테이너 오버헤드가 없는 중간 지점에 위치합니다.

전제 조건: Flox가 먼저 설치되어 있어야 합니다. macOS, Linux 및 Docker용 설치는 flox.dev/docs를 참조하세요.

핵심 개념

Flox 환경은 .flox/env/manifest.toml에 정의되며 flox activate로 활성화됩니다. 매니페스트는 패키지, 환경 변수, 설정 훅 및 셸 구성을 선언합니다. 이 모든 것이 환경을 어디서나 재현하는 데 필요합니다.

주요 경로:

• .flox/env/manifest.toml — 환경 정의 (이 파일을 커밋하세요)
• $FLOX_ENV — 설치된 패키지의 런타임 경로 (/usr와 유사 — bin/, lib/, include/ 포함)
• $FLOX_ENV_CACHE — 캐시, 가상 환경, 데이터를 위한 영구 로컬 저장소 (재빌드 시에도 유지)
• $FLOX_ENV_PROJECT — 프로젝트 루트 디렉터리 (.flox/가 있는 곳)

필수 명령어

flox init                       # 새 환경 생성
flox search <package> [--all]   # 패키지 검색
flox show <package>             # 사용 가능한 버전 표시
flox install <package>          # 패키지 추가
flox list                       # 설치된 패키지 목록
flox activate                   # 환경 진입
flox activate -- <cmd>          # 서브쉘 없이 환경에서 명령어 실행
flox edit                       # 매니페스트 대화형 편집

매니페스트 구조

# .flox/env/manifest.toml

[install]
# 설치할 패키지 — 환경의 핵심
ripgrep.pkg-path = "ripgrep"
jq.pkg-path = "jq"

[vars]
# 정적 환경 변수
DATABASE_URL = "postgres://localhost:5432/myapp"

[hook]
# 비대화형 설정 스크립트 (매 활성화 시 실행)
on-activate = """
  echo "환경 준비 완료"
"""

[profile]
# 셸 함수와 별칭 (대화형 셸에서 사용 가능)
common = """
  alias dev="npm run dev"
"""

[options]
# 지원 플랫폼
systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]

패키지 설치 패턴

기본 설치

[install]
nodejs.pkg-path = "nodejs"
python.pkg-path = "python311"
rustup.pkg-path = "rustup"

버전 고정

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"          # Semver 범위: 최신 20.x

postgres.pkg-path = "postgresql"
postgres.version = "16.2"         # 정확한 버전

플랫폼별 패키지

[install]
# Linux 전용 도구
valgrind.pkg-path = "valgrind"
valgrind.systems = ["x86_64-linux", "aarch64-linux"]

# macOS 프레임워크
Security.pkg-path = "darwin.apple_sdk.frameworks.Security"
Security.systems = ["x86_64-darwin", "aarch64-darwin"]

# macOS에서 GNU 도구 (BSD 기본값과 다를 때)
coreutils.pkg-path = "coreutils"
coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]

패키지 충돌 해결

두 패키지가 동일한 바이너리를 설치할 때는 priority를 사용합니다 (낮은 숫자가 우선):

[install]
gcc.pkg-path = "gcc12"
gcc.priority = 3

clang.pkg-path = "clang_18"
clang.priority = 5               # gcc가 파일 충돌에서 승리

pkg-group을 사용하여 버전을 함께 해결해야 하는 패키지를 그룹화합니다:

[install]
python.pkg-path = "python311"
python.pkg-group = "python-stack"

pip.pkg-path = "python311Packages.pip"
pip.pkg-group = "python-stack"    # python과 함께 해결

언어별 레시피

Python with uv

[install]
python.pkg-path = "python311"
uv.pkg-path = "uv"

[vars]
UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
PIP_CACHE_DIR = "$FLOX_ENV_CACHE/pip-cache"

[hook]
on-activate = """
  venv="$FLOX_ENV_CACHE/venv"
  if [ ! -d "$venv" ]; then
    uv venv "$venv" --python python3
  fi
  if [ -f "$venv/bin/activate" ]; then
    source "$venv/bin/activate"
  fi

  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

Node.js

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"

[hook]
on-activate = """
  if [ -f package.json ] && [ ! -d node_modules ]; then
    npm install --silent
  fi
"""

Rust

[install]
rustup.pkg-path = "rustup"
pkg-config.pkg-path = "pkg-config"
openssl.pkg-path = "openssl"

[vars]
RUSTUP_HOME = "$FLOX_ENV_CACHE/rustup"
CARGO_HOME = "$FLOX_ENV_CACHE/cargo"

[profile]
common = """
  export PATH="$CARGO_HOME/bin:$PATH"
"""

Go

[install]
go.pkg-path = "go"
gopls.pkg-path = "gopls"
delve.pkg-path = "delve"

[vars]
GOPATH = "$FLOX_ENV_CACHE/go"
GOBIN = "$FLOX_ENV_CACHE/go/bin"

[profile]
common = """
  export PATH="$GOBIN:$PATH"
"""

C/C++

[install]
gcc.pkg-path = "gcc13"
gcc.pkg-group = "compilers"

# 중요: gcc만으로는 libstdc++ 헤더가 노출되지 않습니다 — gcc-unwrapped가 필요합니다
gcc-unwrapped.pkg-path = "gcc-unwrapped"
gcc-unwrapped.pkg-group = "libraries"

cmake.pkg-path = "cmake"
cmake.pkg-group = "build"

gnumake.pkg-path = "gnumake"
gnumake.pkg-group = "build"

gdb.pkg-path = "gdb"
gdb.systems = ["x86_64-linux", "aarch64-linux"]

훅과 프로필

훅 — 비대화형 설정

훅은 매 활성화마다 실행됩니다. 빠르고 멱등성을 유지하세요. 경험상 규칙: 자동으로 실행되어야 한다면 [hook]에, 사용자가 입력할 수 있어야 한다면 [profile]에 넣으세요.

[hook]
on-activate = """
  setup_database() {
    if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
      initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
    fi
  }
  setup_database
"""

프로필 — 대화형 셸 구성

프로필 코드는 사용자의 셸 세션에서 사용 가능합니다.

[profile]
common = """
  dev() { npm run dev; }
  test() { npm run test -- "$@"; }
"""

안티 패턴

절대 경로

# 나쁨 — 다른 머신에서 작동하지 않음
[vars]
PROJECT_DIR = "/home/alice/projects/myapp"

# 좋음 — Flox 환경 변수 사용
[vars]
PROJECT_DIR = "$FLOX_ENV_PROJECT"

훅에서 exit 사용

# 나쁨 — 셸을 종료시킴
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "설정 파일 없음"
    exit 1
  fi
"""

# 좋음 — 훅에서 return, exit 사용하지 않음
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "설정 파일 없음 — 먼저 설정을 실행하세요"
    return 1
  fi
"""

매니페스트에 비밀 저장

# 나쁨 — 매니페스트가 git에 커밋됨
[vars]
API_KEY = "<런타임에 설정>"

# 좋음 — 외부 설정 참조 또는 런타임에 전달
# 사용: API_KEY="<your-api-key>" flox activate
[vars]
API_KEY = "${API_KEY:-}"

멱등성 보호 없는 느린 훅

# 나쁨 — 매 활성화마다 재설치
[hook]
on-activate = """
  pip install -r requirements.txt
"""

# 좋음 — 이미 설치된 경우 건너뜀
[hook]
on-activate = """
  if [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

사용자 명령어를 훅에 넣기

# 나쁨 — 훅 함수는 대화형 셸에서 사용할 수 없음
[hook]
on-activate = """
  deploy() { kubectl apply -f k8s/; }
"""

# 좋음 — 사용자가 호출할 함수는 [profile] 사용
[profile]
common = """
  deploy() { kubectl apply -f k8s/; }
"""

풀스택 예제

PostgreSQL을 사용하는 Python API를 위한 완전한 환경:

[install]
python.pkg-path = "python311"
uv.pkg-path = "uv"
postgresql.pkg-path = "postgresql_16"
redis.pkg-path = "redis"
jq.pkg-path = "jq"
curl.pkg-path = "curl"

[vars]
UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
DATABASE_URL = "postgres://localhost:5432/myapp"
REDIS_URL = "redis://localhost:6379"

[hook]
on-activate = """
  if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
    initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
  fi

  venv="$FLOX_ENV_CACHE/venv"
  if [ ! -d "$venv" ]; then
    uv venv "$venv" --python python3
  fi
  if [ -f "$venv/bin/activate" ]; then
    source "$venv/bin/activate"
  fi

  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

[profile]
common = """
  serve() { uvicorn app.main:app --reload --host 0.0.0.0 --port 8000; }
  migrate() { alembic upgrade head; }
"""

[services]
postgres.command = "postgres -D $FLOX_ENV_CACHE/pgdata -k $FLOX_ENV_CACHE"
redis.command = "redis-server --port 6379 --daemonize no"

[options]
systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]

서비스와 함께 활성화: flox activate --start-services

환경 공유

Flox 환경은 git에 네이티브입니다. .flox/ 디렉터리를 커밋하면 모든 협업자가 동일한 환경을 사용합니다:

git add .flox/
git commit -m "Flox 환경 추가"
# 팀원은 다음만 실행하면 됩니다:
git clone <repo> && cd <repo> && flox activate

프로젝트 전반에 재사용 가능한 기본 환경은 FloxHub에 푸시합니다:

flox push                         # 환경을 FloxHub에 푸시
flox activate -r owner/env-name   # 원격 환경을 어디서나 활성화

[include]로 환경을 구성합니다:

[include]
base.floxhub = "myorg/python-base"

[install]
# 기본 위에 프로젝트별 추가
fastapi.pkg-path = "python311Packages.fastapi"

AI 보조 및 바이브 코딩

Flox는 AI 보조 개발 및 바이브 코딩 워크플로우에 이상적입니다. AI 에이전트가 현재 환경에서 사용할 수 없는 도구(컴파일러, 데이터베이스, 린터, CLI 유틸리티)가 필요할 때, sudo 액세스, 시스템 패키지 오염 또는 샌드박스 제한 없이 프로젝트의 Flox 매니페스트에 추가할 수 있습니다.

에이전트에게 중요한 이유:

• sudo 불필요 — flox install은 완전히 사용자 공간에서 작동하므로, 에이전트가 상승된 권한 없이 패키지를 추가할 수 있습니다
• 프로젝트 범위 — 패키지는 전역이 아닌 프로젝트 환경에만 설치되므로, 다른 프로젝트가 충돌 없이 다른 버전을 가질 수 있습니다
• 샌드박스 친화적 — 샌드박스 또는 제한된 환경에서 실행되는 에이전트도 Flox를 통해 필요한 도구를 설치할 수 있습니다
• 되돌리기 가능 — 모든 변경 사항은 manifest.toml에 기록되므로, 원하지 않는 패키지를 시스템 잔여물 없이 깨끗하게 제거할 수 있습니다
• 재현 가능 — 에이전트가 환경을 설정하면, 해당 정확한 설정이 git에 커밋되어 모든 사람에게 작동합니다

에이전트 워크플로우 패턴:

# 에이전트가 도구(예: JSON 처리를 위한 jq)가 필요함을 발견
flox search jq                    # 패키지 존재 확인
flox install jq                   # 프로젝트 환경에 설치

# 또는 더 많은 제어를 위해 매니페스트를 직접 편집
tmp_manifest="$(mktemp)"
flox list -c > "$tmp_manifest"
# [install] 섹션에 패키지를 추가한 후 적용
flox edit -f "$tmp_manifest"

# 도구를 사용할 수 있는 상태로 명령어 실행
flox activate -- jq '.results[]' data.json

이것은 Claude Code 또는 다른 AI 에이전트가 즉석에서 프로젝트 도구를 부트스트랩해야 하는 모든 워크플로우에 Flox를 자연스럽게 적합하게 만듭니다.

디버깅

flox list -c                      # 원시 매니페스트 표시
flox activate -- which python     # 어떤 바이너리가 해석되는지 확인
flox activate -- env | grep FLOX  # Flox 환경 변수 확인
flox search <package> --all       # 더 넓은 패키지 검색 (대소문자 구분)

일반적인 문제:

• 패키지를 찾을 수 없음: 검색은 대소문자를 구분합니다 — flox search --all 시도
• 패키지 간 파일 충돌: 우선해야 하는 패키지에 priority 추가
• 훅 실패: exit 대신 return 사용; ${FLOX_ENV_CACHE:-}로 보호
• 오래된 의존성: $FLOX_ENV_CACHE/.deps_installed 플래그 파일 삭제

관련 스킬

더 깊은 통합을 위해 Flox Claude Code 플러그인의 일부로 다음 스킬을 사용할 수 있습니다:

• flox-services — 서비스 관리, 데이터베이스 설정, 백그라운드 프로세스
• flox-builds — Flox를 사용한 재현 가능한 빌드 및 패키징
• flox-containers — Flox 환경에서 Docker/OCI 컨테이너 생성
• flox-sharing — 환경 구성, 원격 환경, 팀 패턴
• flox-cuda — CUDA 및 GPU 개발 환경

flox.dev/docs에서 자세히 알아보고 설치하세요.