Skip to content

Integrate NVIDIA OpenShell for sandboxed AI agent execution #357

Open
Open
Integrate NVIDIA OpenShell for sandboxed AI agent execution#357
Labels
blockedenhancementNew feature or requestsecurity
@itdove

Description

@itdove
itdove
opened on Apr 1, 2026

Summary

Add optional NVIDIA OpenShell integration to provide container-based sandboxing for AI agents, enabling defense-in-depth security, credential protection, and policy-driven access control.

Status: 🚫 BLOCKED by upstream - OpenShell currently requires Docker, not compatible with Podman

OpenShell: https://github.com/NVIDIA/OpenShell

Background

Current Security Model

DevAIFlow currently uses ai-guardian (https://github.com/itdove/ai-guardian) for security:

  • IDE-level hooks (UserPromptSubmit, PreToolUse) enforce security policies
  • Secret scanning via Gitleaks prevents credential leakage
  • Directory blocking (.ai-read-deny markers) protects sensitive paths
  • MCP/Skill permissions control which tools AI can access

Limitation: IDE hooks can be bypassed if the AI discovers an IDE vulnerability or exploit.

What OpenShell Provides

OpenShell provides out-of-process policy enforcement at the kernel/container level:

"Rather than relying on internal guardrails, it enforces constraints on the environment the agent runs in—meaning the agent cannot override them, even if compromised."

Key capabilities:

  • Sandboxed execution - Isolated containers with defense-in-depth
  • Credential protection - Environment injection without filesystem exposure
  • Policy-driven access - Declarative YAML for filesystem, network, process, and inference routing
  • Hot-reloadable policies - Update permissions without restarting sessions
  • Multi-agent support - Works with Claude Code, GitHub Copilot, Cursor, Codex, OpenCode

Benefits

1. Stronger Security Model

Security Feature ai-guardian (IDE Hooks) OpenShell (Container Sandbox)
Directory Protection .ai-read-deny markers Filesystem policies (kernel-enforced)
Secret Detection Gitleaks scanning Network policies (block exfiltration)
Tool Permissions MCP allow/deny lists Process policies (syscall restrictions)
Enforcement Point IDE hooks (can be bypassed) Out-of-process (cannot be bypassed)
Defense Strength Application-level Kernel-level

2. Credential Protection

Current risk: API tokens (JIRA_API_TOKEN, GITHUB_TOKEN) are inherited by AI agents via environment variables and could be exfiltrated.

OpenShell solution:

  • Credentials injected as environment variables at runtime
  • Never written to sandbox filesystem
  • Network policies prevent exfiltration to unauthorized endpoints
  • Audit log tracks all credential usage

3. Session Type Enforcement

DevAIFlow has three session types with different security requirements. OpenShell can automatically enforce these constraints:

  • investigation - Read-only, no network
  • ticket_creation - Read-only + JIRA/GitHub API access
  • development - Full access with credential protection

Benefit: Prevent accidental code edits during analysis sessions.

4. Enterprise Compliance

  • Audit logging - All agent actions logged
  • Centralized policies - Enterprise can enforce security policies company-wide
  • Compliance demonstrations - Kernel-level controls for security audits

5. ai-guardian Obsolescence

Once OpenShell integration is complete, ai-guardian would become obsolete:

  • OpenShell provides same protections at a lower (stronger) level
  • Kernel enforcement > IDE hook enforcement
  • Cannot be bypassed by compromised AI agent
  • Simpler user experience (one security layer instead of two)

Migration path: Keep ai-guardian as fallback for users without Docker/Podman, deprecate when OpenShell is production-ready.

Blocker

⚠️ OpenShell Currently Requires Docker

From official documentation:

"Docker — Docker Desktop (or a Docker daemon) must be running."

Podman compatibility status:

  • ❌ Not currently supported
  • 🚧 PR #502 "Podman socket fallback for macOS" (in progress, March 2026)
  • 📋 Status: "Not supported yet"

Impact:

  • Many DevAIFlow users (including maintainer) use Podman for rootless containers
  • Podman users cannot adopt OpenShell until upstream adds support
  • Blocks immediate integration

Upstream PR: NVIDIA/OpenShell#502

Why Podman?

Advantages of Podman over Docker:

  • Daemonless - No central service required (better security)
  • Rootless by default - Containers run as user, not root
  • Enterprise adoption - Default on RHEL, Fedora, SUSE, Oracle Linux
  • Docker compatibility - Near-complete CLI compatibility

Proposed Implementation

Phase 1: Configuration Structure (1-2 weeks)

Goal: Add config support, prepare for integration when Podman blocker is resolved

Tasks:

  • Add SecurityConfig class to devflow/config/models.py
  • Add Security tab to devflow/ui/config_tui.py
  • Create policy template directory structure
  • Add dependency detection (has_openshell(), has_docker(), has_podman())
  • Document configuration options

Configuration design:

User config (~/.daf-sessions/config.json):

{
  "security": {
    "use_openshell": true,
    "openshell_policy_dir": "~/.daf-sessions/policies",
    "openshell_default_policy": "development"
  }
}

Enterprise config (~/.daf-sessions/enterprise.json):

{
  "security": {
    "use_openshell": true,
    "openshell_required": true,
    "openshell_policy_dir": "/etc/devaiflow/policies"
  }
}

Phase 2: OpenShell Wrapper (3-4 weeks, BLOCKED)

Blocked until: OpenShell adds Podman support OR users willing to run Docker

Goal: Implement sandboxed session launching

Tasks:

  • Create devflow/sandbox/openshell_wrapper.py
  • Create policy templates (development, investigation, ticket_creation)
  • Wrap ClaudeAgent.launch_session() with OpenShell
  • Add credential injection for JIRA/GitHub/GitLab tokens
  • Implement policy validation
  • Add audit logging integration

Phase 3: Advanced Features (4-6 weeks, BLOCKED)

Tasks:

  • Multi-repository session isolation (separate sandboxes per repo)
  • GPU support for local model workflows
  • Policy management UI in daf config tui
  • Enterprise policy enforcement via enterprise.json
  • Performance benchmarking and optimization
  • Comprehensive documentation

Alternative Solutions (While Blocked)

Since OpenShell requires Docker and many users have Podman:

Option 1: Continue with ai-guardian (Recommended short-term)

Approach: Keep ai-guardian, enhance it, migrate to OpenShell when Podman support lands

Pros:

  • ✅ No Docker/Podman dependency
  • ✅ Already works with all setups
  • ✅ Proven security model

Cons:

  • ❌ Not as strong as kernel-level isolation
  • ❌ Can be bypassed if AI compromises IDE

Option 2: Podman-Native Sandboxing

Approach: Build lightweight sandbox using Podman directly (no K3s overhead)

Implementation effort: 3-4 weeks

Pros:

  • ✅ Works with Podman (no Docker needed)
  • ✅ Rootless containers by default
  • ✅ Similar security to OpenShell

Cons:

  • ❌ Custom implementation (maintenance burden)
  • ❌ Would need migration to OpenShell later

Option 3: Firejail or Bubblewrap

Approach: Use Linux application sandboxing instead of containers

Pros:

  • ✅ No container runtime needed
  • ✅ Very lightweight

Cons:

  • ❌ Linux-only (no macOS/Windows)
  • ❌ Less mature than OpenShell

Option 4: Wait + Optional Docker

Approach: Make OpenShell optional, require Docker only if enabled

Pros:

  • ✅ Graceful degradation
  • ✅ No forced Docker dependency
  • ✅ Users can opt-in when ready

Cons:

  • ❌ Fragmented user experience

Success Criteria

Phase 1 (Configuration)

  • SecurityConfig added to config models
  • Security tab in daf config tui
  • Policy templates created
  • Dependency detection functions implemented
  • Documentation written

Phase 2 (Integration, when Podman supported)

  • Sandboxed sessions launch successfully
  • Policies enforced (verified via attempted violations)
  • Credentials protected (not in sandbox filesystem)
  • No regressions in core functionality
  • Audit log tracks agent actions

Phase 3 (Production Ready)

  • OpenShell default for investigation sessions
  • Multi-repo sessions use separate sandboxes
  • Enterprise can enforce policies via enterprise.json
  • Performance acceptable (< 500ms overhead)
  • Full documentation with examples
  • ai-guardian marked as deprecated (with migration guide)

Timeline

Optimistic (OpenShell adds Podman support soon)

  • Phase 1: 1-2 weeks (configuration structure)
  • Phase 2: 3-4 weeks (OpenShell wrapper)
  • Phase 3: 4-6 weeks (advanced features)
  • Total: 8-12 weeks

Realistic (Wait for upstream)

  • Phase 1: 1-2 weeks (can start now)
  • Wait period: 3-12 months (upstream Podman support)
  • Phase 2: 3-4 weeks (after blocker resolved)
  • Phase 3: 4-6 weeks (advanced features)
  • Total: 3-13 months

Conservative (Build Podman-native alternative)

  • Phase 1: 1-2 weeks (configuration)
  • Podman-native sandbox: 3-4 weeks
  • Phase 2: 1-2 weeks (migrate to OpenShell when ready)
  • Phase 3: 4-6 weeks (advanced features)
  • Total: 9-14 weeks

Migration from ai-guardian

Deprecation Timeline

When OpenShell is production-ready:

  1. v0.3.0 - OpenShell support added (experimental)
  2. v0.4.0 - OpenShell becomes default for investigation sessions
  3. v0.5.0 - OpenShell default for all session types
  4. v1.0.0 - ai-guardian removed

References

Documentation

Blog Posts

Upstream Issues

Podman Resources

Related

Labels

enhancement, security, blocked, upstream, investigation-complete

Next Steps

  1. Monitor OpenShell PR #502 for Podman support
  2. Start Phase 1 (configuration structure)
  3. Prepare policy templates and documentation
  4. Integrate when Podman blocker is resolved

Investigation Status: ✅ Complete
Recommendation: Proceed with Phase 1 configuration, wait for upstream Podman support
Blocker: NVIDIA/OpenShell#502

Metadata

Metadata

Assignees

No one assigned

    Labels

    blockedenhancementNew feature or requestsecurity

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions