{"id":31618116,"url":"https://github.com/sohaibqasem/dockexec","last_synced_at":"2026-05-02T23:39:11.635Z","repository":{"id":314792845,"uuid":"1055603750","full_name":"sohaibqasem/dockexec","owner":"sohaibqasem","description":"dockexec is a lightweight Go service to safely execute LLM-generated Python (and other languages) inside Docker. It supports ephemeral \u0026 pooled containers, utilization-aware schedulers, configurable resource limits, and optional gVisor integration for stronger isolation.","archived":false,"fork":false,"pushed_at":"2025-09-14T21:13:39.000Z","size":1373,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-14T21:21:41.468Z","etag":null,"topics":["docker","generated-code","go","llm","python","sandbox"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sohaibqasem.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-12T14:09:49.000Z","updated_at":"2025-09-14T21:13:42.000Z","dependencies_parsed_at":"2025-09-20T12:45:28.775Z","dependency_job_id":null,"html_url":"https://github.com/sohaibqasem/dockexec","commit_stats":null,"previous_names":["sohaibqasem/dockexec"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/sohaibqasem/dockexec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sohaibqasem%2Fdockexec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sohaibqasem%2Fdockexec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sohaibqasem%2Fdockexec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sohaibqasem%2Fdockexec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sohaibqasem","download_url":"https://codeload.github.com/sohaibqasem/dockexec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sohaibqasem%2Fdockexec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278621843,"owners_count":26017253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","generated-code","go","llm","python","sandbox"],"created_at":"2025-10-06T13:45:52.679Z","updated_at":"2025-10-06T13:46:01.266Z","avatar_url":"https://github.com/sohaibqasem.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dockexec\n\n![Go](https://img.shields.io/badge/Go-1.22+-blue)\n![Docker](https://img.shields.io/badge/Docker-ready-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n![Version](https://img.shields.io/badge/version-v0.1.0-orange)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/dockexec.png\" alt=\"Dockexec Logo\" width=\"250\"\u003e\n\u003c/p\u003e\n\n**dockexec** is a lightweight Go service to safely run Python (and future languages) inside Docker.\nIt supports ephemeral one-off containers, pooled warm containers, utilization-aware scheduling, and optional gVisor isolation.\n\n---\n\n## Features\n\n- **Ephemeral execution** → runs each job in a fresh container (isolated but slower).\n- **Pooled execution** → reuses warm containers for faster execution.\n- **Scheduling modes** → round-robin (default) or utilization-based.\n- **Resource limits** → configurable memory, CPU, and network.\n- **Log levels** → off, basic, or verbose with container stats.\n- **gVisor support** → syscall-level isolation with `runsc` runtime.\n- **Cross-platform** → works on Linux, macOS, and Windows.\n- **Extensible** → design allows multi-language execution in the future.\n\n---\n\n## Setup\n\n### 1. Install Go dependencies\n```bash\ngo mod tidy\n```\n\n### 2. Build the Docker image\n```bash\ndocker build -t python-executor:latest -f docker/Dockerfile .\n```\n\n### 3. Run the service\nEphemeral mode:\n```bash\nEXECUTOR_MODE=docker PORT=9090 DOCKER_IMAGE=python-executor:latest go run main.go\n```\n\nPool mode (3 containers):\n```bash\nEXECUTOR_MODE=pool POOL_SIZE=3 PORT=9090 DOCKER_IMAGE=python-executor:latest go run main.go\n```\n\n---\n\n## Environment Variables\n\n| Variable         | Default                  | Description                                      |\n|------------------|--------------------------|--------------------------------------------------|\n| `EXECUTOR_MODE`  | `docker`                 | `docker` (ephemeral) or `pool` (container pool). |\n| `DOCKER_IMAGE`   | `python-executor:latest` | Docker image used for execution.                 |\n| `DOCKER_RUNTIME` | *(unset)*                | `runc` (default) or `runsc` (gVisor).            |\n| `DOCKER_MEMORY`  | `256m`                   | Memory limit per container (ephemeral).          |\n| `DOCKER_CPUS`    | `0.5`                    | CPU limit per container (ephemeral).             |\n| `POOL_SIZE`      | `3`                      | Number of containers in pool mode.               |\n| `POOL_MEMORY`    | `256m`                   | Memory limit per pooled container.               |\n| `POOL_CPUS`      | `0.5`                    | CPU limit per pooled container.                  |\n| `SCHEDULER_MODE` | `roundrobin`             | `roundrobin` (default) or `utilization`.         |\n| `DEBUG`          | *(unset)*                | Log level: `true` (basic) or `verbose` (detailed). |\n| `PORT`           | `8080`                   | API port.                                        |\n\n---\n\n## API\n\n**POST** `/run`\n\n### Request\n```json\n{ \"code\": \"print(2+3)\" }\n```\n\n### Response\n```json\n{\n  \"jobId\": 1756386494986306000,\n  \"stdout\": \"5\\n\",\n  \"stderr\": \"\",\n  \"exitCode\": 0,\n  \"timeMs\": 200\n}\n```\n\n---\n\n## Example\n\n```bash\ncurl -X POST localhost:9090/run \\\\\n  -H \"Content-Type: application/json\" \\\\\n  -d '{\"code\":\"print(10*10)\"}'\n```\n\nResponse:\n```json\n{\n  \"jobId\": 1756386494986306000,\n  \"stdout\": \"100\\n\",\n  \"stderr\": \"\",\n  \"exitCode\": 0,\n  \"timeMs\": 215\n}\n```\n\n---\n\n## Scheduling Modes\n\nWhen using **pooled executor mode**, you can control how jobs are assigned:\n\n- **Round Robin (default)**\n  Cycles evenly through containers.\n  ```bash\n  EXECUTOR_MODE=pool SCHEDULER_MODE=roundrobin go run main.go\n  ```\n\n- **Utilization-Based**\n  Picks the container with the lowest CPU/memory load (via `docker stats`).\n  ```bash\n  EXECUTOR_MODE=pool SCHEDULER_MODE=utilization go run main.go\n  ```\n  Slight overhead (~2s polling interval).\n\n---\n\n## Log Levels\n\nUse the `DEBUG` environment variable to control logging:\n\nBasic:\n```bash\nDEBUG=true PORT=9090 EXECUTOR_MODE=pool go run main.go\n```\nExample log:\n```\n[DEBUG] Job 1757649737223951000 → Goroutine 53 → Container py-pool-a (mem=256m, cpu=0.5)\n```\n\nVerbose:\n```bash\nDEBUG=verbose PORT=9090 EXECUTOR_MODE=pool go run main.go\n```\nExample log:\n```\n[DEBUG] Job 1757649737223951000 → Utilization snapshot:\n  - py-pool-a → CPU=0.00%, Mem=0.00 MiB\n  - py-pool-b → CPU=12.34%, Mem=45.00 MiB\n  - py-pool-c → CPU=0.50%, Mem=10.50 MiB\n[DEBUG] Job 1757649737223951000 → picked py-pool-b (CPU=12.34%, Mem=45.00 MiB)\n```\n\n---\n\n## Using gVisor\n\nThis executor supports running containers under **gVisor** for syscall-level isolation.\n\n1. Follow the official installation instructions:\n   https://gvisor.dev/docs/user_guide/install/\n\n2. Verify:\n```bash\ndocker run --rm --runtime=runsc hello-world\n```\n\n3. Run with gVisor:\n```bash\nEXECUTOR_MODE=docker DOCKER_RUNTIME=runsc go run main.go\n```\n\nNotes:\n- On macOS, requires Colima or another Linux VM.\n- Performance impact:\n  - CPU-heavy jobs → minimal.\n  - Network/DB/syscall-heavy jobs → noticeable slowdown.\n\n---\n\n## Windows Support\n\nThis project works on Windows as well as Linux/macOS.\n\nThe executor uses Go’s `os.TempDir()` automatically, so no manual changes are needed.\n\n- **Environment variables**\n  - **PowerShell**\n    ```powershell\n    $env:EXECUTOR_MODE=\"pool\"\n    $env:POOL_SIZE=\"3\"\n    $env:DOCKER_IMAGE=\"python-executor:latest\"\n    go run main.go\n    ```\n  - **CMD**\n    ```cmd\n    set EXECUTOR_MODE=pool\n    set POOL_SIZE=3\n    set DOCKER_IMAGE=python-executor:latest\n    go run main.go\n    ```\n  - **Git Bash**\n    ```bash\n    export EXECUTOR_MODE=pool\n    export POOL_SIZE=3\n    export DOCKER_IMAGE=python-executor:latest\n    go run main.go\n    ```\n\n---\n\n## What's Next\n\n1. **Session Mode** *(optional)*\n   - Containers mapped 1:1 to users.\n   - Preserves imports/variables across requests.\n\n2. **Multi-Language Support** *(optional)*\n   - Add an `EXECUTOR_CMD` env variable (default: `python`).\n   - Combined with `DOCKER_IMAGE`, this allows execution of Node.js, Ruby, etc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsohaibqasem%2Fdockexec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsohaibqasem%2Fdockexec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsohaibqasem%2Fdockexec/lists"}