Skip to content

docs: update code executor configuration with jobs and shared modes #397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pavlochaikivskyi wants to merge 20 commits into
base: main
Choose a base branch
from
Open

docs: update code executor configuration with jobs and shared modes #397

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
790d141
docs: update code executor configuration with jobs and shared modes
pavlochaikivskyi Sep 9, 2026
89c6681
docs: release notes for 2.48.0 (#394)
codemie-ai Sep 9, 2026
44d3e4c
docs(user-guide): document table copy-to-clipboard button (#342)
Shagon1k Sep 9, 2026
4915f56
docs: add release notes for codemie 2.49.0 with configuration changes
pavlochaikivskyi Sep 9, 2026
b934c00
Merge remote-tracking branch 'origin/main' into EPMCDME-14806
pavlochaikivskyi Sep 9, 2026
e12c6fe
docs: update code executor namespace and clarify deprecation notice
pavlochaikivskyi Sep 9, 2026
0fb569a
docs: update code executor configuration details in release notes
pavlochaikivskyi Sep 9, 2026
fd56be0
docs: update docker image version for code executor to 2.48.0
pavlochaikivskyi Sep 10, 2026
94f338f
docs: update code_executor default to 'sandbox-jobs'
pavlochaikivskyi Sep 10, 2026
b4c33c4
docs: update code executor configuration for clarity and completeness
pavlochaikivskyi Sep 10, 2026
fea441f
docs: refine namespace and rbac configuration details for code executor
pavlochaikivskyi Sep 10, 2026
74474ee
docs: update release notes for code executor breaking changes and nam…
pavlochaikivskyi Sep 10, 2026
b89b63b
docs: clarify sandbox modes and update executor image configuration d…
pavlochaikivskyi Sep 10, 2026
1cf0026
docs: format sandbox modes for improved readability in code executor …
pavlochaikivskyi Sep 10, 2026
20f2ff6
docs: update breaking changes for code executor configuration details
pavlochaikivskyi Sep 10, 2026
3193eb9
docs: update link to code executor configuration for namespace details
pavlochaikivskyi Sep 11, 2026
f3e8cce
docs: correct namespace.create default in code executor configuration
pavlochaikivskyi Sep 11, 2026
fea6fa4
docs: call out rbac.namespace key removal in 2.49.0 release notes
pavlochaikivskyi Sep 11, 2026
8c33d80
Merge remote-tracking branch 'origin/main' into EPMCDME-14806
pavlochaikivskyi Sep 14, 2026
dd9afbe
Merge remote-tracking branch 'origin/main' into EPMCDME-14806
pavlochaikivskyi Sep 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/admin/configuration/codemie/api-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1042,12 +1042,12 @@ Configure secure Python code execution in isolated Kubernetes pods for running u
| ----------------------------------------- | ------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `CODE_EXECUTOR_ENABLED` | boolean | `false` | Enable the Code Executor tool. When `false`, the tool is neither listed in the tools catalog nor executed. Set `true` to opt in. |
| `CODE_EXECUTOR_EXECUTION_MODE` | string | `"sandbox"` | Execution mode. Only `sandbox` is accepted; code always runs in an isolated Kubernetes pod. |
| `CODE_EXECUTOR_SANDBOX_MODE` | string | `"sandbox-shared"` | Kubernetes sandbox sub-mode: `sandbox-shared` (reuse a shared pod across sessions — development only) or `sandbox-jobs` (create a dedicated Job pod per execution — recommended for production; requires gVisor or Kata Containers runtime class in the cluster). |
| `CODE_EXECUTOR_SANDBOX_MODE` | string | `"sandbox-jobs"` | Kubernetes sandbox sub-mode: `sandbox-shared` (reuse a shared pod across sessions — development only) or `sandbox-jobs` (create a dedicated Job pod per execution — recommended for production; requires gVisor or Kata Containers runtime class in the cluster). |
| `CODE_EXECUTOR_RUNTIME_CLASS_NAME` | string | `"gvisor"` | Kubernetes `runtimeClassName` applied to Job pods when `CODE_EXECUTOR_SANDBOX_MODE=sandbox-jobs`. Must match an installed runtime class (`gvisor` or `kata-containers`). Set to `none` or leave empty to omit `runtimeClassName` from the Job manifest and fall back to the cluster default runtime. **Security risk:** omitting the runtime class disables sandbox isolation and is not recommended for production; use it only where the cluster default runtime provides equivalent isolation guarantees. |
| `CODE_EXECUTOR_KUBECONFIG_PATH` | string | `""` | Path to kubeconfig for Kubernetes authentication (optional, uses in-cluster config if empty). Set to move code execution to a dedicated cluster |
| `CODE_EXECUTOR_WORKDIR_BASE` | string | `"/home/codemie"` | Base working directory for code execution inside containers |
| `CODE_EXECUTOR_NAMESPACE` | string | `"codemie-runtime"` | Kubernetes namespace for executor pods |
| `CODE_EXECUTOR_DOCKER_IMAGE` | string | `"codemie/codemie-python:2.41.0"` | Docker image with Python environment and dependencies for code execution |
| `CODE_EXECUTOR_NAMESPACE` | string | `"codemie-code-executor"` | Kubernetes namespace for executor pods |
| `CODE_EXECUTOR_DOCKER_IMAGE` | string | `"codemie/codemie-python:2.48.0"` | Docker image with Python environment and dependencies for code execution |
| `CODE_EXECUTOR_EXECUTION_TIMEOUT` | float | `30.0` | Max seconds for code execution before timeout (prevents infinite loops) |
| `CODE_EXECUTOR_SESSION_TIMEOUT` | float | `300.0` | Max session lifetime in seconds before automatic cleanup |
| `CODE_EXECUTOR_DEFAULT_TIMEOUT` | float | `30.0` | Default timeout for operations in seconds |
Expand Down
159 changes: 79 additions & 80 deletions docs/admin/configuration/codemie/code-executor-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,37 @@ import TabItem from '@theme/TabItem';

# Code Executor Configuration

The Code Executor runs Python code in isolated Kubernetes sandbox pods with enforced resource limits and security policies. Every execution request is dispatched to a dedicated sandbox pod, keeping user-supplied code isolated from the CodeMie API.
The Code Executor runs Python code in isolated Kubernetes sandbox pods with enforced resource limits and security policies. Every execution request is dispatched to a sandbox pod, keeping user-supplied code isolated from the CodeMie API.

You choose where those sandbox pods run: in the same cluster as CodeMie API sharing its namespace, in the same cluster in a dedicated namespace, or in a separate dedicated cluster.
There are two sandbox modes selected with `CODE_EXECUTOR_SANDBOX_MODE`:

- **jobs** (`sandbox-jobs`, default and recommended)
- **shared** (`sandbox-shared`, deprecated).

## Sandbox Modes

<Tabs>
<TabItem value="jobs" label="sandbox-jobs (default)" default>

Each execution is submitted as a Kubernetes `Job`. A fresh pod runs the user code and is torn down afterwards.

</TabItem>
<TabItem value="shared" label="sandbox-shared">

CodeMie API discovers and reuses long-lived pods from a pool, or creates a new one on demand up to `CODE_EXECUTOR_MAX_POD_POOL_SIZE`. The same pod can be reused across many executions.

:::warning Will be deprecated
`sandbox-shared` is no longer supported and not recommended to use in production environments. Switch to `sandbox-jobs`.
:::

```yaml
extraEnv:
- name: CODE_EXECUTOR_SANDBOX_MODE
value: "sandbox-shared"
```

</TabItem>
</Tabs>

## Enabling the Code Executor

Expand All @@ -26,84 +54,76 @@ extraEnv:

While disabled, the tool is neither listed in the tools catalog nor executed at runtime.

## Choosing a Deployment Topology

| Topology | When to use | Isolation | RBAC required |
| ------------------------------------- | ------------------------------------- | -------------------------------- | --------------------- |
| **Same cluster, shared namespace** | Standard production setup | Separate pod | Yes |
| **Same cluster, dedicated namespace** | Namespace-level workload isolation | Separate pod, separate namespace | Yes (cross-namespace) |
| **Dedicated cluster** | Compliance, multi-tenant environments | Full cluster isolation | No (kubeconfig) |

## Deployment Topologies
## Setting the Executor Image

### Same Cluster as CodeMie API
Set `CODE_EXECUTOR_DOCKER_IMAGE` to the image matching your CodeMie version:

Executor pods run in the same Kubernetes cluster as CodeMie API.

<Tabs>
<TabItem value="shared" label="Shared namespace" default>
```yaml
extraEnv:
- name: CODE_EXECUTOR_DOCKER_IMAGE
value: "codemie/codemie-python:<codemie-version>"
```

Executor pods are deployed in the same namespace as CodeMie API (e.g. `codemie`).
## RBAC Configuration

**Set in CodeMie API values:**
Enable RBAC so the CodeMie API service account can manage pods/Jobs in the executor namespace:

```yaml
features:
tools:
code_executor:
rbac:
enabled: true
namespace: "" # defaults to the CodeMie release namespace

extraEnv:
- name: CODE_EXECUTOR_NAMESPACE
value: "codemie"
```

</TabItem>
<TabItem value="dedicated" label="Dedicated namespace">
## Namespace Configuration

Executor pods are deployed in a separate namespace (e.g. `codemie-runtime`).
Code executor runs in the `codemie-code-executor` namespace by default, matching the `CODE_EXECUTOR_NAMESPACE` default. Set `namespace.create` to `true` to have the chart manage it:

**Set in CodeMie API values:**
```yaml
features:
tools:
code_executor:
namespace:
create: true
```

To use a different namespace, set the name and `CODE_EXECUTOR_NAMESPACE` to match:

```yaml
features:
tools:
code_executor:
rbac:
enabled: true
namespace: "codemie-runtime"
namespace:
name: "<namespace>"

extraEnv:
- name: CODE_EXECUTOR_NAMESPACE
value: "codemie-runtime"
value: "<namespace>"
```

</TabItem>
</Tabs>
## Applying CodeMie API Settings

:::info
If you cannot manage the existing service account, or need to use a separate one instead of the CodeMie API service account, consider configuring `kubeconfig` credentials as described in the [Dedicated Cluster](#dedicated-cluster) section.
:::
```bash
helm upgrade codemie-api \
oci://europe-west3-docker.pkg.dev/or2-msq-epmd-edp-anthos-t1iylu/helm-charts/codemie \
--version <version> \
-f codemie-api/values-<cloud>.yaml \
--namespace codemie
```

### Dedicated Cluster
## Environment Variables Reference

**1. Create the executor namespace in the dedicated cluster:**
For the full list of available environment variables, see [API Configuration — Code Executor & Python Sandbox](./api-configuration.md#code-executor--python-sandbox).

```bash
kubectl create namespace codemie-runtime
```
## Legacy Topics

**2. Create a kubeconfig secret in the CodeMie API namespace:**
The topics below only apply to niche or deprecated setups. Most deployments can skip this section.

```bash
kubectl create secret generic codemie-executor-kubeconfig \
--from-file=kubeconfig=<path-to-kubeconfig> \
--namespace codemie
```
<details>
<summary>Dedicated Cluster via kubeconfig (will be deprecated)</summary>

**3. Set in CodeMie API values:**
It is also possible to point Code Executor at a namespace in a different cluster by mounting a `kubeconfig` secret instead of relying on in-cluster RBAC:

```yaml
extraVolumeMounts: |
Expand All @@ -119,53 +139,32 @@ extraVolumes: |

extraEnv:
- name: CODE_EXECUTOR_NAMESPACE
value: "codemie-runtime"
value: "codemie-code-executor"
- name: CODE_EXECUTOR_KUBECONFIG_PATH
value: "/secrets/kubeconfig"
```

## Applying CodeMie API Settings
</details>

The Code Executor is disabled by default, so `CODE_EXECUTOR_ENABLED` must be set to `true` to make the tool available. Tune the remaining Code Executor settings as needed and apply the chart:
<details>
<summary>Pre-warming the Pod Pool (sandbox-shared only)</summary>

```yaml
extraEnv:
- name: CODE_EXECUTOR_ENABLED
value: "true"
- name: CODE_EXECUTOR_MAX_POD_POOL_SIZE
value: "5"
- name: CODE_EXECUTOR_DOCKER_IMAGE
value: "codemie/codemie-python:<version>"
```

```bash
helm upgrade codemie-api \
oci://europe-west3-docker.pkg.dev/or2-msq-epmd-edp-anthos-t1iylu/helm-charts/codemie \
--version <version> \
-f codemie-api/values-<cloud>.yaml \
--namespace codemie
```
Pre-warming only applies to the deprecated `sandbox-shared` mode. `sandbox-jobs` always creates a fresh Job pod per execution, so there is no pool to pre-warm.

## Pre-warming the Pod Pool (Optional)

By default, CodeMie API creates executor pods on demand.
The first execution request waits for a pod to start.
To avoid this, deploy the `codemie-runtime` chart to keep pods running and ready:
In `sandbox-shared` mode, CodeMie API creates executor pods on demand by default, and the first execution request waits for a pod to start. To avoid this, deploy the `codemie-code-executor` chart to keep pods running and ready for discovery, into the **same namespace** as `CODE_EXECUTOR_NAMESPACE`:

```bash
helm upgrade --install codemie-runtime \
oci://europe-west3-docker.pkg.dev/or2-msq-epmd-edp-anthos-t1iylu/helm-charts/codemie-runtime \
helm upgrade --install codemie-code-executor \
oci://europe-west3-docker.pkg.dev/or2-msq-epmd-edp-anthos-t1iylu/helm-charts/codemie-code-executor \
--version <version> \
-f codemie-runtime/values.yaml \
-f codemie-code-executor/values.yaml \
--namespace <executor-namespace>
```

To control how many pods are kept ready, set `replicaCount` in your `codemie-runtime/values.yaml`:
To control how many pods are kept ready, set `replicaCount` in your `codemie-code-executor/values.yaml`:

```yaml
replicaCount: 5
```

## Environment Variables Reference

For the full list of available environment variables, see [API Configuration — Code Executor & Python Sandbox](./api-configuration.md#code-executor--python-sandbox).
</details>
36 changes: 36 additions & 0 deletions docs/admin/update/release-notes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,42 @@ This page provides information about updated third-party components and configur

---

### CodeMie 2.51.0 {#v2-51-0}

<details>
<summary>Release details</summary>

**Release Date:** TBD · [GitHub Tag ↗](https://github.com/codemie-ai/codemie/releases/tag/2.51.0)

<h3>Third-Party Component Updates</h3>

No third-party component updates in this release.

<h3>Configuration Changes</h3>

1. **[BREAKING] Code Executor** — changes in `codemie-api`:
- `CODE_EXECUTOR_SANDBOX_MODE` env var now defaults to `sandbox-jobs` — `sandbox-shared` will be deprecated.
- `CODE_EXECUTOR_NAMESPACE` env var default value changed to `codemie-code-executor` (previously `codemie-runtime`).

:::warning
If you already use the Code Executor with a custom namespace, keep `CODE_EXECUTOR_NAMESPACE` and `features.tools.code_executor.namespace.name` set to that namespace and ensure RBAC stays enabled in codemie-api helm chart — otherwise the executor now defaults to the `codemie-code-executor` namespace.

The old `rbac.namespace` key is removed; migrate to `namespace.name`:

```yaml
features:
tools:
code_executor:
namespace:
name: "<namespace>"
```

:::

See [Code Executor Configuration](../configuration/codemie/code-executor-configuration.md#namespace-configuration) for details.

</details>

### CodeMie 2.50.0 {#v2-50-0}

<details>
Expand Down
Loading