OpenHandsを自前運用する前に：Docker sandbox・SDK・microagentsを分ける基準

3行まとめ

Sandbox

Dockerを基本に実行範囲を絞る。

Secrets

model keyとrepo secretを分ける。

GitHub

issue、branch、PR権限を見る。

Microagents

project知識と手順を残す。

OpenHandsは、agentの賢さより先に実行境界を決めます。

• OpenHandsはOSSのAI software development agentとして自前運用しやすい一方、agentがどこでcommandを実行し、どのrepoやsecretへ触れるかを先に決める必要があります。
• 初回はDocker sandboxを基本にし、local process実行やremote runtimeは別レビューにします。runtimeを変えることは、agentが触れる境界を変える判断です。
• microagentsはrepo知識や手順、SDKはapp組み込み用途、GitHub連携はissue/branch/PRの権限として分けて見ます。

本文の事実確認には、OpenHands公式docs、OpenHands GitHub repository、runtime/sandbox docs、microagents docs、SDK docsを使っています。Xで見かけるOpenHands、self-hosted coding agent、sandbox、GitHub issue automationへの投稿は需要シグナルとして扱い、本文の根拠にはしていません。

この記事でわかること

Runtime

Docker、local、remoteを分ける。

Keys

LLM credentialとsecretを管理。

Repo

GitHubで何を書けるか決める。

SDK

app組み込みは別レビューにする。

self-hosted agentは、運用責任が自分たち側へ寄ります。

• OpenHandsを自前運用する時に最初に分ける境界
• Docker sandbox、local process、remote runtimeの見方
• model credentials、GitHub token、app secretを分ける理由
• GitHub連携をissue、branch、PRの権限で見る方法
• microagentsに置くproject知識と、SDK利用の違い
• 初週にどこまで導入すればよいか

OpenHandsは、AI agentにソフトウェア開発作業を任せるためのOSS platformです。便利なのは、UIやagentだけではありません。runtimeを自分で選び、model providerを選び、GitHub連携やSDK組み込みまで含めて、自前運用の選択肢を持てる点です。

ただし、自前運用は自由度と責任が一緒に来ます。この記事では、OpenHands導入前に、runtime、sandbox、credentials、repo権限、microagents、SDKを分けて整理します。

前提知識

項目	内容	見方
OpenHands		software development agent platform。
Runtime		agentがcodeを実行する場所。
Microagents		repo知識や手順をagentへ渡す。
SDK		OpenHandsをappへ組み込む。

OpenHandsは、UIだけでなくruntimeとintegrationを合わせて見ます。

OpenHands公式docsでは、OpenHandsをソフトウェア開発agentとして使い、codebaseの理解、変更、command実行、browserやterminal操作を伴う開発作業を支援するものとして説明しています。GitHub repositoryでも、OpenHandsがcodeを変更し、commandsを実行し、webをbrowseし、APIをcallできるagentであることが示されています。

OpenHandsは、単なるchat UIではありません。agentがruntimeでcommandを実行し、fileを読み書きし、toolを使い、必要に応じてGitHub workflowへ入ります。だからこそ、実行場所と権限を先に決めます。

この記事の扱う範囲

項目	役割
Runtime	agentがcodeやcommandを実行する場所
Docker sandbox	hostから実行環境を隔離する基本候補
Local process	hostに近い実行方式として慎重に扱う
Remote runtime	remote側のcompute、storage、auditを別確認する
Microagents	repo知識、作業手順、domain文脈をagentへ渡す
SDK	OpenHandsを自社appやworkflowへ組み込む

2026年5月31日時点で公開されているOpenHands公式docsとGitHub repositoryを確認しています。導入時には、OpenHands version、runtime設定、model provider、GitHub権限、secret管理、network policyを確認してください。

注意点

この記事は、OpenHandsにproduction secretや本番repoのwrite権限をいきなり渡すための記事ではありません。まずtest repo、Docker sandbox、secretなし、小さなtaskから始める前提です。

まず5つの境界に分ける

項目	内容	見方
Execution		どこでcommandを実行するか。
Network		どこへ接続できるか。
Credentials		model keyやGitHub token。
Repository		clone、branch、PRの範囲。
Knowledge		microagentsで渡す文脈。

