AI用のサンドボックス作成ツール hanare を作りました

コーディングエージェントなどのAIエージェント向けのサンドボックス作成ツールのhanareというものを作りました。

https://github.com/lambdasakura/hanare/

# 準備
hanare build

# サンドボックス作成
hanare start <プロジェクトディレクトリ>

# サンドボックス削除
hanare stop <プロジェクトディレクトリ>

こんな感じに利用できます。 hanare start するとコンテナ内にtmuxセッションが起動します。
hanare start するときにこのセッションの存在確認も実施するので、間違ってターミナルを閉じたりしても再度 hanare start するだけで作業を継続できます。

config ディレクトリをカスタマイズすることで、自分の気にいったシェル環境にカスタマイズすることも出来るので普段使っている設定ファイルを持ち込むことで違和感なく利用することができます。

もちろんサンドボックスとなるように作っています。機密情報やプロジェクトのディレクトリは、ボリュームマウントで与える仕組みになっているます。意図しない機密情報を与えることを避けることが出来ます。

なぜ作ったのか？

DevConatainerへの不満

Claude Code などのコーディングエージェントを利用するのは、ほぼ日常となってきました。ただ、その動作については安全面などに課題が多いのが現状です。意図しないファイルを削除してしまったり、機密情報を漏洩してしまったりなど様々な操作を行ってしまう可能性があります。

これへの対策としてコーディングエージェントを隔離された空間(サンドボックス)で動作させることが行われています。色々な方法が取られていますが、devcontainerを利用しているという人も多いのではないでしょうか。devcontainerはコーディングエージェントを隔離するという目的は達成できますが、個人的にはいくつか課題を感じていました。具体的には以下のような課題です。

• worktreeなどを利用する場合に隔離する単位に迷いが生じる
  • worktreeごとにdevcontainerを作るのか？worktreeの作成元のdevcontainerでどうにかするのか？
    • worktree自体の追加、削除を行う場合は大本のディレクトリは意識しないといけないので考慮事項が多い
• VSCodeを起動しないといけない
  • コーディングエージェント主体の場合、編集能力は最小限でいいためVSCodeの機能はほとんど必要ない
  • devcontainer-cliがあるが機能が不足している印象
• 環境に変更があるたびにコンテナのビルドが必要
• プロジェクトごとに仕組みを作らないといけない
• devcontainerだと複数プロセスを起動する場合に考慮が必要
  • Claude CodeのTeamAgentを利用する、CodexとClaude Codeで相互にやり取りする、Claude Codeを起動している隣で別の操作を行う、など複数プロセスを前提している作業が多いが、devcontainerでこういったことをするのは手間

さらに、コーディングエージェントメインに開発を行っているとほとんどエディタを開くことがありません。git diff などで差分を確認したりすることが主でコードの編集を行うことはほとんど無くなってしまいました。

作りたいサンドボックスの方向性

コーディングエージェントは自由にツールを使う、自分も並行して作業しているという環境を考えると色々な便利なツールが利用できるサンドボックス環境を作る方が良さそうです。最小限の環境を考えるDevContainerとは完全に逆です。ただし、軽量な隔離環境が欲しいのでコンテナで構築するのは変わらずその方針にしたいです。一方でコンテナイメージのビルドは極力避けたいです。

色々整理していくと

• シェルでよく使うようなツール群はコンテナに含まれていてほしい
• コンテナのビルドを避けたいので極力コンテナイメージは使いまわしたい
• とはいえプロジェクトごとに開発ツールの環境は固定したい
  • Node.jsのバージョンなどはプロジェクトで決めたい
• 開発に使うPostgresなどのミドルウェアはコンテナで利用する

