Feature: register openshell sandbox type — OpenShell gateway-backed execution for agents
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 4/5
- 見積もり時間
- 3〜5日
- 初心者へのやさしさ
- 30/100
- issue の種類
- 機能追加
- 明瞭さ
- おおむね明確
- 活発さ
- 活発
- 技術スタック
- docker, python
調査の方向性
Start with _registry.py in praisonai_sandbox to see how _BUILTIN_SANDBOXES loaders are declared, then read DockerSandbox and praisonaiagents/sandbox/config.py to match the factory and lifecycle pattern. The open decision is whether to integrate via the OpenShell CLI or an SDK, so settle that with maintainers first. Done means a new openshell type resolves through the registry, SandboxConfig.openshell exists, and mocked tests pass without OpenShell installed.
索引モデルが issue の本文から書いたものです。
説明
2. Summary
PraisonAI ships multiple optional sandbox backends via praisonai-sandbox and SandboxManager in praisonai-agents. OpenShell (upstream gateway stack) provides compute drivers (including Docker) and managed sandbox lifecycle with a supervisor — a different isolation model than the in-repo DockerSandbox (raw container exec).
Today there is no openshell type in the sandbox registry, no SandboxConfig.openshell() factory, and no documentation for running agents against an OpenShell gateway. Operators evaluating OpenShell alongside PraisonAI must use the OpenShell CLI manually; agents cannot select sandbox_type="openshell" consistently with other backends.
This issue tracks a v1 optional backend mirroring existing optional sandbox backends in this repo: lazy registration, optional PyPI extra, is_available probing, async start / stop / execute, and integration tests (mocked + optional live Linux CI).
3. Severity / type
| Field | Value |
|---|---|
| Type | Feature (new backend) |
| Severity | Medium — unlocks OpenShell deployments; not required for default subprocess/docker users |
| Security | Must not leak gateway TLS keys or host paths in logs; respect OpenShell policy |
| Breaking change | None if additive |
4. Affected components
| Layer | Package | Change |
|---|---|---|
| Sandbox implementation | praisonai-sandbox |
New openshell.py, registry entry |
| Packaging | praisonai-sandbox pyproject.toml |
Optional [openshell] dependency group |
| Agent config | praisonai-agents |
SandboxConfig.openshell(...) |
| Manager | praisonaiagents.sandbox.manager |
No API break; resolves new type via registry |
| Docs | docs.praison.ai | Install gateway, config, agent example |
| Tests | praisonai-sandbox/tests |
Unit mocks; optional integration marker |
Out of scope v1: PraisonAI-Plugins policy/HITL bridge (follow-up issue).
5. Background — why not reuse docker?
| Aspect | DockerSandbox |
OpenShell |
|---|---|---|
| Control plane | Local docker CLI/API |
OpenShell gateway + drivers |
| Lifecycle | Container per execute pattern | Named sandboxes, supervisor readiness |
| Networking | User-managed | Driver grpc_endpoint (e.g. host gateway from containers) |
| Policy / audit | PraisonAI SecurityPolicy only |
OpenShell gateway + sandbox model |
Conflating the two types would confuse operators and break discovery (SandboxRegistry.list_types()).
6. Current behavior (evidence)
Registry builtins (praisonai_sandbox/_registry.py):
docker, subprocess, sandlock, ssh, plus additional optional types (see _registry.py)
No openshell.
Config factories (praisonaiagents/sandbox/config.py): include docker, subprocess, capsule, native, and others — no openshell.
Repository search: no openshell / OpenShell symbols in PraisonAI monorepo at time of spike (2026-10-26).
7. Desired behavior
| Capability | Description |
|---|---|
| Discovery | SandboxRegistry.get("openshell") returns OpenShellSandbox when extra installed |
| Availability | is_available true when OpenShell CLI or SDK reachable and gateway healthy (configurable check) |
| Lifecycle | await sandbox.start() provisions or attaches to named sandbox; stop() cleans up per config |
| Execute | await sandbox.execute(code, language=...) returns SandboxResult with stdout/stderr/exit code |
| Agent usage | SandboxManager(SandboxConfig.openshell(name="agent-1")) works like other registered types |
| Optional install | pip install praisonai-sandbox[openshell] does not pull OpenShell system packages |
8. Proposed API
8.1 SandboxConfig
@classmethod
def openshell(
cls,
name: str,
*,
image: str | None = None,
gateway_url: str | None = None, # default from env OPENSHELL_GATEWAY_URL
) -> "SandboxConfig":
return cls(
sandbox_type="openshell",
metadata={
"name": name,
"image": image,
"gateway_url": gateway_url,
},
)
8.2 Environment variables (documented)
| Variable | Purpose |
|---|---|
OPENSHELL_GATEWAY_URL |
e.g. https://127.0.0.1:17670 for CLI/SDK |
OPENSHELL_GATEWAY_CONFIG |
Path to gateway.toml (operator concern; document for Docker driver) |
OPENSHELL_SANDBOX_NAME |
Optional default sandbox name |
Exact names should align with OpenShell 0.1.x CLI conventions where possible.
8.3 Example (target DX)
from praisonaiagents.sandbox import SandboxManager, SandboxConfig
config = SandboxConfig.openshell(name="research-agent")
async with SandboxManager(config) as mgr:
result = await mgr.execute("print(2 + 2)")
assert result.stdout.strip() == "4"
9. Implementation plan
Phase A — Backend skeleton
- Add
OpenShellSandboxclass implementing the same public surface as other sandbox classes (start,stop,execute, propertiessandbox_type,is_available). - Register lazy loader in
_BUILTIN_SANDBOXES["openshell"]. - Add optional dependencies in
pyproject.toml(choose one primary integration path in PR):- Subprocess CLI (
openshell sandbox create|exec|delete) for 0.1.5 compatibility, or - Official Python client if/when published and stable on PyPI.
- Subprocess CLI (
Phase B — Agents + docs
- Add
SandboxConfig.openshell. - Document gateway install, Docker driver
grpc_endpoint(e.g.https://host.docker.internal:17670on Docker Desktop), and agent example. - Export type in sandbox CLI help if applicable.
Phase C — Tests
- Unit tests with mocked subprocess or HTTP client (no live gateway required for default CI).
- Optional
@pytest.mark.integrationtest job on Linux + Docker Engine (not WSL Desktop-only) when OpenShell sandbox create succeeds.
10. Reference implementation pattern
Follow the same module layout as existing optional backends under praisonai_sandbox/:
| Pattern | Apply to OpenShell |
|---|---|
Lazy import in is_available |
Check CLI on PATH or import optional dep |
asyncio.to_thread for blocking calls |
CLI invocations |
Clear RuntimeError when unavailable |
Missing gateway / failed health |
| Logging without secrets | Never log TLS key material |
Follow _registry.py entry:
def _openshell_loader():
from .openshell import OpenShellSandbox
return OpenShellSandbox
11. Spike notes (operator environment)
Internal spike (2026-10-26) on WSL + Docker Desktop:
| Check | Result |
|---|---|
openshell gateway info |
Healthy 0.1.5 |
Docker hello-world |
OK |
Container → gateway TLS (host.docker.internal:17670) |
OK |
openshell sandbox create |
Error — ControlSupervisorStartFailed |
Upstream reports similar failures on WSL + Docker Desktop (upstream issues #3880, #3842 on the OpenShell repository).
This does not block merging a backend; it defines where live E2E tests must run.
12. Acceptance criteria
-
openshellappears in registry when[openshell]extra installed. -
SandboxConfig.openshell(...)produces config accepted bySandboxManager. -
OpenShellSandbox.executereturnsSandboxResultfor a happy-path mocked test. -
is_availablefalse when OpenShell not installed / gateway unreachable (no hang). - Default CI passes without OpenShell installed (optional extra not in default matrix).
- Documentation page: prerequisites, gateway, Docker driver endpoint, minimal agent snippet.
- CHANGELOG entry under
praisonai-sandbox.
13. Non-goals (v1)
| Item | Reason |
|---|---|
| Bundling OpenShell gateway in PraisonAI | Operator installs OpenShell separately |
Replacing DockerSandbox |
Different use cases |
| PraisonAI-Plugins OpenShell policy adapter | Separate feature |
| Windows/WSL E2E guarantee | Blocked by upstream supervisor on Docker Desktop |
| Auto-fix WSL networking | Document gateway.toml; operator responsibility |
14. Risks and mitigations
| Risk | Mitigation |
|---|---|
| OpenShell CLI breaking changes 0.1.x | Pin tested version in docs; integration tests gated |
| Subprocess parsing fragility | Prefer SDK when available; structured JSON output if CLI adds it |
| TLS to local gateway | Document trust store / cert generation (openshell gateway generate-certs) |
| Long sandbox create times | Timeouts + clear errors in start() |
15. Testing matrix (recommended)
| Job | OpenShell | Docker | Expected |
|---|---|---|---|
| Unit (default) | Mocked | N/A | Always run |
| Integration linux-docker | Installed | Engine | Sandbox create + execute |
| Windows CI | Not required | Optional skip | Unit only |
| WSL dev laptops | Manual | Desktop | Document known supervisor failure |
16. Documentation outline
- What is OpenShell — link to upstream repo.
- Install — gateway service,
openshell doctor check. - Docker driver — sample
gateway.tomlfragment forgrpc_endpoint. - PraisonAI —
pip install praisonai-sandbox[openshell],SandboxConfig.openshell, env vars. - Troubleshooting — gateway unhealthy, TLS, WSL supervisor error (link upstream issues).
17. Related work
| Item | Relationship |
|---|---|
| Existing optional backend modules | Template for lazy-loaded, extra-gated backends |
SandboxConfig.capsule |
Plugin-registered type — OpenShell is builtin in v1 |
| Strategy doc “golden path … sandbox” | Align docs when shipped |
18. Labels (suggested)
enhancement, praisonai-sandbox, praisonai-agents, sandbox, integration
19. Priority justification
| Factor | Notes |
|---|---|
| Customer / partner ask | OpenShell evaluation alongside PraisonAI |
| Effort | Medium — one backend module + config + tests |
| Dependency risk | Optional extra; core unaffected |
| E2E validation | Depends on Linux OpenShell environment |
20. Appendix — registry snippet (after merge)
Expected:
_BUILTIN_SANDBOXES = {
...
# existing loaders unchanged
"openshell": _openshell_loader,
}
21. Appendix — operator gateway.toml (reference)
Docker Desktop / WSL spike used:
[openshell]
version = 2
[openshell.drivers.docker]
grpc_endpoint = "https://host.docker.internal:17670"
Operators on pure Linux may use 172.17.0.1 or bridge IP instead — document both patterns.
22. Appendix — CLI surface (OpenShell 0.1.5)
Commands referenced during spike (subject to upstream change):
| Command | Use |
|---|---|
openshell gateway info |
Health check for is_available |
openshell sandbox create --name X |
Provision |
openshell sandbox get X |
Status |
openshell sandbox delete X |
Cleanup |
Implementers should verify exec / run command naming in 0.1.5+ before binding.
23. Appendix — security checklist
- No gateway private keys in repo or agent logs
- Sandbox names validated (alphanumeric + safe length)
- Timeouts on all subprocess/network calls
- Resource limits mapped where OpenShell API supports them
24. Appendix — duplicate issue search (before filing)
Search PraisonAI issues for: OpenShell, openshell sandbox, openshell gateway.
If an open issue exists, close as duplicate or extend scope instead of filing this body verbatim.
25. Appendix — success metrics (post-release)
| Metric | Target |
|---|---|
Unit test coverage for openshell.py |
≥ same bar as other optional backend mocks |
| Docs page published | Install + one runnable example |
| Integration job | Green on Linux runner with OpenShell |
26. Appendix — follow-up issues (optional)
- PraisonAI-Plugins bridge for OpenShell policy / approval flows.
- CLI
praisonai sandbox --type openshellshorthand. - Doctor command:
praisonai doctor openshellwrapping gateway health.
27. Appendix — manager flow (unchanged)
SandboxManager(config)
→ resolve sandbox_type from config
→ SandboxRegistry.get(type)
→ backend.start() / execute() / stop()
Adding openshell requires no manager rewrite if backend conforms to existing protocol.
28. Closing
OpenShell is an increasingly common gateway-first sandbox stack. PraisonAI already abstracts multiple backends; openshell belongs in that registry as an optional first-class type, with docs and tests that do not depend on fragile WSL Desktop E2E. Spike work confirms gateway connectivity is solvable; supervisor provisioning must be validated on Linux CI.
End of issue body.
Filed from OpenShell integration planning spike (2026-10-26). Draft: issue-drafts/openshell/publish-ISSUE-sandbox-add-openshell-backend.md.
- 主要言語
- Python
- スター
- 9.3k
- フォーク
- 1.5k
- 平均マージ
- 1日 5時間
- マージ済み PR(30日)
- 520
環境構築
このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
MervinPraison/PraisonAI のほかの issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
MervinPraison/PraisonAI#6710 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
claude
難易度 2/5 1〜3時間 初心者へのやさしさ 74/100
MervinPraison/PraisonAI#6707 ·
メンテナーはふだん 1 日以内に返信
-
bug claude
難易度 1/5 1時間未満 初心者へのやさしさ 90/100
MervinPraison/PraisonAI#6671 ·
メンテナーはふだん 1 日以内に返信
-
Compaction budget regression fixture remains below budget with accurate tokenization再び着手できるかも このイシューのプルリクエストはマージされずにクローズされました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 62/100
MervinPraison/PraisonAI#5418 · コメント 3 件 ·
メンテナーはふだん 1 日以内に返信
-
bug claude documentation
難易度 2/5 1〜3時間 初心者へのやさしさ 70/100
MervinPraison/PraisonAI#5341 · コメント 3 件 ·
メンテナーはふだん 1 日以内に返信
MervinPraison/PraisonAI の issue をすべて見る
似ている issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 76/100
メンテナーはふだん 2 日以内に返信
-
[Bug]: LANGSMITH_SAMPLING_RATE ignores fractional values (isdigit check), traces 100% of requestsオープン
難易度 2/5 1〜3時間 初心者へのやさしさ 84/100
メンテナーはふだん 1 日以内に返信
-
platform/backend tests
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
Significant-Gravitas/AutoGPT#17100 ·
メンテナーはふだん 1 日以内に返信
-
bug good first issue
難易度 2/5 1〜3時間 初心者へのやさしさ 64/100
-
難易度 1/5 1時間未満 初心者へのやさしさ 61/100
scverse/infercnvpy#238 ·
メンテナーはふだん 1 日以内に返信