境界を分けると、失敗時にどこを閉じるべきか分かります。

OpenHandsを導入する時は、最初に5つの境界を分けます。

境界	確認すること
Execution	commandをどこで実行するか
Network	どこへ接続できるか
Credentials	model key、GitHub token、app secret
Repository	clone、branch、PR、reviewの範囲
Knowledge	microagentsで渡すrepo知識

この5つを分けずに「OpenHandsを入れる」とだけ考えると、後からsecurity reviewが難しくなります。たとえば、Docker sandboxでread-only調査をするのと、local processでwrite tokenを持って本番repoを触るのは、同じ導入ではありません。

便利さより境界を先に見る

AI agentは、できることが多いほど便利です。しかし、できることが多いほど、失敗時の影響も大きくなります。最初は、agentが実行できるcommand、読めるfile、書けるbranch、使えるtoken、接続できるnetworkを小さくします。

変更しやすい形で始める

runtimeやcredentialを後から差し替えられるように、設定をfile化し、READMEやAGENTS.mdへ運用ルールを残します。個人のlocal設定だけで運用を始めると、team標準へ移す時に詰まります。

Docker sandboxを初期選択にする

Isolate

hostとagent実行を分ける。

Reproduce

同じimageで再現しやすい。

Limit

mountやnetworkを絞る。

Review

権限変更をPRで確認。

初回はhost processではなく、隔離されたruntimeから始めます。

OpenHandsを初めてチームで使うなら、Docker sandboxを基本にします。Docker sandboxは、hostとagent実行環境を分けられるため、local machineのfileやprocessへ無制限に近づく運用より説明しやすくなります。

Dockerは万能ではありません。mount、network、privileged mode、volume、environment variableの渡し方によって、実際の境界は変わります。それでも、初回導入では、host processで直接動かすよりレビューしやすい出発点になります。

Docker sandboxで見るもの

観点	確認すること
image	どのbase imageを使うか
mount	repoやcacheをどこまでmountするか
network	internet accessや社内networkをどう扱うか
env	model keyやtokenをどう渡すか
logs	command、tool call、errorをどう残すか

sandboxを過信しない

sandboxがあるから安全、とは言えません。agentへ渡すrepoやsecret、network接続、host volumeが広ければ、riskは残ります。Dockerを使う目的は、境界をなくすことではなく、境界を説明できるようにすることです。

判断基準

「このagentが暴走した時に、どこまで触れるか」を説明できる設定にします。説明できないmountやsecretは初回から渡しません。

local processとremote runtimeを別扱いにする

項目	内容	見方
Docker		初期導入の基本候補。
Local		host権限に近づくため慎重に。
Remote		network、storage、auditを見る。
CI		再現性とlog保持を重視。

runtimeを変えることは、agentが触れる境界を変える判断です。

OpenHandsでは、runtimeの選択が導入判断の中心です。Docker sandbox、local process、remote runtime、CI連携では、便利さとriskが変わります。

runtime	向く場面	注意点
Docker sandbox	初回導入、test repo、小task	mountとnetworkの確認が必要
local process	local toolchainをそのまま使いたい時	host権限に近づく
remote runtime	team共有やscalable運用	storage、network、auditを見る
CI	再現性のある検証	実装agentと保証testを分ける

local processは便利ですが、agentがhostに近い場所で動きます。remote runtimeは共有運用しやすい一方、credential、storage、log retention、network policy、costを確認する必要があります。

runtimeを変える時のreview

runtime変更は、単なる設定変更ではありません。agentが触れるfile、process、network、secret、logの境界が変わります。PRで変更し、security reviewの対象にします。

model credentialsとsecretsを分ける

項目	内容	見方
LLM key		model providerへ接続する。
GitHub token		repo操作の権限を持つ。
App secret		testやintegration用。
Runtime env		sandbox内だけに渡す。

keyをまとめて渡さず、用途ごとにscopeを切ります。

OpenHandsを動かすには、model providerへのcredentialが必要になります。GitHub連携や外部toolを使うなら、GitHub tokenやapp secretも必要になる場合があります。これらをまとめて扱わないことが大事です。

