{"id":44572258,"url":"https://github.com/iii-hq/iii","last_synced_at":"2026-04-21T03:02:40.473Z","repository":{"id":279824117,"uuid":"911303109","full_name":"iii-hq/iii","owner":"iii-hq","description":"iii unifies your existing backend stack with a single engine and three primitives: Function, Trigger, and Worker.","archived":false,"fork":false,"pushed_at":"2026-04-20T09:59:02.000Z","size":550974,"stargazers_count":15333,"open_issues_count":94,"forks_count":1024,"subscribers_count":76,"default_branch":"main","last_synced_at":"2026-04-20T10:35:48.216Z","etag":null,"topics":["agents","ai","api","backend","developer-tools","framework","genai","javascript","primitives","python","rust","typescript"],"latest_commit_sha":null,"homepage":"https://iii.dev","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iii-hq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.spdx","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":"NOTICE.md","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-01-02T17:45:02.000Z","updated_at":"2026-04-20T09:33:14.000Z","dependencies_parsed_at":"2025-02-27T23:24:37.387Z","dependency_job_id":"962f5172-fe6d-41ac-ad35-1b7320e0f394","html_url":"https://github.com/iii-hq/iii","commit_stats":null,"previous_names":["motiadev/motia","iii-hq/iii"],"tags_count":254,"template":false,"template_full_name":null,"purl":"pkg:github/iii-hq/iii","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iii-hq%2Fiii","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iii-hq%2Fiii/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iii-hq%2Fiii/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iii-hq%2Fiii/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iii-hq","download_url":"https://codeload.github.com/iii-hq/iii/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iii-hq%2Fiii/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32074812,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T02:38:07.213Z","status":"ssl_error","status_checked_at":"2026-04-21T02:38:06.559Z","response_time":128,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agents","ai","api","backend","developer-tools","framework","genai","javascript","primitives","python","rust","typescript"],"created_at":"2026-02-14T03:23:52.476Z","updated_at":"2026-04-21T03:02:40.456Z","avatar_url":"https://github.com/iii-hq.png","language":"Rust","readme":"# III Engine\n\nIII is a WebSocket-based process communication engine. Workers connect over WS, register\nfunctions and triggers, and the engine routes invocations between workers and core modules.\nCore modules add HTTP APIs, event stream, cron scheduling, and logging.\n\n## Quick Start\n\nPrerequisites:\n\n- Rust 1.80+ (edition 2024)\n- Redis (only if you enable the event/cron/stream modules; the default config expects Redis at\n  `redis://localhost:6379`). Cron uses the built-in KV adapter by default.\n\nInstall (prebuilt binary)\n-------------------------\nThis installer currently supports macOS and Linux (not native Windows).\nYou can install the latest release binary with:\n```bash\ncurl -fsSL https://raw.githubusercontent.com/iii-hq/iii/main/install.sh | sh\n```\n\nTo install a specific version, pass it as the first argument (the leading `v` is optional):\n```bash\ncurl -fsSL https://raw.githubusercontent.com/iii-hq/iii/main/install.sh | sh -s -- v0.2.1\n```\nOr set `VERSION` explicitly:\n```bash\nVERSION=0.2.1 curl -fsSL https://raw.githubusercontent.com/iii-hq/iii/main/install.sh | sh\n```\n\nBy default, the binary is installed to `~/.local/bin`. Override with `BIN_DIR` or `PREFIX`:\n```bash\nBIN_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/iii-hq/iii/main/install.sh | sh\n```\n\nTo check that the binary is on your PATH and see the current version:\n```bash\ncommand -v iii \u0026\u0026 iii --version\n```\n\nDocker\n------\n\nPull the pre-built image:\n```bash\ndocker pull iiidev/iii:latest\n```\n\nRun with a config file:\n```bash\ndocker run -p 3111:3111 -p 49134:49134 \\\n  -v ./config.yaml:/app/config.yaml:ro \\\n  iiidev/iii:latest\n```\n\n**Production (hardened)**:\n```bash\ndocker run --read-only --tmpfs /tmp \\\n  --cap-drop=ALL --cap-add=NET_BIND_SERVICE \\\n  --security-opt=no-new-privileges:true \\\n  -v ./config.yaml:/app/config.yaml:ro \\\n  -p 3111:3111 -p 49134:49134 -p 3112:3112 -p 9464:9464 \\\n  iiidev/iii:latest\n```\n\n**Docker Compose** (full stack with Redis + RabbitMQ):\n```bash\ndocker compose up -d\n```\n\n**Docker Compose with Caddy** (example):\n\nThe included `docker-compose.prod.yml` runs iii behind a [Caddy](https://caddyserver.com/docs/) reverse proxy for TLS:\n\n```bash\n# 1. Replace your-domain.com in Caddyfile with your actual domain\n# 2. Start the stack\ndocker compose -f docker-compose.prod.yml up -d\n```\n\nSee the [Caddy documentation](https://caddyserver.com/docs/) for TLS and reverse proxy configuration.\n\n| Port | Service |\n|------|---------|\n| 49134 | WebSocket (worker connections) |\n| 3111 | REST API |\n| 3112 | Stream API |\n| 9464 | Prometheus metrics |\n\nRun the engine:\n\n```bash\ncargo run\n# or explicitly pass a config\ncargo run -- --config config.yaml\n```\n\nThe engine listens for workers at `ws://127.0.0.1:49134`.\n\nIf you want to run without Redis, create a minimal config that only loads modules you need:\n\n```yaml\nmodules:\n  - class: modules::api::RestApiModule\n    config:\n      host: 127.0.0.1\n      port: 3111\n  - class: modules::observability::OtelModule\n    config:\n      enabled: false\n      level: info\n      format: default\n```\n\nConfig files support environment expansion like `${REDIS_URL:redis://localhost:6379}`.\n\n## Connect a Worker\n\nNode.js:\n\n```javascript\nimport { Bridge } from '@iii-dev/sdk'\n\nconst bridge = new Bridge('ws://127.0.0.1:49134')\n\nbridge.registerFunction({ function_id: 'math.add' }, async (input) =\u003e {\n  return { sum: input.a + input.b }\n})\n```\n\nRust:\n\n```rust\nuse iii_sdk::Bridge;\nuse serde_json::json;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n  let bridge = Bridge::new(\"ws://127.0.0.1:49134\");\n  bridge.connect().await?;\n\n  bridge.register_function(\"math.add\", |input| async move {\n    let a = input.get(\"a\").and_then(|v| v.as_i64()).unwrap_or(0);\n    let b = input.get(\"b\").and_then(|v| v.as_i64()).unwrap_or(0);\n    Ok(json!({ \"sum\": a + b }))\n  });\n\n  Ok(())\n}\n```\n\n## Expose an HTTP Endpoint (API trigger)\n\nThe REST API module maps HTTP routes to functions via the `http` trigger type. Functions should\nreturn `{ \"status_code\": \u003cint\u003e, \"body\": \u003cjson\u003e }`.\n\n```javascript\nbridge.registerFunction({ function_id: 'api.echo' }, async (req) =\u003e {\n  return { status_code: 200, body: { ok: true, input: req.body } }\n})\n\nbridge.registerTrigger({\n  trigger_type: 'http',\n  function_id: 'api.echo',\n  config: { api_path: 'echo', http_method: 'POST' },\n})\n```\n\nWith the default API config, the endpoint will be available at:\n`http://127.0.0.1:3111/echo`.\n\n## Modules\n\nAvailable core modules (registered in `src/modules/config.rs`):\n\n- `modules::api::RestApiModule` – HTTP API trigger (`http`) on `host:port` (default `127.0.0.1:3111`).\n- `modules::queue::QueueModule` – Redis-backed queue system (`queue` trigger, `emit` function).\n- `modules::cron::CronModule` – Cron-based scheduling (`cron` trigger, built-in KV adapter by default).\n- `modules::stream::StreamModule` – Stream WebSocket API (default `127.0.0.1:3112`) and\n  `stream.set/get/delete/list` functions (Redis-backed by default).\n- `modules::observability::OtelModule` – Observability: `log.info/warn/error/debug`, traces, metrics, and alerts.\n- `modules::shell::ExecModule` – File watcher that runs commands (only when configured).\n\nIf `config.yaml` is missing, the engine loads the default module list:\nRestApi, Queue, Logging, Cron, Stream. Queue/Stream expect Redis; Cron uses built-in KV by default.\n\n## Protocol Summary\n\nThe engine speaks JSON messages over WebSocket. Key message types:\n`registerfunction`, `invokefunction`, `invocationresult`, `registertrigger_type`,\n`registertrigger`, `unregistertrigger`, `triggerregistrationresult`, `registerservice`,\n`functionsavailable`, `ping`, `pong`.\n\nInvocations can be fire-and-forget by omitting `invocation_id`.\n\n## Repository Layout\n\n- `src/main.rs` – CLI entrypoint (`iii` binary).\n- `src/engine/` – Worker management, routing, and invocation lifecycle.\n- `src/protocol.rs` – WebSocket message schema.\n- `src/modules/` – Core modules (API, event, cron, stream, logging, shell).\n- `config.yaml` – Example module configuration.\n- `examples/custom_queue_adapter.rs` – Example of a custom module + adapter.\n\n## Development\n\n- Format/lint: `cargo fmt \u0026\u0026 cargo clippy -- -D warnings`\n- Watch run: `make watch` (or `make watch-debug` for verbose logs)\n\n### Building Docker Images Locally\n\n```bash\n# Production image (distroless runtime)\ndocker build -t iii:local .\n\n# Debug image (Debian with shell, htop, vim)\ndocker build -f Dockerfile.debug -t iii:debug .\n\n# Run locally built image\ndocker run --rm iii:local --version\n```\n\n### Security\n\nThe Docker images include:\n- Distroless runtime (no shell, minimal attack surface)\n- Non-root user execution\n- Trivy vulnerability scanning in CI\n- SBOM (Software Bill of Materials) attestation\n- Build provenance\n\nFor production deployments, always use the hardened runtime flags documented above.\n","funding_links":[],"categories":["Rust","TypeScript","Agent Integration \u0026 Deployment Tools"],"sub_categories":["Stateful Serverless Frameworks"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiii-hq%2Fiii","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiii-hq%2Fiii","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiii-hq%2Fiii/lists"}