Feature: register openshell sandbox type — OpenShell gateway-backed execution for agents
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
- Ambito
- ai-infra-agents
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
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.
- 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
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di MervinPraison/PraisonAI
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 82/100
MervinPraison/PraisonAI#6710 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
claude
Difficoltà 2/5 1-3 ore Idoneità per principianti 74/100
MervinPraison/PraisonAI#6707 ·
I maintainer di solito rispondono entro 1 giorno
-
bug claude
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 90/100
MervinPraison/PraisonAI#6671 ·
I maintainer di solito rispondono entro 1 giorno
-
Compaction budget regression fixture remains below budget with accurate tokenizationForse di nuovo libera Una pull request per questa issue è stata chiusa senza essere unita. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 62/100
MervinPraison/PraisonAI#5418 · 3 commenti ·
I maintainer di solito rispondono entro 1 giorno
-
bug claude documentation
Difficoltà 2/5 1-3 ore Idoneità per principianti 70/100
MervinPraison/PraisonAI#5341 · 3 commenti ·
I maintainer di solito rispondono entro 1 giorno
Tutte le issue di MervinPraison/PraisonAI
Issue simili
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
I maintainer di solito rispondono entro 2 giorni
-
[Bug]: LANGSMITH_SAMPLING_RATE ignores fractional values (isdigit check), traces 100% of requestsAperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 84/100
I maintainer di solito rispondono entro 1 giorno
-
platform/backend tests
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
Significant-Gravitas/AutoGPT#17100 ·
I maintainer di solito rispondono entro 1 giorno
-
bug good first issue
Difficoltà 2/5 1-3 ore Idoneità per principianti 64/100
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 61/100
scverse/infercnvpy#238 ·
I maintainer di solito rispondono entro 1 giorno