credentialの分類

種類	役割	初期方針
LLM key	model providerへ接続	projectごとにscopeを分ける
GitHub token	repo操作	least privilegeで始める
App secret	testやintegration	初回は渡さない
Runtime env	sandbox内で使うenv	必要なtaskだけに限定

secretなしで価値を見る

初回は、secretなしで価値が出るtaskを選びます。docs修正、type error調査、test failureの原因分析、small refactorの提案などです。secretが必要なtaskは、運用が固まってから扱います。

logに出る前提で見る

agentはcommandを実行し、tool resultを持ちます。secretがstdoutやerror logに出ないように、command、env、masking、log保存先を確認します。

GitHub連携はissueとPRの権限で見る

項目	内容	見方
Issue		起点と指示を受け取る。
Branch		作業branchを作る。
Pull request		diffと説明を出す。
Review		merge前に人間が確認。

OpenHandsのGitHub連携は、repoへ何を書けるかで判断します。

OpenHandsをGitHubとつなぐ場合、issue、branch、PRのどこまで任せるかを分けます。GitHub連携は便利ですが、repoへ書ける権限を持つ場合、導入前の説明が必要です。

GitHub連携で見るもの

項目	確認すること
Issue	agentがtask起点として読む範囲
Branch	agentがbranchを作るか
Commit	commit authorやmessageの扱い
Pull request	PR本文、labels、reviewer設定
Review	merge前に人間reviewを必須にする

GitHub issueからagentを起動する運用では、issue本文がagentへのpromptになります。受け入れ条件、禁止操作、test command、変更範囲を書けるようにissue templateを整えます。GitHub Issue Formの設計は、AIエージェント向けGitHub Issue Formの作り方でも整理しています。

PRは候補として扱う

agentがPRを作っても、mergeは人間reviewとCIの後にします。PR本文には、summary、tests、not run、risksを残します。この形式は、AIエージェントPRテンプレートの作り方と合わせると運用しやすくなります。

microagentsはproject知識と手順に使う

Repo map

directory責務を伝える。

Commands

testやlint手順。

Policy

禁止操作やPR形式。

Domain

用語や業務知識。

microagentsは、毎回promptへ貼る文脈をfile化する入口です。

OpenHands docsでは、microagentsを使ってagentへ追加の指示や知識を渡せる仕組みが説明されています。repo固有の文脈、作業手順、domain知識を毎回promptへ貼るのではなく、fileとして管理できます。

microagentsに向いているのは、毎回必要になるproject知識です。

microagentsに置くもの

種類	例
repo map	directory構成、package責務
commands	lint、test、typecheck、build
policy	禁止操作、secret、外部送信
workflow	PR本文、release、migration
domain	用語、業務ルール、例外条件

AGENTS.mdとの関係

複数agentを使うteamでは、repo共通の基準をAGENTS.mdへ置き、OpenHands固有の補足をmicroagentsへ置くと管理しやすくなります。AGENTS.mdの設計は、チーム向けAGENTS.mdテンプレートでも扱っています。

SDKは組み込み用途として別レビューにする

項目	内容	見方
Use case		chat UIかautomationかを分ける。
Runtime		どこでagentを動かすか。
Auth		userとagent権限を分ける。
Audit		sessionとtool callを記録。

SDK利用は、developer tool導入より広いproduct設計になります。

OpenHands SDKを使うと、OpenHandsを自社appやworkflowへ組み込む方向へ進められます。これは、developer toolとして使う話より広い設計になります。

SDK利用では、誰の権限でagentが動くのか、runtimeはどこか、sessionをどう保存するか、tool callをどうauditするか、user dataをどう扱うかを決めます。

SDK利用で見るもの

観点	確認すること
use case	chat UI、issue automation、internal tool
auth	user権限とagent権限の分離
runtime	Docker、remote、managed環境
audit	session、tool call、diff、command log
data	prompt、repo content、customer data

SDKは、OpenHandsをproductの一部にする入口です。まずはdeveloper toolとして境界を固め、組み込み用途は別のdesign reviewにします。

