セットアップ

Nix が導入済みであれば、対応する開発シェルの system で本ページの「環境に入る」以降を使用できる。Windows では先に Windows (WSL) で WSL 内に環境を作る (NixOS 経路では bootstrap がここまで自動で行う)。

前提

Nix — flakes を有効化すること
direnv — 任意。導入すると cd だけで環境に入る
Docker — 任意。コンテナ環境を使う場合のみ

Nix の導入

以下は x86_64-linux 専用の固定済み手順である。macOS (x86_64-darwin / aarch64-darwin) および aarch64-linux では実行しない。それらの system では Nix 公式の対象 system 向け導入手順で Nix を導入し、本ページの「環境に入る」へ進む。本リポジトリは、それらの system 向けインストーラと sha256 を固定していない。

配布物をバージョン固定で取得し、チェックサムを検証してから展開する。curl ... | sh のようにインストーラを検証せず実行する方式は用いない。

チェックサムは以下に固定した値を使う。配布元から取得した値との照合は、配布元が差し替えられれば同時に差し替わるため検証にならない。

NIX_VERSION=2.35.1
NIX_SHA256=c3fe29778acaa93b5095ee66e36f11ec7c6a284c40970a24cc83ac4f04809db3
TARBALL="nix-${NIX_VERSION}-x86_64-linux.tar.xz"

curl -LO "https://releases.nixos.org/nix/nix-${NIX_VERSION}/${TARBALL}"
echo "${NIX_SHA256}  ${TARBALL}" | sha256sum -c -
tar -xf "${TARBALL}"
"nix-${NIX_VERSION}-x86_64-linux/install" --daemon

tarball 名、インストーラのパス、checksum コマンドはいずれも system に依存する。ほかの system で上記の sha256 だけを置き換えても動作しない。機能ごとの対応状況は対応範囲にある。

続いて flakes を有効化する (~/.config/nix/nix.conf または /etc/nix/nix.conf)。

experimental-features = nix-command flakes

環境に入る

git clone https://github.com/sabas0ba/dotfiles.git ~/repos/dotfiles
cd ~/repos/dotfiles

nix develop
scripts/check-env.sh

flake.lock を同梱しているため、同じ system では同じ入力から開発シェルを構築する。開発シェルを出力する system は対応範囲にある。

direnv

導入すると cd で環境に入り、ディレクトリを離れると元に戻る。

# シェルにフックを追加する (bash の例)
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

# nix-direnv を有効化する (flake の評価結果をキャッシュする)
mkdir -p ~/.config/direnv
echo 'source $HOME/.nix-profile/share/nix-direnv/direnvrc' >> ~/.config/direnv/direnvrc

cd ~/repos/dotfiles
direnv allow

マシン固有の設定は .envrc.local に置く。git 管理外で、.envrc から読み込まれる。

Claude Code のクラウド環境

Claude Code のリモート実行環境では、セッションごとに Nix を持たない Ubuntu のコンテナが用意される。.claude/settings.json の SessionStart フックが scripts/cloud-setup.sh を呼び、本ページと同じ手順で環境を構成するため、手動の操作は要らない。

この経路の対象 system は対応範囲にある。ほかの CPU architecture には固定済みの Nix 配布物がなく、cloud-setup.sh は取得前に停止する。

Nix の導入 — 版と sha256 は scripts/nix-pin.sh で定義し、WSL の Ubuntu 経路と共有する。systemd が無いため単一利用者の方式で入れる
開発シェルの実体化 — nix develop の結果を profile として置く (Dockerfile と同じ処理)
環境の引き渡し — 開発シェルの PATH と DOTFILES_ENV をセッションに渡す。以降のコマンドは nix develop を経由せず開発シェルと同一のツールで動く
構成の記録 — 何を元にどう構成したかを /var/log/dotfiles/cloud-setup.log に残す (構成の記録)

コンテナの状態は保存されるため、2 回目以降の開始は速い。フックは CLAUDE_CODE_REMOTE=true の環境でのみ動作する。

環境に指定する設定

環境セレクタ (claude.ai/code の入力欄の上にある雲のアイコン) から作成・変更する。

項目	指定
Network access	Trusted (既定)。変更しない
Environment variables	不要。`nix/packages.nix` に無いツールを足す場合のみ `DOTFILES_EXTRA_PACKAGES` (追加のパッケージを指定する)
Setup script	不要

