# etienneperot/safe-code-execution architecture

> Architecture diagram of the GitHub repository etienneperot/safe-code-execution, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/etienneperot/safe-code-execution
- Repository: https://github.com/etienneperot/safe-code-execution

## Overview

##### Project type and purpose
- This is an open-source **Open WebUI addon** that provides **sandboxed code execution** capabilities. It ships two plugin flavors:
a. A **code execution function** (a “Run code” button under AI messages)
b. A **code execution tool** (an LLM-callable tool that runs code autonomously)
- It relies on the **safecode** library to interface with a **gVisor** sandbox, ensuring untrusted code runs securely.

##### File structure
- **Top-level directories**
- `.github/` → CI workflows for tests & linting
- `build/` → packaging scripts (`build_openwebui.py`, versioning)
- `docs/` → setup & developer guides
- `open-webui/` → raw plugin definitions for Functions & Tools (what you copy into Open WebUI)
- `res/` → screenshots & GIFs for documentation
- `src/openwebui/` → Python modules defining how the plugin hooks into Open WebUI
- `src/safecode/` → sandbox orchestration: `sandbox.py`, `user_storage.py`, `update_check.py`
- `tests/` → shell tests for the function & tool
- **Key patterns**
– **Plugin layer** (`src/openwebui/…`)
– **Sandbox core** (`src/safecode/…`)
– **Build & CI** for packaging and quality gates

##### README for additional insights
- Confirms two integration points (Function vs Tool)
- Lists external dependencies: Python runtime, gVisor
- Describes installation steps in Open WebUI’s UI

a. Main components
1. **Open WebUI Host** (Frontend + Function/Tool registry)
2. **Run Code Function** plugin module
3. **Run Code Tool** plugin module
4. **SafeCode Library** (sandbox manager, user storage, update checker)
5. **gVisor Sandbox** (container runtime for untrusted code)
6. **GitHub Actions CI** (lint & test)
7. **Build Scripts** (package & version metadata)
b. Relationships & interactions
- User or LLM invokes **Function** or **Tool** in Open WebUI
- Plugin module calls into **SafeCode Library API**
- SafeCode spins up a **gVisor** sandbox, mounts user workspace via **user_storage**, executes code
- Sandbox returns stdout/stderr/results to the plugin → displayed back in Open WebUI
- Periodically, **SafeCode** runs an **update_check** to fetch new versions/configs
- **Build Scripts** package the plugin, CI workflows run tests against both `open-webui/` copies and `src/` modules
c. Architectural patterns & design principles
- **Layered architecture**: UI plugin layer → sandboxing core → external runtime
- **Separation of concerns**: plugin definitions vs sandbox orchestration vs storage & updates
- **Plugin extensibility**: two distinct entry points (Function vs Tool) share the same backend
d. Technologies, frameworks, libraries
- Python 3.x, gVisor, Open WebUI plugin API
- GitHub Actions for CI, shell scripts for end-to-end tests
- Build tooling in Python for packaging

##### Detail
- **all** critical modules: plugin entries, sandbox core, storage & update components
- **external dependencies** explicitly (gVisor, Python runtime, GitHub Actions)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Open WebUI Layer"
        Host["Open WebUI Host (Event Emitter)"]:::plugin
        Function["Run Code Function Plugin"]:::plugin
        Tool["Run Code Tool Plugin"]:::plugin
    end

    subgraph "Raw Plugin Definitions"
        RawFunc["Raw Function Definition"]:::plugin
        RawTool["Raw Tool Definition"]:::plugin
    end

    subgraph "SafeCode Library"
        Sandbox["Sandbox Manager"]:::safecode
        Storage["User Storage Component"]:::safecode
        Update["Update Checker"]:::safecode
    end

    GVisor["gVisor Sandbox (external runtime)"]:::external

    subgraph "CI & Build"
        Build["Build Scripts & Version Metadata"]:::ci
        CI1["CI Workflow: openwebui-test"]:::ci
        CI2["CI Workflow: python-lint"]:::ci
    end

    subgraph "End-to-End Shell Tests"
        TestFunc["E2E Shell Tests (Function)"]:::ci
        TestTool["E2E Shell Tests (Tool)"]:::ci
    end

    Host -->|"invokes"| Function
    Host -->|"invokes"| Tool
    Function -->|"calls SafeCode API"| Sandbox
    Tool -->|"calls SafeCode API"| Sandbox
    Sandbox -->|"spawns sandbox"| GVisor
    GVisor -->|"returns results"| Sandbox
    Sandbox -->|"mounts workspace"| Storage
    Update -.->|"periodic update_check"| Sandbox
    Sandbox -->|"returns results"| Host

    CI1 -.->|"runs against"| Build
    CI2 -.->|"runs against"| Build
    Build -.->|"packages"| RawFunc
    Build -.->|"packages"| RawTool
    Build -.->|"packages"| Function
    Build -.->|"packages"| Tool
    TestFunc -.->|"tests"| Function
    TestTool -.->|"tests"| Tool

    click Host "https://github.com/etienneperot/safe-code-execution/blob/master/src/openwebui/event_emitter.py"
    click Function "https://github.com/etienneperot/safe-code-execution/blob/master/src/openwebui/functions/run_code.py"
    click Tool "https://github.com/etienneperot/safe-code-execution/blob/master/src/openwebui/tools/run_code.py"
    click RawFunc "https://github.com/etienneperot/safe-code-execution/blob/master/open-webui/functions/run_code.py"
    click RawTool "https://github.com/etienneperot/safe-code-execution/blob/master/open-webui/tools/run_code.py"
    click Sandbox "https://github.com/etienneperot/safe-code-execution/blob/master/src/safecode/sandbox.py"
    click Storage "https://github.com/etienneperot/safe-code-execution/blob/master/src/safecode/user_storage.py"
    click Update "https://github.com/etienneperot/safe-code-execution/blob/master/src/safecode/update_check.py"
    click Build "https://github.com/etienneperot/safe-code-execution/blob/master/build/build_openwebui.py"
    click Build "https://github.com/etienneperot/safe-code-execution/blob/master/build/version.txt"
    click CI1 "https://github.com/etienneperot/safe-code-execution/blob/master/.github/workflows/openwebui-test.yml"
    click CI2 "https://github.com/etienneperot/safe-code-execution/blob/master/.github/workflows/python-lint.yml"
    click TestFunc "https://github.com/etienneperot/safe-code-execution/blob/master/tests/openwebui/functions/run_code_test.sh"
    click TestTool "https://github.com/etienneperot/safe-code-execution/blob/master/tests/openwebui/tools/run_code_test.sh"

    classDef plugin fill:#ADD8E6,stroke:#000,color:#000
    classDef safecode fill:#90EE90,stroke:#000,color:#000
    classDef external fill:#FFA500,stroke:#000,color:#000
    classDef ci fill:#D3D3D3,stroke:#000,color:#000
```
