インストール

console

$ curl -fsSL https://kobune.1024.works/install.sh | sh

環境に合ったアーカイブを選び、公開されている .sha256 と照合し、kobune、 kobuned、kobune-studio を ~/.local/bin に配置します。bash / zsh / fish のうちインストール済みのシェルには、補完スクリプトも書き込みます。

root 権限は一切必要ありません。PATH の設定が必要な場合は、いま使っているシェルの書き方で 1 行だけ表示します。fish なら fish_add_path を示すので、 fish が受け付けない export 行を渡されることはありません。

何をインストールすることになるか

リリースはまだ 1 つもありません。nightly は main のビルドで、マージのたびに差し替えられます。上のコマンドが取得するのもこれです。

kobune --version は、クレートのバージョンとビルド元のコミットを表示します（0.1.0 (a1b2c3d)）。ビルドを識別しているのはコミットのほうです。前に付いている番号はリリースされたことがなく、中身が変わっても据え置かれます。

したがって、一般に「安定版」と呼ばれるものではありません。フラグの名前が変わることも、既定値が変わることもあり、あとから読めるのは、その変更をしたコミットだけです。 CHANGELOG.md は、そうでなくなる日のために置いてあります。

未完成という意味ではありません。Firecracker を除くマイルストーンは着地しており、このページで用意する環境は動きます。まだないのは、動かないでいてくれるバージョンのほうです。

必要なもの

必要なもの	補足
コンテナランタイム	Docker / OrbStack / colima のいずれか。または macOS 26 以降の Apple Container
macOS	全機能に対応しています。Linux でも中核機能は動作しますが、launchd socket activation は利用できません
Rust 1.88 以降	ソースからビルドする場合のみ

デスクトップアプリは任意です。追加の条件についてはデスクトップアプリを参照してください。

インストールスクリプト

実行する前に中身を読んでください。install.sh は POSIX シェルで約 700 行、意外なことは何もしていません。設定は 3 つです。

変数	説明
`KOBUNE_INSTALL_DIR`	バイナリの配置先。既定は `~/.local/bin`
`KOBUNE_CHANNEL`	取得するリリースタグ。既定は `nightly` で、現状これしかありません
`KOBUNE_NO_COMPLETIONS`	何か値を設定すると補完スクリプトを書き込みません

console

$ curl -fsSL https://kobune.1024.works/install.sh | KOBUNE_INSTALL_DIR=/usr/local/bin sh

PATH の設定

配置先が PATH に入っていない場合、追加する方法を表示します。示すのは 1 つ、いま使っているシェルの分だけです。

console

fish_add_path ~/.local/bin

console

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
. ~/.zshrc

console

# macOS は ~/.bash_profile、Linux は ~/.bashrc。ログインシェルは前者しか
# 読まず、macOS のターミナルはログインシェルとして起動します。
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
. ~/.bash_profile

console

echo 'setenv PATH $HOME/.local/bin:$PATH' >> ~/.tcshrc
source ~/.tcshrc

console

# $nu.config-path に追記
$env.PATH = ($env.PATH | prepend '~/.local/bin')

console

# ~/.config/elvish/rc.elv に追記
set paths = ['~/.local/bin' $@paths]

console

# $PROFILE に追記
$env:PATH = "$HOME/.local/bin" + [IO.Path]::PathSeparator + $env:PATH

判定には $SHELL ではなくプロセスツリーを使います。$SHELL はログインシェルであり、zsh でログインしてから fish を起動した時点で別のものになります。 fish で export PATH を渡されると、そのまま設定ファイルに貼られて何か月も壊れたままになりがちです。ksh / mksh / dash も判別し、~/.profile を案内します。

判定できなかったときは推測せず、すべてのシェルの方法を並べて表示します。

インストールされるのは nightly ビルドです。詳しくはこのページ冒頭の何をインストールすることになるかを参照してください。

再実行すればその場で更新されます。kobune update でも同じことができ、こちらはシェルのパイプも 2 回のダウンロードも要りません。

手動でビルド済みバイナリを取得する

スクリプトが取得するのと同じアーカイブです。