Trusted の許可リストには *.nixos.org が含まれ、フックが必要とする releases.nixos.org (Nix 本体) と cache.nixos.org (依存のバイナリ) が共に通る。None ではフックが Nix を取得できず、開発シェルの無いセッションになる。Custom では上記の 2 つを許可する。

以上は本リポジトリを開いたセッションに対するものである。フックは本リポジトリにあるため、他のリポジトリのセッションでは動作しない。その場合は他のリポジトリで使う。

到達範囲の制限

GitHub への要求はネットワークの設定とは別の proxy を通り、セッションに紐付いたリポジトリだけに制限される。github: 形式の flake の入力は、紐付いていなければ取得できない (403)。Network access を Full にしても変わらない。

nixpkgs — 403 となるが cache.nixos.org から substitute できるため影響しない
home-manager、NixOS-WSL — substitute できない。nix flake check と make hm-switch はここで失敗する

取得を伴わない検査は実行できる。

scripts/check-env.sh                             # 環境のスモークテスト
nix build --no-link .#checks.x86_64-linux.pins   # 個別の検査

すべての検査 (make check) は CI がコンテナ内で行う。イメージは構築時に入力をすべて取り込んでおり、--network none で完結する。

追加のパッケージを指定する

nix/packages.nix に無いツールを、当該セッションに限って足せる。作業対象のリポジトリが必要とする言語のツールチェーン (Python、Go 等) のように、開発環境そのものには入れない依存を想定している。

クラウド環境によっては、セットアップの完了後にネットワークが遮断される (ChatGPT Codex の既定がこれである)。遮断後は取得できないため、セットアップの実行中に store へ入れておく必要がある。指定はここで受ける。

経路	指定方法
SessionStart フック	環境変数 `DOTFILES_EXTRA_PACKAGES`
Setup script	引数 `--extra-packages`、または環境変数

フックのコマンドは .claude/settings.json に固定されており引数を渡せないため、環境変数を使う。双方を与えた場合は併合する。

DOTFILES_EXTRA_PACKAGES="python3 gcc ripgrep"

/opt/dotfiles/scripts/cloud-setup.sh --setup-script --disposable \
  --extra-packages "python3 gcc"

値は nixpkgs の attribute 名を空白区切りで並べたものである。nixpkgs#python3 のような flakeref ではなく、python3 のように名前だけを与える。

nixpkgs のリビジョンは flake.lock が固定したものを使う。開発シェルと同一であり、store も共有する。registry の nixpkgs (固定されていない) は参照しない
配置先は /nix/var/nix/profiles/dotfiles-extra である。開発シェルの profile とは分けてあり、単一情報源である nix/packages.nix の内容には影響しない
PATH では開発シェルのツールより前に置く。名前が重なった場合は追加した側が使われる
profile は毎回、その時点の指定から作り直す。コンテナはセッションをまたいで保存されるため、指定から外したパッケージが残り続けると、開発シェルのコマンドを覆ったまま指定からは分からない状態になる。指定を外せば次のセッションで消える
scripts/check-env.sh の検査対象ではない。当該スクリプトが見るのは nix/packages.nix のツールのみである
名前の誤りは実体化の時点で失敗する。他の構成は最後まで進めたうえで終了状態を失敗とするため、指定を直して再実行すればよい。誤った 1 つのために他のパッケージの導入を中止することはしない
バイナリキャッシュに無いものを指定するとソースからの構築となり、時間がかかる。Setup script の目安 (5 分) を超えると環境のキャッシュが作られない

対象はコマンドを提供するパッケージである。言語のライブラリ (python3Packages.requests 等) は指定しても動かない。profile に入るのは指定したパッケージ自身だけで、それが伝播する依存は揃わないため、import の時点で失敗する。

>>> import requests
  File ".../site-packages/requests/__init__.py", line 43, in <module>
    import urllib3
ModuleNotFoundError: No module named 'urllib3'

ライブラリを含む環境は python3.withPackages のような合成を要し、attribute 名の列挙では表せない。必要な場合は nix/packages.nix に式として書く。

恒久的に必要なツールはここではなく nix/packages.nix に追加する。手順はツールを追加するにある。本節の指定は環境の設定にしか残らず、他の環境 (手元、Docker、CI) には反映されない。

構成の記録

scripts/cloud-setup.sh は、実行のたびに何を元にどう構成したかを /var/log/dotfiles/cloud-setup.log へ追記する。構成の出力はセッションの終了とともに失われ、コンテナも作り直されるため、後から確認する手段が他に無い。

