Skip to content

meta: Containers API + ContainerRuntime Provider #5892

Closed as not planned
Closed as not planned

Description

@varshaprasad96

Summary

OGX implements the OpenAI Responses API but currently lacks support for the shell and code_interpreter tools, which require server-side code execution in sandboxed containers. The OpenAI Containers API and Shell tool are generally available. Users evaluating OGX for production agent workloads expect feature parity with OpenAI's tool execution capabilities.

This meta issue tracks implementing the Containers API (CRUD for sandboxed execution environments), the ContainerRuntime provider protocol (abstracting over Docker/Podman and Kubernetes backends), and the shell tool integration in the Responses provider. Together these enable agents to install packages, run scripts, manipulate files, and perform arbitrary computation in secure, isolated containers.

RFC: https://docs.google.com/document/d/1O-17grbe7QcnVrgWcVhOr577ueLsHUFo78CcO0okdWw

Depends on: #5891 (Skills API) for skill mounting into containers.

All endpoints launch at `/v1alpha`.

Tasks

Containers API

Tasks 1–7 (core API structure) are tracked in sub-issue #5912.

inline::local ContainerRuntime Provider

  • 12. Add `docker` Python SDK as optional dependency
  • 13. Create `LocalContainerRuntimeConfig` — Docker/Podman selection, max_containers, default_image
  • 14. Implement `create_container()` — Docker SDK with network isolation, resource limits, unprivileged user
  • 15. Implement `delete_container()`, `get_container()`, `list_containers()`
  • 16. Implement container file operations — upload, list, get, get_content, delete via Docker SDK
  • 17. Implement `execute_shell()` — `container.exec_run()` with timeout, stdout/stderr capture
  • 18. Implement `mount_skills()` — extract skill bundles into `/mnt/skills/{skill_name}/`
  • 19. Implement `last_active_at` update on each container use
  • 20. Implement container expiration background task

Responses API Integration — Shell Tool

  • 21. Add `OpenAIResponseInputToolShell` input tool type with `ShellEnvironment`
  • 22. Add `ShellCall` and `ShellCallOutputItem` output item types
  • 23. Extend `OpenAIResponseInputTool` union with shell
  • 24. Implement shell tool handler — `container_auto`, `container_reference`, `local` modes
  • 25. Implement skill attachment resolution — `skill_reference`, `inline`, `path`
  • 26. Wire `previous_response_id` for multi-turn container reuse

Distribution + CI + Coverage

  • 27. Update starter distribution with optional `container_runtime` provider config
  • 28. Create `ci-tests-containers` distribution config
  • 29. Update `docs/static/openai-coverage.json` — add all 10 Containers endpoints
  • 30. Document Docker-in-Docker or rootless Podman requirement for CI

Tests

  • 31. Write Containers API unit tests — CRUD, file ops, expiration, policy layering
  • 32. Write ContainerRuntime unit tests — mock Docker SDK, lifecycle, execution, skill mounting
  • 33. Write shell tool integration tests — container_auto, container_reference, multi-turn

Future phases (tracked, not in initial scope)

  • 34. `remote::kubernetes` ContainerRuntime provider (Phase 2)
  • 35. `inline::local` sandbox mode with OpenShell (Phase 3)
  • 36. Code interpreter + credential injection (Phase 4)

Containers API Endpoints

Method Path Description
POST /containers Create a container
GET /containers List containers
GET /containers/{container_id} Get container
DELETE /containers/{container_id} Delete container
POST /containers/{container_id}/files Upload file
GET /containers/{container_id}/files List files
GET /containers/{container_id}/files/{file_id} Get file metadata
GET /containers/{container_id}/files/{file_id}/content Download file
DELETE /containers/{container_id}/files/{file_id} Delete file

Dependency Graph

Responses Provider
    ├── ContainerRuntime (for shell_call execution)
    └── Skills (for resolving skill_reference attachments)

Containers Provider (API layer)
    ├── ContainerRuntime (delegates actual container management)
    └── Skills (for mounting skills into containers)

ContainerRuntime Provider
    └── (no OGX API dependencies — talks to Docker/Podman or K8s API)

File structure

src/ogx_api/containers/
  __init__.py
  models.py
  api.py
  fastapi_routes.py

src/ogx/providers/
  registry/containers.py
  registry/container_runtime.py
  inline/containers/builtin/
    __init__.py
    impl.py
  inline/container_runtime/local/
    __init__.py
    config.py
    impl.py

tests/unit/containers/
tests/unit/container_runtime/
tests/integration/containers/

Activity

  1. varshaprasad96 commented on May 19, 2026

    @varshaprasad96
    ContributorAuthor
  2. cdoern commented on May 20, 2026

    @cdoern
    Collaborator

    @franciscojavierarceo @varshaprasad96 can I help out with this one?

  3. varshaprasad96 commented on May 20, 2026

    @varshaprasad96
    ContributorAuthor

    @cdoern sure! We can get started on this and skills API in parallel. Once the ContainerRuntime core (lifecycle, file ops, shell execution) is implemented, we can add skill mounting after #5891 merges

  4. deleted a comment from on May 20, 2026
  5. deleted a comment from on May 20, 2026
  6. cdoern commented on May 21, 2026

    @cdoern
    Collaborator

    sounds good let me break this down into sub tasks and get started on some of the core API structure.

  7. github-actions commented on Jul 21, 2026

    @github-actions
    Contributor

    This issue has been automatically marked as stale because it has not had activity within 60 days. It will be automatically closed if no further activity occurs within 30 days.

  8. github-actions commented on Aug 21, 2026

    @github-actions
    Contributor

    This issue has been automatically closed due to inactivity. Please feel free to reopen if you feel it is still relevant!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions