メインコンテンツへスキップ

arc attach

arc attach は、ローカルディレクトリをリモートの arc デーモンへ provider として逆マウントし、shell アクセス権のないマシンからでも AFS 経由でローカルファイルを読めるようにします。

arc attach は、ローカルディレクトリをリモートの arc デーモンへ逆マウントし、そのリモートデーモン上の /modules/{namespace} の下に provider として公開します。これは arc afs mount とは逆方向です：リモートの何かをローカルの AFS にマウントするのではなく、ローカルの何かをリモートの AFS から見えるようにします。

使用法

bash
arc attach --to <url> [options]

厳密に必須なのは --to だけです。それ以外に何が必要かは、attach する対象が次の 3 種類のうちどれかによって決まります:

  • ディレクトリ attach（デフォルト）：--namespace <name> + --source <dir> —— ローカルディレクトリを、リモートの /modules/{namespace} にマウントされた provider として公開する
  • host attach：--as-host —— このホストの HostFace をリモートの /peers/{peer.json.id} にエクスポートする（--namespace/--source は不要）
  • engine attach：--as-engine <name> 単独 —— そのid の下に裸の code-agents engine を attach する；--as-host と組み合わせた場合は、HostFace と並ぶ表示用メタデータになるだけ

オプション

  • --to <url>（必須）：対象デーモンの URL。例：ws://host:4900 や ws://host:4900/ws/attach
  • --namespace <name>：対象上で公開する namespace。/modules/{namespace} にマウントされる（ディレクトリ attach 用）
  • --source <dir>：provider として公開するローカルディレクトリ（ディレクトリ attach 用）
  • --as-engine <name>：engine id 単独；--as-host と併用する場合は表示用メタデータのみ（リモート id は peer.json の id）
  • --as-host：このホストの HostFace を対象の /peers/{peer.json.id} にエクスポートする
  • --readonly：source を読み取り専用として公開する（ディレクトリ attach 用）
  • --replace：この namespace に既存の session があれば置き換える
  • --token <token>：リモートデーモンの owner アクセストークン（loopback 対象ではスキップされる）
  • --browser：認証フローのためにブラウザを開く（デフォルト true）；無人実行では --token と一緒に --no-browser を渡す
  • --json：デフォルトの人間向けテキストの代わりに、機械可読なイベントを stdout に出力する
  • --view：出力ビューの形式（json は --json と等価）
  • --instance <name> / -i：このコマンドがどのローカル ARC インスタンスに対して動作するか；省略すると default
  • --home <dir>：インスタンスのルート（このホストの peer.json と資格情報が置かれる場所；通常は不要）。どのインスタンスにするかを選ぶには --instance を使う

SIGINT（Ctrl+C）を受けると、arc attach はグレースフルに detach し、リモート側がきれいにアンマウントできるようにします。

例

bash
arc attach --to ws://host:4900 --namespace my-local-src --source ./src --readonly
arc attach --to ws://host:4900 --as-host

--json

--json を付けると、すべての進行状況の行（Attaching...、to:、namespace:、source:、Press Ctrl+C to detach.、Detaching...）は stderr に移り、stdout には改行区切りの JSON イベントだけが残ります —— arc attach ... --json の出力を pipe するスクリプトは、人間向けの文章を除外する必要なく stdout をそのまま JSON として読めます:

bash
$ arc attach --to ws://127.0.0.1:PORT/ws/attach --source /tmp --namespace test --json

stdout（attach が成功した場合、この 1 行だけ）:

json
{"event":"attached","sessionId":"sess_test_...","namespace":"test","targetPath":"/modules/test"}

stderr（進行状況すべて、banner は省略）:

Attaching...
  to:        ws://127.0.0.1:PORT/ws/attach
  namespace: test
  source:    /tmp
Press Ctrl+C to detach.

失敗した場合、--json は対応する JSON オブジェクトを stdout に追加しません —— stdout は空のままで、エラーは依然として stderr 上の人間向けの ERROR: ... 行のままです。これは検証エラー（必須の組み合わせが欠けている）と接続エラーの両方で同じで、どちらも exit 5 です:

bash
$ arc attach --to ws://127.0.0.1:1/ws/attach --source /tmp --json

stdout：（空）

stderr：

ERROR: attach requires --namespace and --source, or --as-engine, or --as-host
bash
$ arc attach --to ws://127.0.0.1:9/ws/attach --namespace test --source /tmp --json

stdout：（空）

stderr：

Attaching...
  to:        ws://127.0.0.1:9/ws/attach
  namespace: test
  source:    /tmp
ERROR: attach failed [cockpit-unreachable]: connect ECONNREFUSED 127.0.0.1:9