Feature: register openshell sandbox type — OpenShell gateway-backed execution for agents

オープン
#6,014 コメント 2 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 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 の本文から書いたものです。

説明

bug claude documentation origin/outsider security

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
  1. Add OpenShellSandbox class implementing the same public surface as other sandbox classes (start, stop, execute, properties sandbox_type, is_available).
  2. Register lazy loader in _BUILTIN_SANDBOXES["openshell"].
  3. 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.
Phase B — Agents + docs
  1. Add SandboxConfig.openshell.
  2. Document gateway install, Docker driver grpc_endpoint (e.g. https://host.docker.internal:17670 on Docker Desktop), and agent example.
  3. Export type in sandbox CLI help if applicable.
Phase C — Tests
  1. Unit tests with mocked subprocess or HTTP client (no live gateway required for default CI).
  2. Optional @pytest.mark.integration test 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

  • openshell appears in registry when [openshell] extra installed.
  • SandboxConfig.openshell(...) produces config accepted by SandboxManager.
  • OpenShellSandbox.execute returns SandboxResult for a happy-path mocked test.
  • is_available false 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

  1. What is OpenShell — link to upstream repo.
  2. Install — gateway service, openshell doctor check.
  3. Docker driver — sample gateway.toml fragment for grpc_endpoint.
  4. PraisonAI — pip install praisonai-sandbox[openshell], SandboxConfig.openshell, env vars.
  5. 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)

  1. PraisonAI-Plugins bridge for OpenShell policy / approval flows.
  2. CLI praisonai sandbox --type openshell shorthand.
  3. Doctor command: praisonai doctor openshell wrapping 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 を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

MervinPraison/PraisonAI のほかの issue

MervinPraison/PraisonAI の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。