Feature: register openshell sandbox type — OpenShell gateway-backed execution for agents
Los mantenedores suelen responder en 1 día
Nadie ha tomado este issue todavía.
Evaluación
- Dificultad
- 4/5
- Tiempo estimado
- 3-5 días
- Aptitud para principiantes
- 30/100
- Tipo de issue
- Nueva funcionalidad
- Claridad
- Bastante claro
- Estado de actividad
- Activo
- Stack tecnológico
- docker, python
- Área
- ai-infra-agents
Línea de trabajo
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.
Escrito por el modelo de indexación a partir del texto del issue.
Descripción
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.
- Lenguaje dominante
- Python
- Estrellas
- 9.3k
- Forks
- 1.5k
- Merge medio
- 1 d 5 h
- PR fusionados (30 d)
- 520
Preparar el entorno
Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Más de MervinPraison/PraisonAI
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 82/100
MervinPraison/PraisonAI#6710 · 1 comentario ·
Los mantenedores suelen responder en 1 día
-
claude
Dificultad 2/5 1-3 horas Aptitud para principiantes 74/100
MervinPraison/PraisonAI#6707 ·
Los mantenedores suelen responder en 1 día
-
bug claude
Dificultad 1/5 Menos de una hora Aptitud para principiantes 90/100
MervinPraison/PraisonAI#6671 ·
Los mantenedores suelen responder en 1 día
-
Compaction budget regression fixture remains below budget with accurate tokenizationQuizá libre de nuevo Un pull request para esta issue se cerró sin fusionarse. Abierto
Dificultad 2/5 1-3 horas Aptitud para principiantes 62/100
MervinPraison/PraisonAI#5418 · 3 comentarios ·
Los mantenedores suelen responder en 1 día
-
bug claude documentation
Dificultad 2/5 1-3 horas Aptitud para principiantes 70/100
MervinPraison/PraisonAI#5341 · 3 comentarios ·
Los mantenedores suelen responder en 1 día
Todos los issues de MervinPraison/PraisonAI
Issues similares
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 76/100
Los mantenedores suelen responder en 2 días
-
[Bug]: LANGSMITH_SAMPLING_RATE ignores fractional values (isdigit check), traces 100% of requestsAbierto
Dificultad 2/5 1-3 horas Aptitud para principiantes 84/100
Los mantenedores suelen responder en 1 día
-
platform/backend tests
Dificultad 2/5 1-3 horas Aptitud para principiantes 78/100
Significant-Gravitas/AutoGPT#17100 ·
Los mantenedores suelen responder en 1 día
-
bug good first issue
Dificultad 2/5 1-3 horas Aptitud para principiantes 64/100
-
scverse link in README is brokenAbierto
Dificultad 1/5 Menos de una hora Aptitud para principiantes 61/100
scverse/infercnvpy#238 ·
Los mantenedores suelen responder en 1 día