flox-environments

Flox 환경

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

활성화 시점

사용자가 환경 관리 문제를 가지고 있을 때 이 스킬을 사용하세요. 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 + 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