最小構成の始め方

項目	内容	見方
Docker		隔離runtimeで始める。
Test repo		本番repoの前に試す。
Read-first		最初は調査と小修正に限定。
No secrets		secretなしで価値を見る。

初回は大きな実装ではなく、境界が説明できる運用を作ります。

最初は、小さく始めます。Docker sandbox、test repo、secretなし、read-first task、human review必須です。

最初の構成

AGENTS.md
.openhands/
  microagents/
    repo-guide.md

AGENTS.md には、repo全体の禁止操作、test command、PR本文の形式を書きます。microagentsには、OpenHands向けのrepo mapやよく使うcommandを置きます。

最初のtask例

• docsの古いリンクを直す
• failing testの原因を調査する
• type errorを1つのpackage内で直す
• small refactor案を3つ出す
• test追加の候補を出す

初回から、production API、database、deploy、secretを使うtaskは避けます。

導入初週の進め方

1. 1日目

   Docker sandboxで起動確認。

2. 2日目

   test repoで小taskを試す。

3. 3日目

   microagentsを1つ作る。

4. 5日目

   GitHub PR作成を確認。

5. 7日目

   SDKとremote runtime候補をreview。

初週はself-hosted運用の責任境界を固めます。

初週は、OpenHandsがどれだけ大きな実装をできるかではなく、境界を説明できるかを確認します。

日	やること	完了条件
1日目	Docker sandboxで起動確認	mount、network、envを説明できる
2日目	test repoで小taskを実行	diffとcommand logをreviewできる
3日目	microagentsを1つ作る	repo mapとtest commandが伝わる
5日目	GitHub PR作成を確認	branch、PR本文、review gateが動く
7日目	remote runtimeとSDK候補をreview	導入する/しない理由が書ける

拡大する条件

• sandbox境界が説明できる
• secretなしでも価値が出ている
• PRにsummary、tests、risksが残る
• microagentsが短く保たれている
• GitHub権限がleast privilegeになっている

この条件を満たしてから、対象repoやtaskの種類を増やします。

FAQ

Docker or local?

初回はDockerを基本にする。

Secrets?

用途ごとにscopeを分ける。

Microagents?

repo知識と手順に使う。

SDK?

組み込み用途は別設計にする。

迷ったら、agentがどこで何を実行できるかを見ます。

Docker sandboxとlocal processはどちらから始めるべきですか

初回はDocker sandboxを基本にします。local processはhost権限に近づくため、必要性とriskを説明できる場合だけ検討します。

secretはいつ渡しますか

secretなしで価値を確認してからです。secretが必要なtaskでは、scope、masking、log、runtime env、削除手順を決めます。

microagentsとAGENTS.mdはどう分けますか

agent横断の基準はAGENTS.md、OpenHands固有の補足やrepo知識はmicroagentsに置きます。どちらも長くしすぎず、実際に使われる内容へ絞ります。

SDKは最初から使うべきですか

最初は使わない方が扱いやすいです。developer toolとしてruntime、secret、GitHub権限を整理した後、app組み込みが必要な場合にSDKを別レビューします。

OSS agentなら社内データを安全に扱えますか

OSSであることと安全であることは別です。self-hostedなら運用責任は自分たちに寄ります。runtime、network、secret、logs、model providerへの送信を確認します。

---

次に読むなら

参照した主な情報源

• OpenHands Documentation

https://docs.all-hands.dev/

• OpenHands GitHub repository

https://github.com/All-Hands-AI/OpenHands

• OpenHands Docs: Usage / Runtimes

https://docs.all-hands.dev/modules/usage/runtimes

• OpenHands Docs: Microagents

https://docs.all-hands.dev/modules/usage/prompting/microagents

• OpenHands SDK

https://docs.all-hands.dev/modules/usage/sdk

次に読むなら

更新履歴

1. 2026年5月31日

   OpenHands公式docsとGitHub repositoryを確認して初版を作成しました。

導入時には公式docsと利用中のOpenHands versionを確認してください。

• 2026年5月31日: OpenHands公式docsとGitHub repositoryを確認し、初版を作成しました。