Skip to content

docs(config): update code executor tool documentation #308

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
elluvium wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(config): update code executor tool documentation #308

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
7 changes: 4 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 @@ -735,7 +735,8 @@ Configure secure Python code execution in isolated Kubernetes pods for running u

| Parameter | Type | Default | Description |
| -------------------------------------- | ------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CODE_EXECUTOR_EXECUTION_MODE` | string | `"local"` | Execution mode: `sandbox` (isolated K8s pod, recommended for production), `local` (embedded kernel, less secure) |
| `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. Code runs in an isolated Kubernetes sandbox pod. |
| `CODE_EXECUTOR_KUBECONFIG_PATH` | string | `""` | Path to kubeconfig for Kubernetes authentication (optional, uses in-cluster config if empty). Set if you want 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 |
Expand All @@ -752,14 +753,14 @@ Configure secure Python code execution in isolated Kubernetes pods for running u
| `CODE_EXECUTOR_RUN_AS_USER` | integer | `1001` | Unix user ID for pod security context (non-root execution) |
| `CODE_EXECUTOR_RUN_AS_GROUP` | integer | `1001` | Unix group ID for pod security context |
| `CODE_EXECUTOR_FS_GROUP` | integer | `1001` | Filesystem group ID for pod volume permissions |
| `CODE_EXECUTOR_SECURITY_THRESHOLD` | string | `"LOW"` | Security policy: `SAFE` (permissive), `LOW`, `MEDIUM`, `HIGH` (restrictive) |
| `CODE_EXECUTOR_SECURITY_THRESHOLD` | string | `"LOW"` | Required security policy threshold: `SAFE`, `LOW`, `MEDIUM`, `HIGH` |
| `CODE_EXECUTOR_YAML_POLICY_PATH` | string | `""` | Path to custom YAML security policy file (optional, overrides default policy) |
| `CODE_EXECUTOR_VERBOSE` | boolean | `false` | Enable verbose logging for executor debugging |
| `CODE_EXECUTOR_KEEP_TEMPLATE` | boolean | `true` | Persist pod template after execution for performance optimization |
| `CODE_EXECUTOR_SKIP_ENVIRONMENT_SETUP` | boolean | `false` | Skip environment initialization in sandbox (faster startup but may break dependencies) |

:::warning Security Considerations
**Local Mode:** `CODE_EXECUTOR_EXECUTION_MODE=local` provides less isolation and security. Use `sandbox` mode in production where untrusted code execution is required.
**Sandbox Isolation:** `CODE_EXECUTOR_EXECUTION_MODE=sandbox` runs user-supplied code in a dedicated Kubernetes pod, isolated from the CodeMie API. This is the execution model for running untrusted code safely in production.

**Security Threshold:** The security policy controls what operations are allowed:

Expand Down
39 changes: 22 additions & 17 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,26 +10,31 @@ import TabItem from '@theme/TabItem';

# Code Executor Configuration

The Code Executor runs Python code in isolated Kubernetes pods with enforced resource limits and security policies.
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.

It supports four deployment modes: local execution inside the API pod, sandbox pods in the same cluster with shared namespace, sandbox pods in the same cluster with dedicated namespace, or sandbox pods in a dedicated cluster.
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.

## Choosing a Deployment Mode
## Enabling the Code Executor

| Mode | When to use | Isolation | RBAC required |
The Code Executor is disabled by default. To make it available, set `CODE_EXECUTOR_ENABLED=true` in the CodeMie API environment:

```yaml
extraEnv:
- name: CODE_EXECUTOR_ENABLED
value: "true"
```

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 |
| ------------------------------------- | ------------------------------------- | -------------------------------- | --------------------- |
| **Local** | No Kubernetes, quick prototyping | None — runs inside the API pod | No |
| **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 Modes

### Local Mode

The default mode. Code is executed directly inside the CodeMie API pod via subprocess. No Kubernetes resources needed.

No changes required. The default value of `CODE_EXECUTOR_EXECUTION_MODE` is `local`.
## Deployment Topologies

### Same Cluster as CodeMie API

Expand All @@ -47,7 +52,7 @@ features:
tools:
code_executor:
rbac:
enabled: true # Creates role and assign it to the service account configured for codemie-api
enabled: true
namespace: "" # defaults to the CodeMie release namespace

extraEnv:
Expand Down Expand Up @@ -119,14 +124,14 @@ extraEnv:
value: "/secrets/kubeconfig"
```

## Updating CodeMie API
## Applying CodeMie API Settings

After configuring a sandbox deployment mode (Same Cluster or Dedicated Cluster), add the following environment variables and apply the chart:
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:

```yaml
extraEnv:
- name: CODE_EXECUTOR_EXECUTION_MODE
value: "sandbox"
- name: CODE_EXECUTOR_ENABLED
value: "true"
- name: CODE_EXECUTOR_MAX_POD_POOL_SIZE
value: "5"
- name: CODE_EXECUTOR_DOCKER_IMAGE
Expand Down
Loading