Repository navigation
Description
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.
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.
- 1. Add `Api.containers` and `Api.container_runtime` to the Api enum in `src/ogx_api/datatypes.py` (tracked in Containers API: core API structure (src/ogx_api/containers) #5912)
- 2. Create Containers API data models — `Container`, `ContainerFile`, `ExpiresAfter`, `NetworkPolicy`, `NetworkPolicyExtended`, `NetworkDomainCredential`, `NetworkCredential`, `ContainerCreateRequest` (tracked in Containers API: core API structure (src/ogx_api/containers) #5912)
- 3. Create `ShellEnvironment` model — discriminated union of `container_auto`, `container_reference`, `local` (tracked in Containers API: core API structure (src/ogx_api/containers) #5912)
- 4. Create `ShellCallOutput`, `ShellOutcome` execution models (tracked in Containers API: core API structure (src/ogx_api/containers) #5912)
- 5. Create Containers API protocol in `src/ogx_api/containers/api.py` (tracked in Containers API: core API structure (src/ogx_api/containers) #5912)
- 6. Create ContainerRuntime protocol — lifecycle + file management + `execute_shell()` + `mount_skills()` (tracked in Containers API: core API structure (src/ogx_api/containers) #5912)
- 7. Create Containers FastAPI routes — all 10 endpoints (tracked in Containers API: core API structure (src/ogx_api/containers) #5912)
- 8. Implement policy layering enforcement — request cannot expand operator defaults, reject with 403
- 9. Implement `inline::builtin` Containers provider — delegates to ContainerRuntime
- 10. Create Containers and ContainerRuntime provider registries
- 11. Add Containers and ContainerRuntime router and resolver wiring
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
varshaprasad96 commentedon May 19, 2026
cc: @franciscojavierarceo
cdoern commentedon May 20, 2026
@franciscojavierarceo @varshaprasad96 can I help out with this one?
varshaprasad96 commentedon May 20, 2026
@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
cdoern commentedon May 21, 2026
sounds good let me break this down into sub tasks and get started on some of the core API structure.
fix(containers): satisfy provider registry contract for new APIs
feat(containers): add Containers API surface under /v1alpha (ogx-ai#5913
github-actions commentedon Jul 21, 2026
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.
github-actions commentedon Aug 21, 2026
This issue has been automatically closed due to inactivity. Please feel free to reopen if you feel it is still relevant!