マシン	アーカイブ
Apple Silicon	`kobune-aarch64-apple-darwin.tar.gz`
Intel Mac	`kobune-x86_64-apple-darwin.tar.gz`
Linux x86_64	`kobune-x86_64-unknown-linux-gnu.tar.gz`

console

$ gh release download nightly --repo hota1024/kobune \
    --pattern 'kobune-aarch64-apple-darwin.tar.gz*'
$ shasum -a 256 -c kobune-aarch64-apple-darwin.tar.gz.sha256
$ tar xzf kobune-aarch64-apple-darwin.tar.gz
$ cd kobune-aarch64-apple-darwin

macOS は未署名バイナリを隔離します

console

$ xattr -d com.apple.quarantine kobune kobuned kobune-studio

インストールスクリプトはこれを自動で実行します。署名は未解決のため、手動ならこのコマンドを実行するか、ソースからビルドしてください。同じ理由でデスクトップアプリは配布していません。未署名の .app は警告ではなく Gatekeeper に実行そのものを止められます。

ビルド

Kobune はまだ crates.io に公開していないため、ビルドするにはリポジトリをクローンします。

console

$ git clone https://github.com/hota1024/kobune
$ cd kobune
$ cargo build --release --workspace

target/release に 3 つのバイナリが生成されます。

kobune — 操作に使う CLI
kobuned — CLI が通信する daemon
kobune-studio — kobune studio がブラウザに配信するダッシュボード

PATH の通ったディレクトリに配置します。

console

$ cp target/release/kobune target/release/kobuned \
     target/release/kobune-studio ~/.local/bin/

この 3 つは同じディレクトリに置いてください。CLI は自身と同じ場所を参照して残りの 2 つを見つけます。

先にダッシュボードのページをビルドしてください

kobune-studio はページを埋め込んだバイナリです。クローンした直後の cargo build にはビルドすべきページがないため、代わりに「何を実行すればよいか」を書いたプレースホルダが埋め込まれ、バイナリはダッシュボードではなくそれを配信します。

console

$ cd apps/studio/web
$ pnpm install
$ pnpm build

そのうえで上記のビルドを実行してください。これが必要なのはソースからビルドする場合だけで、リリースアーカイブにはページが含まれています。cargo build の後に pnpm build を実行しても構いません。cargo は web/dist を監視しているため、次のビルドでページを取り込みます。

シェル補完

インストールスクリプトを使えば書き込み済みです。手動で用意する場合、あるいはスクリプトが見つけられなかったシェル向けには次のようにします。

fishzshbash

console

$ kobune completions fish > ~/.config/fish/completions/kobune.fish

console

$ mkdir -p ~/.local/share/zsh/site-functions
$ kobune completions zsh > ~/.local/share/zsh/site-functions/_kobune
$ echo 'fpath=(~/.local/share/zsh/site-functions $fpath)' >> ~/.zshrc

console

$ mkdir -p ~/.local/share/bash-completion/completions
$ kobune completions bash > ~/.local/share/bash-completion/completions/kobune

fish は追加設定なしで読み込みます。zsh はディレクトリを fpath に加える必要があるため、1 行余分に書いています。bash は bash-completion 2.x が必要です。

elvish と powershell も指定できますが、生成器に付いてくるだけで動作確認はしていません。

worktree の間を移動する

kobune cd feature/user-auth は、シェルのカレントディレクトリをその workspace の worktree へ移します。これには起動ファイルへの 1 行が必要です。インストールスクリプトはこの行を書きません。シェルが起動のたびに読むファイルへの書き込みは、頼まれてもいないのにやることではないからです。

fishzshbash

console

$ echo 'kobune shell-init fish | source' >> ~/.config/fish/config.fish

console

$ echo 'eval "$(kobune shell-init zsh)"' >> ~/.zshrc

console

$ echo 'eval "$(kobune shell-init bash)"' >> ~/.bashrc

これで kobune という名前のシェル関数が 1 つ定義されます。この関数は cd 以外をすべてそのままコマンドへ渡します。読み込んでいない場合、kobune cd は移動先のパスを表示するだけです。プログラムは、自身を起動したシェルのカレントディレクトリを変えられません。それができるのは、シェル側にいるこの関数です。

最新に保つ

console

$ kobune update
› installing 9f3c1a2…
╭ update ────────────────────────────────────────────────────────────────╮
│ installed  9f3c1a2                                                     │
│                                                                        │
│ › the daemon is still the previous build, so run kobune daemon restart │
╰────────────────────────────────────────────────────────────────────────╯

update は、実行した kobune が置かれているディレクトリを対象に、現在の nightly へ差し替えます。設定で指定した場所ではなく、いま動かしているものを更新します。CLI と daemon は必ず一緒に入れ替えます。ビルドが揃っていないと、両者のあいだのプロトコルが噛み合わなくなるからです。

新しいファイルは既存のファイルの隣に書き出してから rename で置き換えます。実行中のバイナリは書き込めませんが、置き換えることはできます。そのため daemon が動いている状態で更新しても、再起動するまでは古いビルドが動き続けます。最後の 1 行はそのことを指しています。どのマシンでも同じことを言い、違うのは再起動の結果です。daemon の起動は、launchd がジョブを持っていればまず launchd に頼みます。そのため、そこで再起動すれば launchd が起動した daemon が残ります。80 と 443 を保持したまま、いま入ったビルドで動くものです。LaunchDaemon が無いマシンでは頼む相手がいないので、直接起動された daemon が、それまでと同じ代替ポートで動きます。

この 1 行は 状態から導いたもので、常に出るわけではありません。daemon が動いていなければ入れ替えるものはなく、パネルは入れたビルドだけを伝えます。

インストールせずに確認するだけなら次のようにします。

console

$ kobune update --check
╭ update ─────────────────────────╮
│ available  9f3c1a2              │
│ running    c7282b8              │
│                                 │
│ › install it with kobune update │
╰─────────────────────────────────╯

新しいビルドが残した作業

上のパネルが答えられるのは、置き換えられる側のビルドについてだけです。リポジトリの Skill が新しいものと一致しているか、LaunchDaemon が新しいビルドの書く形になっているか。これらに答えられるのは、入った側のビルドだけです。そこで、そのビルドが最初に実行されたときに自分で答えます。

console

$ kobune url web
https://web.myapp.localhost
› kobune changed to 9f3c1a2 since the last run
› the daemon is not this build, so run kobune daemon restart
› this repository's Skill is not this build's, so run kobune skill install --force

どの行も、このマシンの状態がそう言っているから出ています。daemon が応答して、返ってきたバージョンがこのビルドのものではなかった、 .claude/skills/kobune/SKILL.md がこのバイナリの持つものと違う、入っている plist が古い形で書かれている。推測はしません。Skill を一度も入れていないリポジトリに勧めることはなく、記録が始まる前に書かれた plist を古いと決めつけることもありません。daemon の行が「前のビルド」ではなく「このビルドではない」と言うのは、新しいバイナリから手で起動した daemon もここに入るからです。どちらでも対処は同じです。

Skill の行について 2 点。対象は いまいるリポジトリ です。リポジトリの一覧を持っているわけではないので、別のチェックアウトに古い写しが残っていても、この行は面倒を見ません。また --force を使うため、手で編集した SKILL.md も古い写しと同様に置き換わります。どちらにせよ差分は git diff に出ます。

表示は ビルドごとに 1 回、--json ではない最初の実行時です。これは kobune update が関与しない更新、つまり install.sh の再実行、パッケージマネージャ、自分でのビルドも同じようにカバーします。状態として持つのは ~/.kobune/build.json にある「最後に動いたコミット」だけで、これを書くのは上の行を表示したあとです。途中で中断された実行は、次にまた見つけ直します。

kobune daemon 自身には通知を付けません。stop は依頼を書いた時点で戻るため、直後に確認すると「いま止めたプロセスがまだ動いている」と報告してしまうからです。記録もしないので、次のコマンドがまとめて表示します。

CLI 自身の発言と同じく stderr へ出し、--json では出しません。エージェントのストリームは 1 つのドキュメントのままです。kobune update --json は同じ内容をデータとして返します。

json

{
  "status": "installed",
  "commit": "9f3c1a2…",
  "next": [
    {
      "command": "kobune daemon restart",
      "reason": "the daemon is still the previous build"
    }
  ]
}

自動チェック