=== 2026-08-26T10:59:57Z 開始
経路            hook
引数            (なし)
dotfiles        fc4cdec... 2026-08-26 Merge pull request #34 from ...
nix (固定)      2.35.1
追加パッケージ  hello cowsay
環境変数
  CLAUDE_CODE_REMOTE=true
  CLAUDE_ENV_FILE=/root/.claude/session-env/.../sessionstart-hook-0.sh
  CODEX_HOME=(未設定)
  DOTFILES_EXTRA_PACKAGES=hello cowsay
  HOME=/root
  USER=root
--- 2026-08-26T11:00:05Z 終了 (状態 0)
nix (実行)      nix (Nix) 2.35.1
nixpkgs         597283ad8aa0b331c788e97c4c262d58877074ef
追加パッケージ  実体化できなかったもの: (なし)

記録する環境変数は上記の名前に限る。env の全体を取って名前のパターン (*TOKEN* 等) で除外する方式は採らない。パターンに一致しない名前の秘密があれば、その値が記録されるためである。変数を足す場合は、値が秘密になりえないものに限る。

未コミットの変更がある場合、dotfiles の行に「(未コミットの変更あり)」が付く。開発シェルの評価対象は HEAD ではなく作業ツリーであり、リビジョンだけでは別の内容の環境が同じ記録になるためである。未追跡のファイルは対象に含めない (flake の評価は git の管理下にあるものだけを見るため、環境の内容を変えない)
入力は開始時に書き、結果は終了時に書く。終了時にまとめて 1 度で済ませると、途中で異常終了した場合に何も残らず、記録が最も要る場面で失われる
構成が失敗した場合も記録される。終了状態がそのまま残る
引数の誤り、リモート実行環境でない場合、--disposable の欠落では記録しない。いずれも何も構成せずに終わるため、記録する対象が無い
記録先に書けない場合は、その旨を出力して構成を続ける。環境が構成できることを、記録が残ることより優先する
記録先はリポジトリの checkout と $HOME の双方から独立させてある。前者はセッションごとに作り直され、後者は --setup-script が上書きするため、いずれに置いても履歴が残らない

他のリポジトリで使う

本リポジトリ以外の開発で本環境を使う場合は、クラウド環境の Setup script に以下を書く。フックは本リポジトリにしか無いため、環境の側から入れる。DOTFILES_REV は利用する40桁の commit SHAへ置き換える。branch や tag は指定できない。

#!/bin/bash
set -euo pipefail

DOTFILES_REV=${DOTFILES_REV:-REPLACE_WITH_40_HEX_COMMIT_SHA}
DOTFILES_URL=https://github.com/sabas0ba/dotfiles.git
DOTFILES_DIR=/opt/dotfiles

if [[ ! "$DOTFILES_REV" =~ ^[0-9a-fA-F]{40}$ ]]; then
  echo "DOTFILES_REV に40桁の commit SHAを指定してください。" >&2
  exit 1
fi

if [ -e "$DOTFILES_DIR" ] && [ ! -d "$DOTFILES_DIR/.git" ]; then
  echo "$DOTFILES_DIR は dotfiles の checkout ではありません。" >&2
  exit 1
fi

if [ ! -d "$DOTFILES_DIR/.git" ]; then
  git clone --no-checkout "$DOTFILES_URL" "$DOTFILES_DIR"
else
  origin=$(git -C "$DOTFILES_DIR" remote get-url origin)
  if [ "${origin%.git}" != "${DOTFILES_URL%.git}" ]; then
    echo "$DOTFILES_DIR の origin が異なります: $origin" >&2
    exit 1
  fi
  if [ -n "$(git -C "$DOTFILES_DIR" status --porcelain --untracked-files=normal)" ]; then
    echo "$DOTFILES_DIR に未コミットの変更があります。" >&2
    exit 1
  fi
fi

git -C "$DOTFILES_DIR" fetch --depth 1 origin "$DOTFILES_REV"
resolved=$(git -C "$DOTFILES_DIR" rev-parse --verify 'FETCH_HEAD^{commit}')
if [ "$resolved" != "${DOTFILES_REV,,}" ]; then
  echo "取得した commit が DOTFILES_REV と一致しません。" >&2
  exit 1
fi
git -C "$DOTFILES_DIR" checkout --detach "$resolved"

"$DOTFILES_DIR/scripts/cloud-setup.sh" --setup-script --disposable

途中で Nix の取得や build が失敗しても、同じ DOTFILES_REV でそのまま再実行できる。既存 checkout の origin と working tree を確認してから再利用するため、別の repository や編集済みファイルを上書きしない。

