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

Aperta
#6,014 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
30/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
docker, python

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
Python
Stelle
9.3k
Fork
1.5k
Merge medio
1g 5h
PR unite (30g)
520

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di MervinPraison/PraisonAI

Tutte le issue di MervinPraison/PraisonAI

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.