> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Containers

> Container management capability — no backend wired yet

Container capabilities are declared in the API but have **no backend** today, so every call raises `NotImplementedError`.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Container Capability"
        A[📦 container_create] --> B[🚫 No Backend]
        B --> C[⚠️ NotImplementedError]
    end

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef warn fill:#F59E0B,stroke:#7C90A0,color:#fff

    class A input
    class B process
    class C warn
```

> [!WARNING]
>
> No provider is wired to container management. `container_create`, `container_file_read`, `container_file_write`, `container_file_list`, and their async `a`-prefixed variants all raise `NotImplementedError`. Do not build on these until a backend lands.
>
> These names are not part of `praisonai.capabilities.__all__`, so `from praisonai.capabilities import *` and `dir()`-style discovery will not surface them. Explicit imports still work (and still raise `NotImplementedError`). The `praisonai containers` CLI and MCP adapters are unchanged.

## Quick Start

**1. What happens when you call it**

Every container function raises immediately — no container is created.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Explicit import — container_create is intentionally hidden from __all__ until a backend lands
from praisonai.capabilities import container_create

try:
    result = container_create("python:3.11")
except NotImplementedError as e:
    print(e)
    # container_create has no backend implementation yet. Container
    # management is not wired to a provider, so no container is actually
    # created. Track/implement this before relying on it.
```

**2. Run code in a container instead**

To actually run code in an isolated container today, use Docker with an agent.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Docker Runner",
    instructions="Run tasks inside a Docker sandbox"
)

agent.start("Summarise the latest AI research")
```

See [Run on Docker](https://praison.ai/docs/features/run-on-docker.md) for the supported path.

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Capability as container_create
    participant Backend

    User->>Capability: container_create("python:3.11")
    Capability--xBackend: no provider wired
    Capability-->>User: raise NotImplementedError
```

| Function | Behaviour today |
| - | - |
| `container_create` / `acontainer_create` | Raises `NotImplementedError` |
| `container_file_read` / `acontainer_file_read` | Raises `NotImplementedError` |
| `container_file_write` / `acontainer_file_write` | Raises `NotImplementedError` |
| `container_file_list` / `acontainer_file_list` | Raises `NotImplementedError` |

The CLI and MCP adapters wrap these calls and surface an honest error: the CLI exits non-zero, and MCP returns an error instead of a fake container ID.

***

## Configuration Options

No options apply while there is no backend. The signature is retained for a future provider.

> [card] [Capabilities SDK Reference](https://praison.ai/docs/sdk/reference/praisonai/modules/capabilities.md)
>
> Auto-generated reference for the capabilities module

***

## Common Patterns

Isolated execution is available through supported paths instead:

* **Docker sandbox** — run agent tasks inside a container with [Run on Docker](https://praison.ai/docs/features/run-on-docker.md).
* **Sandboxed tools** — restrict tool execution with the sandbox configuration.

***

## Best Practices

> [accordion] Do not rely on container\_create yet
>
> There is no backend. Calls raise `NotImplementedError` — treat this capability as unavailable until a provider is wired.

> [accordion] Handle the error explicitly if you probe for it
>
> If your code checks for container support at runtime, catch `NotImplementedError` and fall back to a supported path rather than assuming success.

> [accordion] Use Docker for real isolation
>
> For genuine isolated execution today, use the Docker path with an `Agent`. It is supported and tested.

***

## Related

> [card] [Run on Docker](https://praison.ai/docs/features/run-on-docker.md)
>
> Run agents inside a Docker container today

> [card] [Capabilities Overview](https://praison.ai/docs/capabilities/index.md)
>
> All LiteLLM parity capabilities


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.