--disposable は、実行先が使い捨ての環境であることの明示である。本経路は /usr/local/bin と $HOME を書き換えるため、指定が無ければ実行しない。フックと違い Setup script は Claude Code の起動より前に走るため CLAUDE_CODE_REMOTE を持たず、コンテナであることを示す印 (/.dockerenv、/run/.containerenv、/proc/1/cgroup) も当該環境には無い。環境から判定できないため引数で明示する。

本リポジトリは public であり、セッションに紐付いていなくても clone できる (tarball は 403 だが git 経由は通る)。

本リポジトリ自身も DOTFILES_REV で固定する。使用したリビジョンは --setup-script が最初に出力する。後から見る場合は checkout を直接見る。

git -C /opt/dotfiles log -1 --format='%H %cs %s'

--setup-script は、環境変数を引き渡す代わりに実体を配置する。

処理	フック	Setup script
Nix の導入	行う	行う
開発シェルの実体化	行う	行う
環境の引き渡し	`$CLAUDE_ENV_FILE` へ書く	行わない
ツールの配置	行わない	`/usr/local/bin` へ symlink する
ホームの構成の配置	行わない	`home/` 以下を `$HOME` へ置く (`home/.codex/` は `$CODEX_HOME` が設定されていればその直下へ置く)
system の構成の配置	行わない	`etc/` 以下を `/etc` へ置く。`codex/config.toml` は既存 TOML へ overlay する
追加パッケージ	環境変数で指定する	引数または環境変数で指定する
構成の記録	行う	行う

Setup script には CLAUDE_ENV_FILE が無く、セッションのシェルは /etc/profile を読まないため、環境変数では渡せない。既に PATH にある /usr/local/bin へ、選択した nix build .#<profile> の内容 (nix/packages.nix) と nix 自身を置く。再実行時は現在のリビジョンから profile を再評価し、追加されたコマンドを配置するとともに、前回管理していた削除済みコマンドのリンクを取り除く。

system の同名のコマンド (git、coreutils 等) は Nix 版に置き換わる。覆ったものは実行時に列挙する
言語のツールチェーン (Node、Python 等) は含まない。クラウド環境が持つものを使うか、追加のパッケージとして指定する
ホームの構成は home-manager を経由しない (前節のとおり取得できないため)。置く内容は同一で、既存のファイルは上書きする。内容が異なるものは初回に <ファイル名>.dotfiles-backup へ退避する
/etc/codex/config.toml は既存内容を初回に .dotfiles-backup へ退避したうえで TOML として merge し、既存の管理外 key を残して dotfiles 側の key を優先する。書き戻しでコメントは失われる (退避先に残る)。merge 結果を読み直して意味が一致しない場合と、yq が型を保てない日時の値を含む場合は、既存ファイルを変更せずに失敗する。dotfiles 側から削除した key は既存ファイルに残る
本経路では DOTFILES_ENV が設定されない。scripts/check-env.sh はコマンドの実体が Nix の store にあることで判定するため、開発シェルを経由せずそのまま実行して成功する
flake が複数の toolchain profile を公開する場合は、Setup script の環境変数 DOTFILES_TOOLCHAIN_PROFILE に output 名を指定できる。未指定時は default となる
初回は数分かかる。Setup script の目安 (5 分) を超えると環境のキャッシュが作られない

ChatGPT Codex のクラウド環境

Codex のクラウド環境では、Environment の Setup script に前節の「他のリポジトリで使う」にある共通 script を設定する。本リポジトリには Codex 向けの自動実行 hook を置いていないため、本リポジトリを対象にする場合も同じ設定を使用する。処理内容、既存ファイルの退避、revision の固定および到達範囲の制約も同じである。

Codex のクラウド環境は、既定では setup script の完了後にネットワークを遮断する。以降は取得ができないため、作業に必要なツールは setup script の中で揃える。nix/packages.nix に無いものは --extra-packages で足す (追加のパッケージを指定する)。

/opt/dotfiles/scripts/cloud-setup.sh --setup-script --disposable \
  --extra-packages "python3 gcc"

セットアップにより home/.codex/AGENTS.md が ${CODEX_HOME:-$HOME/.codex}/AGENTS.md に配置される。Codex はこれを利用者共通の作業指示として直接読み込み、Claude Code は ~/.claude/CLAUDE.md から import する。Codex のクラウド環境では CODEX_HOME=/opt/codex のため、配置先は /opt/codex/AGENTS.md となる。本リポジトリ内では、ルートの AGENTS.md がリポジトリ固有の手順を追加する。

目次に戻る