こういう感じになりました。基本的なツールはベースイメージに含めてしまえばいいでしょう。問題はプロジェクト固有のツールについてです。これについては、mise(https://mise.jdx.dev/) などを使って別途揃えてしまうことにしました。さらに miseのインストールディレクトリをコンテナにマウントして共有することにすればコンテナ間で使いまわすことが可能になります。

あとは、このように構成したコンテナにプロジェクトディレクトリをボリュームマウントすればすべてのプロジェクトで同じコンテナイメージを利用しつつ、プロジェクトごとに適切なツールを使うことが可能になります。worktreeへの対応も、miseによる環境統一を期待しているので1つのコンテナで複数のworktreeを扱ってしまって気にしないことにしてしまいます。

ミドルウェアはコンテナで用意する方向にしたいので、コンテナ内でdockerコマンドが利用できるようにホスト側のdockerのソケットを共有して利用する DooD(Docker outside of Docker) の形で利用できるようにします。

実装

概ね実装の方針が定まったので、あとは気合で実装するだけです。とりあえずシェルで実装して気に入ったら後からgoなどでバイナリ化するかもしれません。基本的に前節で説明したことを実現しつつ機密情報、設定情報などを与える仕組みを加えたものになりました。

• config、sshディレクトリをコンテナに与えて各種プログラムの設定は行う
• ~/.claude、~/.codex といったコーディングエージェント用のディレクトリ、設定は自動的にマウント
  • 利便性のために一旦こうしている。そのうち変更する可能性はある
• devcontainerと同じくベースのコンテナはsleep infinityを行って、ユーザのプロセスはexecで新しく作成する
  • ユーザにはtmuxを起動するようにして、想定しない終了に備え永続化
• ベースイメージはカスタマイズできるようにしておく
  • これを弄る場合にはコンテナのリビルドが必要になるので極力しない想定
• LinuxとWindowsを想定してそれぞれbashスクリプト、PowerShellスクリプトで実装

実際のコードやもっと詳しい説明はリポジトリのREADMEを確認してみてください。

https://github.com/lambdasakura/hanare

名前は hanare です。母屋と離れというような意味の離れです。隔離空間なので別の建物をイメージしています。

利用の流れ

hanare build を最初に実行して、hanare start <プロジェクトディレクトリ> すると以下のようにtmuxが起動します。

あとは、/workspaceの下に指定したディレクトリがマウントされています。そこに、cdして claudeなりcodexなりを起動して開発を進めることができます。

claude codeとcodexは最初からインストールされています。ホスト側の設定を引き継いでいるので、特に認証なども不要で利用できるはずです。tmuxが起動しているので、ペインを増やしたりすることで並行で作業を行うこともできます。

mise、dockerについてもWindows、Linux環境で問題なく利用できたので開発ツールに関してもプロジェクト内で統一して作業できます。適宜mise useしたり、config/mise/config.toml を編集したりして利用できます。なお、設定ファイルについては hanare のディレクトリにあるconfigを読み取るようにしているので注意してください。

他のプロジェクトを開発するときでも同じコマンドで開始するだけで閉鎖空間が手に入るので楽です。miseのディレクトリは共通になっているので、インストールや起動に時間もかかりません。

今後の予定

とりあえず、実際に使ってみて便利に使えているのでじんわり育てていこうかなと思っています。複数プロジェクトが入っているディレクトリをまとめて面倒見ることもできますし、個別に起動しても隔離空間が手ごろに手に入って便利です。miseを使うことでツールのインストールを毎回実施する必要もなくなったので素早く環境が手に入るのも気に入っています。

コーディングエージェント以外でもOpenClawなどを動かす環境としても利用できると思うので、そちらでも試してみたいですね。

Docker Sandboxについて(追記)

そういえば、docker sandboxについて言及することを忘れていました。docker sandboxはhanareとかなり似ているものですが、ウィンドウを閉じてもセッションが継続する仕組みやmiseを使って複数プロジェクトでも同じコンテナを使うといったことまではやってくれません。また Docker Desktop専用の機能でもあります。手軽に使えるものが欲しかったので自作しています。