1  # execd - OpenSandbox Execution Daemon
  2  
  3  `execd` is the runtime daemon used inside OpenSandbox sandboxes.
  4  
  5  It is built on Gin and exposes HTTP APIs for code execution, shell commands, filesystem operations, PTY sessions, and metrics.
  6  
  7  ## Quick Start
  8  
  9  ### 1) Build
 10  
 11  ```bash
 12  cd components/execd
 13  make build
 14  ```
 15  
 16  ### 2) Start Jupyter Server
 17  
 18  ```bash
 19  ./tests/jupyter.sh
 20  ```
 21  
 22  ### 3) Run execd
 23  
 24  ```bash
 25  ./bin/execd \
 26    --jupyter-host=http://127.0.0.1:54321 \
 27    --jupyter-token=your-jupyter-token \
 28    --port=44772
 29  ```
 30  
 31  ### 4) Verify
 32  
 33  ```bash
 34  curl -v http://localhost:44772/ping
 35  ```
 36  
 37  ## API
 38  
 39  - OpenAPI spec: `../../specs/execd-api.yaml`
 40  - Common capability groups:
 41    - Code execution (`/code`, SSE stream)
 42    - Session and command execution (`/session`, `/command`)
 43    - Filesystem operations (`/files`, `/directories`)
 44    - PTY over WebSocket (`/pty`)
 45    - Local metrics endpoints (`/metrics`, `/metrics/watch`)
 46  
 47  ## Configuration
 48  
 49  ### CLI Flags
 50  
 51  | Flag | Default | Description |
 52  |---|---|---|
 53  | `--jupyter-host` | `""` | Jupyter server URL reachable by execd. |
 54  | `--jupyter-token` | `""` | Jupyter token for HTTP/WebSocket auth. |
 55  | `--port` | `44772` | HTTP listen port. |
 56  | `--log-level` | `6` | Log level (0=Emergency, 7=Debug). |
 57  | `--access-token` | `""` | Optional shared API access token. |
 58  | `--graceful-shutdown-timeout` | `1s` | SSE tail-drain wait window before closing. |
 59  | `--jupyter-idle-poll-interval` | `100ms` | Poll interval after Jupyter reports idle. |
 60  
 61  ### Environment Variables
 62  
 63  | Variable | Description |
 64  |---|---|
 65  | `JUPYTER_HOST` | Same as `--jupyter-host` (overridden by explicit flag). |
 66  | `JUPYTER_TOKEN` | Same as `--jupyter-token` (overridden by explicit flag). |
 67  | `EXECD_API_GRACE_SHUTDOWN` | Same as `--graceful-shutdown-timeout`. |
 68  | `EXECD_JUPYTER_IDLE_POLL_INTERVAL` | Same as `--jupyter-idle-poll-interval`. |
 69  | `EXECD_CLONE3_COMPAT` | Linux clone3 compatibility switch (see below). |
 70  | `EXECD_LOG_FILE` | Optional log output file path; default is stdout. |
 71  | `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Preferred OTLP metrics endpoint. |
 72  | `OTEL_EXPORTER_OTLP_ENDPOINT` | Fallback OTLP endpoint when metrics-specific endpoint is unset. |
 73  | `OPENSANDBOX_ID` | Optional `sandbox_id` metric/resource attribute. |
 74  | `OPENSANDBOX_EXECD_METRICS_EXTRA_ATTRS` | Optional extra metric attrs (`k=v,k2=v2`). |
 75  
 76  ## Observability
 77  
 78  ### OpenTelemetry Metrics
 79  
 80  OTLP metrics export is enabled when either endpoint is set:
 81  
 82  - `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`
 83  - `OTEL_EXPORTER_OTLP_ENDPOINT`
 84  
 85  Detailed metric list and attributes [opentelemetry.md](./docs/opentelemetry.md).
 86  
 87  ### Local Metrics Endpoints
 88  
 89  - `GET /metrics`: point-in-time host metrics snapshot
 90  - `GET /metrics/watch`: SSE stream (1s cadence)
 91  
 92  ## Linux clone3 Compatibility
 93  
 94  Some sandbox environments fail on `clone3(2)`.  
 95  Set `EXECD_CLONE3_COMPAT` in sandbox env to force fallback behavior:
 96  
 97  - `1` / `true` / `yes` / `on`: enable seccomp fallback
 98  - `reexec`: enable fallback and re-exec binary
 99  
100  ## License
101  
102  `execd` is part of OpenSandbox. See `../../LICENSE`.