1 日 1 回、コマンドが終わったあとに nightly の中身を GitHub へ問い合わせ、実行中のものと違えば stderr に 1 行だけ表示します。

a newer build is available (9f3c1a2). Run `kobune update`

コマンドの前ではなく後に実行するため、通信が遅くても待っている出力が遅れることはありません。--json のときは完全に省略されるので、エージェントが解析するストリームに混ざることはありません。失敗しても何も言いません。GitHub に到達できなかったチェックには、伝えるべきことがないからです。

止めるときは環境変数を設定します。

console

$ export KOBUNE_NO_UPDATE_CHECK=1

結果は ~/.kobune/update-check.json に 24 時間キャッシュし、その間はキャッシュから同じ 1 行を出し続けます。1 日に 1 度しか出ない警告は、たいてい見落とされるからです。

`kobune --version`

このフラグでも同じチェックをします。自動チェックと違って毎回問い合わせます。 --version は目の前のビルドについての質問であり、最大 1 日古いキャッシュから答えるのでは別の質問に答えることになるからです。バージョンを先に表示してからチェックするので、求めた出力が通信を待つことはありません。

console

$ kobune --version
kobune 0.1.0 (c7282b8)
› a newer build is available (9f3c1a2). Install it with kobune update

公開されているビルドと同じなら何も足しません。どのビルドかはバージョンの行がすでに答えており、訊かれたのはそれだけだからです。--json と KOBUNE_NO_UPDATE_CHECK は自動チェックと同じように省略し、GitHub に到達できなかったときも同様です。

ソースからビルドしたものについては、どちらとも言いません。バイナリはビルド元のコミットを記録していますが、それが無ければ比べる相手がなく、正直に答えようがありません。「最新です」は推測になり、「古いです」は意図して作ったビルドから引き剥がしてしまいます。

console

$ kobune --version
kobune 0.1.0 (9f3c1a2)

コンテナランタイムの選択

Docker

追加の設定は不要です。Kobune は Docker API を直接利用し、docker CLI を呼び出しません。そのため CLI 自体はインストールされていなくても、API に到達できれば動作します。Docker Desktop、OrbStack、colima のいずれでも構いません。

console

$ kobune doctor
│ …
│ ✓  container runtime  docker 29.4.0
│ …

Apple Container

macOS 26 以降と、サービスの起動が必要です。

console

$ container system start

kobune.toml で指定します。

toml

[runtime]
default = "apple"

選ぶ前に把握しておくべき違いが 3 点あります。ランタイムを参照してください。

daemon の起動

console

$ kobune daemon start
╭ kobuned ─────────────────────────────╮
│ running                              │
│                                      │
│ version   0.1.0 (9b2f09b)            │
│ protocol  7                          │
│ runtime   docker 29.4.0, apple 1.2.1 │
│ uptime    0s                         │
│ socket    ~/.kobune/kobuned.sock     │
╰──────────────────────────────────────╯

通常は手動で実行する必要はありません。いずれのコマンドも、daemon が停止していれば自動的に起動します。プロキシ、DNS、アイドル判定を担当するため、常駐プロセスとして動作します。

管理者権限が必要な設定

https://web.myapp.localhost にポート番号なしでアクセスするには、3 つの設定に管理者権限が必要です。設定は初回の 1 度だけです。

console

$ kobune setup
╭ setup ─────────────────────────────────────────────────────────────────╮
│ the URLs need 3 steps, and they need root.                             │
│ each one is shown before it is run, and nothing runs until you say so. │
│                                                                        │
│ 1. let launchd hold 80/443/53 (the daemon itself stays non-root)       │
│ 2. point *.localhost at Kobune's DNS                                   │
│ 3. trust the local CA, so HTTPS stops warning                          │
╰────────────────────────────────────────────────────────────────────────╯

1/3 let launchd hold 80/443/53 (the daemon itself stays non-root)
  generated plist: ~/.kobune/dev.kobune.daemon.plist
  sudo cp ~/.kobune/dev.kobune.daemon.plist /Library/LaunchDaemons/…
  …
run this? [y/N] y
  ✓ done

2/3 point *.localhost at Kobune's DNS
  sudo mkdir -p /etc/resolver && printf 'nameserver 127.0.0.1\n' | sudo tee …
run this? [y/N] n
  – skipped
…

確認なしに実行されるものはありません。 実行するコマンドは必ず質問より先に表示されるため、同意する対象は直前に読んだものそのものです。実行しなかった手順は、最後にまとめて再表示されます。

すべてに同意するなら kobune setup --yes、一度も訊かれずにコマンドを読むだけなら kobune setup --dry-run です。

応答できる端末がないとき、つまりエージェント・パイプ・--json では、コマンドを表示するだけで何も実行しません。 自動で sudo を実行するとパスワード入力待ちで停止し、利用者から見れば黙って権限昇格が行われたことになります。

実行後は次のようにします。

console

$ kobune daemon restart   # launchd のジョブとして戻り、標準ポートを確保します
$ kobune doctor

設定を省略する場合

この設定は必須ではなく、省略するための設定も不要です。80/443 を確保できない場合、プロキシは代わりに 18080/18443 を使用し、URL にポート番号が付きます。

console

$ kobune url web
https://web.feat-1.myapp.localhost:18443

この状態であることは kobune doctor が明示します。

ポートを自分で決める場合は明示的に指定してください。明示したポートはそのまま使われ、フォールバックしません。

console

$ export KOBUNE_HTTP_PORT=8080 KOBUNE_HTTPS_PORT=8443 KOBUNE_DNS_PORT=15353
$ kobune daemon start

DNS にフォールバックはありません。 /etc/resolver にポート番号を書く必要があり、その書き込みにはいずれにせよ root 権限が要るため、DNS だけを動かしても意味がないためです。これは Kobune ではなく macOS 側の仕様です。 kobune doctor が、指定したポートを含んだコマンドをそのまま出力します。

kobune setup を実行済みの場合

プロキシはフォールバックしません。launchd はジョブが起動しているかどうかに関わらず 80 を保持し続けるため、ここでのバインド失敗は「ジョブを起こす必要がある」という意味になります。別のポートで待ち受けてしまうと、その状態が隠れてしまいます。どちらであるかは kobune doctor が示します。

動作確認

console

$ kobune doctor

✓ 以外の行には、必ず対処方法が併記されます。ここに問題が残ったまま先に進まないでください。後から発生する原因の分かりにくい不具合は、多くの場合ここに起因します。

ファイルの配置場所

KOBUNE_HOME（既定値 ~/.kobune）に、daemon のソケット、状態ファイル、ログ、ローカル CA、生成されたトンネル設定が保存されます。

Unix ソケットのパスは約 100 バイトまでという制限があるため、KOBUNE_HOME に深い階層のディレクトリは指定できません。Kobune は起動時にこれを検証し、原因の分かりにくいエラーで失敗する代わりに、その旨を明示します。

アンインストール

console

$ kobune uninstall

見つかったもの、つまりコンテナ・daemon の状態・バイナリ・補完・root が必要な手順を一覧で示し、削除する前に確認します。--dry-run は一覧を出して終了し、 --yes は確認を省略します。端末がない環境では --yes が必須です。

worktree はそのまま残します。 何が残るか分かるように一覧には表示します。削除するなら kobune rm です。

削除対象の詳細と、root が必要な手順の扱いは CLI リファレンスにあります。

インストール ​

何をインストールすることになるか ​

必要なもの ​

インストールスクリプト ​

PATH の設定 ​

手動でビルド済みバイナリを取得する ​

ビルド ​

シェル補完 ​

worktree の間を移動する ​

最新に保つ ​

新しいビルドが残した作業 ​

自動チェック ​

kobune --version ​

コンテナランタイムの選択 ​

Docker ​

Apple Container ​

daemon の起動 ​

管理者権限が必要な設定 ​

設定を省略する場合 ​

動作確認 ​

ファイルの配置場所 ​

アンインストール ​

インストール

何をインストールすることになるか

必要なもの

インストールスクリプト

PATH の設定

手動でビルド済みバイナリを取得する

ビルド

シェル補完

worktree の間を移動する

最新に保つ

新しいビルドが残した作業

自動チェック

`kobune --version`

コンテナランタイムの選択

Docker

Apple Container

daemon の起動

管理者権限が必要な設定

設定を省略する場合

動作確認

ファイルの配置場所

アンインストール