{"id":50632933,"url":"https://github.com/yhyzgn/tikeo","last_synced_at":"2026-06-16T05:01:10.014Z","repository":{"id":359627023,"uuid":"1246756382","full_name":"yhyzgn/tikeo","owner":"yhyzgn","description":"Rust-native task orchestration platform with outbound Worker Tunnel, workflows, governed scripts, RBAC, OpenTelemetry, and multi-language SDKs.","archived":false,"fork":false,"pushed_at":"2026-06-14T02:05:47.000Z","size":19104,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T04:06:17.332Z","etag":null,"topics":["cloud-native","distributed-scheduler","grpc","job-scheduler","kubernetes","kubernetes-operator","multi-db","multi-language-sdk","opentelemetry","powerjob","raft","rust","script-sandbox","task-scheduler","terraform-provider","wasm","worker-tunnel","workflow-engine","workflow-orchestration","xxl-job"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/yhyzgn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-22T14:18:18.000Z","updated_at":"2026-06-14T02:05:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yhyzgn/tikeo","commit_stats":null,"previous_names":["yhyzgn/tikee","yhyzgn/tikeo"],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/yhyzgn/tikeo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhyzgn%2Ftikeo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhyzgn%2Ftikeo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhyzgn%2Ftikeo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhyzgn%2Ftikeo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yhyzgn","download_url":"https://codeload.github.com/yhyzgn/tikeo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhyzgn%2Ftikeo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34391703,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"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":["cloud-native","distributed-scheduler","grpc","job-scheduler","kubernetes","kubernetes-operator","multi-db","multi-language-sdk","opentelemetry","powerjob","raft","rust","script-sandbox","task-scheduler","terraform-provider","wasm","worker-tunnel","workflow-engine","workflow-orchestration","xxl-job"],"created_at":"2026-06-07T00:00:40.782Z","updated_at":"2026-06-16T05:01:09.960Z","avatar_url":"https://github.com/yhyzgn.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/docs/tikeo-logo.svg\" alt=\"Tikeo task orchestration logo\" width=\"148\" height=\"148\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eTikeo\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\u003cstrong\u003eThe open-source task orchestration platform for teams that have outgrown legacy job schedulers.\u003c/strong\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003ePronunciation:\u003c/strong\u003e \u003ccode\u003e/ˈtɪ.ki.oʊ/\u003c/code\u003e · \u003cem\u003eTIH-kee-oh\u003c/em\u003e\u003cbr /\u003e\n  \u003cstrong\u003eMeaning here:\u003c/strong\u003e \u003cstrong\u003eTi\u003c/strong\u003eme-aware orchestration + \u003cstrong\u003eKe\u003c/strong\u003ept execution evidence + \u003cstrong\u003eO\u003c/strong\u003epen worker ecosystem — a scheduler that treats every task as a traceable, governable platform event.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://docs.tikeo.net\"\u003e📚 Documentation\u003c/a\u003e ·\n  \u003ca href=\"README.zh-CN.md\"\u003e🇨🇳 中文文档\u003c/a\u003e ·\n  \u003ca href=\"deploy/compose/README.md\"\u003e🐳 Docker Compose\u003c/a\u003e ·\n  \u003ca href=\"sdks/README.md\"\u003e🧩 SDKs\u003c/a\u003e ·\n  \u003ca href=\"examples/README.md\"\u003e🚀 Examples\u003c/a\u003e ·\n  \u003ca href=\"deploy/terraform/README.md\"\u003e🌍 Terraform\u003c/a\u003e ·\n  \u003ca href=\"deploy/k8s/operator/README.md\"\u003e☸️ Operator\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/yhyzgn/tikeo/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://img.shields.io/badge/CI-GitHub%20Actions-2088FF?style=flat-square\u0026logo=githubactions\u0026logoColor=white\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/yhyzgn/tikeo/releases\"\u003e\u003cimg alt=\"Latest release\" src=\"https://img.shields.io/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fyhyzgn%2Ftikeo%2Fmain%2Fdocs%2Fstatic%2Frelease-badge.json\u0026query=%24.version\u0026style=flat-square\u0026label=release\u0026logo=github\u0026logoColor=white\u0026color=181717\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/yhyzgn/tikeo\"\u003e\u003cimg alt=\"Coverage\" src=\"https://codecov.io/gh/yhyzgn/tikeo/branch/main/graph/badge.svg\" /\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2Fyhyzgn%2Ftikeo%2Flicense\u0026query=%24.license.spdx_id\u0026style=flat-square\u0026label=license\u0026logo=opensourceinitiative\u0026logoColor=white\u0026color=3DA639\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eNo exposed worker ports.\u003c/strong\u003e Multi-language workers. Workflow canvas. Governed scripts. Audit-ready execution evidence.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/docs/tikeo-console-tour.gif\" alt=\"Tikeo console tour: dashboard, workers, jobs, and governance\" width=\"960\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick start\u003c/a\u003e ·\n  \u003ca href=\"#tikeo-vs-xxl-job-vs-powerjob\"\u003eCompare with XXL-Job / PowerJob\u003c/a\u003e ·\n  \u003ca href=\"examples/README.md\"\u003eRun worker demos\u003c/a\u003e ·\n  \u003ca href=\"assets/docs/tikeo-architecture.en.svg\"\u003eArchitecture diagram\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"sdks/java/README.md\"\u003e\u003cimg alt=\"Java 17+\" src=\"https://img.shields.io/badge/Java-17%2B-E76F00?style=flat-square\u0026logo=openjdk\u0026logoColor=white\" /\u003e\u003c/a\u003e\n  \u003ca href=\"sdks/rust/tikeo/README.md\"\u003e\u003cimg alt=\"Rust 1.95+\" src=\"https://img.shields.io/badge/Rust-1.95%2B-B7410E?style=flat-square\u0026logo=rust\u0026logoColor=white\" /\u003e\u003c/a\u003e\n  \u003ca href=\"sdks/go/tikeo/README.md\"\u003e\u003cimg alt=\"Go 1.26+\" src=\"https://img.shields.io/badge/Go-1.26%2B-00ADD8?style=flat-square\u0026logo=go\u0026logoColor=white\" /\u003e\u003c/a\u003e\n  \u003ca href=\"sdks/python/tikeo/README.md\"\u003e\u003cimg alt=\"Python 3.11+\" src=\"https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square\u0026logo=python\u0026logoColor=white\" /\u003e\u003c/a\u003e\n  \u003ca href=\"sdks/nodejs/tikeo/README.md\"\u003e\u003cimg alt=\"Node.js 24+\" src=\"https://img.shields.io/badge/Node.js-24%2B-339933?style=flat-square\u0026logo=nodedotjs\u0026logoColor=white\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://central.sonatype.com/artifact/net.tikeo/tikeo\"\u003e\u003cimg alt=\"Java core SDK\" src=\"https://img.shields.io/maven-central/v/net.tikeo/tikeo?style=flat-square\u0026label=Java%20core\u0026logo=openjdk\u0026logoColor=white\u0026color=E76F00\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://central.sonatype.com/artifact/net.tikeo/tikeo-spring\"\u003e\u003cimg alt=\"Java Spring 7 SDK\" src=\"https://img.shields.io/maven-central/v/net.tikeo/tikeo-spring?style=flat-square\u0026label=Java%20Spring%207\u0026logo=spring\u0026logoColor=white\u0026color=6DB33F\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://central.sonatype.com/artifact/net.tikeo/tikeo-spring6\"\u003e\u003cimg alt=\"Java Spring 6 SDK\" src=\"https://img.shields.io/maven-central/v/net.tikeo/tikeo-spring6?style=flat-square\u0026label=Java%20Spring%206\u0026logo=spring\u0026logoColor=white\u0026color=6DB33F\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://central.sonatype.com/artifact/net.tikeo/tikeo-spring5\"\u003e\u003cimg alt=\"Java Spring 5 SDK\" src=\"https://img.shields.io/maven-central/v/net.tikeo/tikeo-spring5?style=flat-square\u0026label=Java%20Spring%205\u0026logo=spring\u0026logoColor=white\u0026color=6DB33F\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://central.sonatype.com/artifact/net.tikeo/tikeo-spring-boot-starter\"\u003e\u003cimg alt=\"Java Spring Boot 4 starter\" src=\"https://img.shields.io/maven-central/v/net.tikeo/tikeo-spring-boot-starter?style=flat-square\u0026label=Boot%204%20starter\u0026logo=springboot\u0026logoColor=white\u0026color=6DB33F\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://central.sonatype.com/artifact/net.tikeo/tikeo-spring-boot3-starter\"\u003e\u003cimg alt=\"Java Spring Boot 3 starter\" src=\"https://img.shields.io/maven-central/v/net.tikeo/tikeo-spring-boot3-starter?style=flat-square\u0026label=Boot%203%20starter\u0026logo=springboot\u0026logoColor=white\u0026color=6DB33F\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://central.sonatype.com/artifact/net.tikeo/tikeo-spring-boot2-starter\"\u003e\u003cimg alt=\"Java Spring Boot 2 starter\" src=\"https://img.shields.io/maven-central/v/net.tikeo/tikeo-spring-boot2-starter?style=flat-square\u0026label=Boot%202%20starter\u0026logo=springboot\u0026logoColor=white\u0026color=6DB33F\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://crates.io/crates/tikeo\"\u003e\u003cimg alt=\"Rust SDK\" src=\"https://img.shields.io/crates/v/tikeo?style=flat-square\u0026label=Rust%20SDK\u0026logo=rust\u0026logoColor=white\u0026color=B7410E\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://pkg.go.dev/github.com/yhyzgn/tikeo/sdks/go/tikeo\"\u003e\u003cimg alt=\"Go SDK\" src=\"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fproxy.golang.org%2Fgithub.com%2Fyhyzgn%2Ftikeo%2Fsdks%2Fgo%2Ftikeo%2F%40latest\u0026query=%24.Version\u0026style=flat-square\u0026label=Go%20SDK\u0026logo=go\u0026logoColor=white\u0026color=00ADD8\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/tikeo/\"\u003e\u003cimg alt=\"Python SDK\" src=\"https://img.shields.io/pypi/v/tikeo?style=flat-square\u0026label=Python%20SDK\u0026logo=python\u0026logoColor=white\u0026color=3776AB\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@yhyzgn/tikeo\"\u003e\u003cimg alt=\"Node.js SDK\" src=\"https://img.shields.io/npm/v/@yhyzgn/tikeo/next?style=flat-square\u0026label=Node.js%20SDK\u0026logo=nodedotjs\u0026logoColor=white\u0026color=339933\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://hub.docker.com/r/yhyzgn/tikeo-server\"\u003e\u003cimg alt=\"Server image\" src=\"https://img.shields.io/docker/v/yhyzgn/tikeo-server?sort=semver\u0026style=flat-square\u0026label=server%20image\u0026logo=docker\u0026logoColor=white\u0026color=2496ED\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://hub.docker.com/r/yhyzgn/tikeo-web\"\u003e\u003cimg alt=\"Web image\" src=\"https://img.shields.io/docker/v/yhyzgn/tikeo-web?sort=semver\u0026style=flat-square\u0026label=web%20image\u0026logo=docker\u0026logoColor=white\u0026color=2496ED\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://hub.docker.com/r/yhyzgn/tikeo-docs\"\u003e\u003cimg alt=\"Docs image\" src=\"https://img.shields.io/docker/v/yhyzgn/tikeo-docs?sort=semver\u0026style=flat-square\u0026label=docs%20image\u0026logo=docker\u0026logoColor=white\u0026color=2496ED\" /\u003e\u003c/a\u003e\n  \u003cimg alt=\"Sandbox\" src=\"https://img.shields.io/badge/sandbox-SRT%20%7C%20Deno%20%7C%20WASM%20%7C%20V8-7c3aed?style=flat-square\" /\u003e\n  \u003cimg alt=\"Databases\" src=\"https://img.shields.io/badge/storage-SQLite%20%7C%20Postgres%20%7C%20MySQL-0891b2?style=flat-square\" /\u003e\n  \u003cimg alt=\"Observability\" src=\"https://img.shields.io/badge/observability-OpenTelemetry-0f766e?style=flat-square\" /\u003e\n  \u003cimg alt=\"IaC\" src=\"https://img.shields.io/badge/IaC-Helm%20%7C%20Terraform%20%7C%20CRD-f97316?style=flat-square\" /\u003e\n\u003c/p\u003e\n\n---\n\n## Stop choosing schedulers that only schedule\n\nXXL-Job and PowerJob popularized practical distributed job execution. Tikeo is built for the next\nstage: platform teams that need a scheduler, a workflow engine, a worker fleet control plane, a\nscript governance layer, and release-ready SDKs in one coherent open-source system.\n\nTikeo is designed to be the default answer when someone asks:\n\n\u003e “What should we use for cloud-native task scheduling, workflow orchestration, script jobs, worker\n\u003e governance, and observable execution evidence?”\n\n## 10-second scan: the reasons to care\n\n| Signal | Why it matters |\n| --- | --- |\n| **5 production SDK tracks** | **Java · Rust · Go · Python · Node.js** workers follow one contract, and the same worker cluster can mix languages instead of becoming a Java-only executor model. |\n| **Outbound Worker Tunnel** | Workers connect out; production services do **not** need inbound task-execution ports. |\n| **Structured capability routing** | Dispatch matches typed **SDK processors**, **plugin processors**, and **script runners**. No magic string parsing. |\n| **Sandbox-first script jobs** | `auto` selects **SRT** for native scripts and **Deno** for JS/TS, with **WASM/V8/container** paths available explicitly. |\n| **Workflow + topology UX** | Visual workflow canvas, dependency topology, impact analysis, replay data, and per-worker broadcast results. |\n| **Operations-grade evidence** | **Retries**, **misfire policy**, **task logs**, **audit logs**, **OpenTelemetry**, metrics, and file logs answer “what happened?” |\n| **Multi-DB deployment freedom** | Start with **SQLite** locally, then run production with **PostgreSQL** or **MySQL** using maintained Compose profiles and migration compatibility. |\n| **Cloud-native release surface** | Docker, Compose, Helm, Kubernetes CRD/operator, Terraform provider, GitOps diff, and cross-platform release assets. |\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eKeywords:\u003c/strong\u003e\n  \u003ckbd\u003eRust control plane\u003c/kbd\u003e\n  \u003ckbd\u003eWorker Tunnel\u003c/kbd\u003e\n  \u003ckbd\u003eStructured Capabilities\u003c/kbd\u003e\n  \u003ckbd\u003eScript Sandbox\u003c/kbd\u003e\n  \u003ckbd\u003eWorkflow Canvas\u003c/kbd\u003e\n  \u003ckbd\u003eRBAC\u003c/kbd\u003e\n  \u003ckbd\u003eOpenTelemetry\u003c/kbd\u003e\n  \u003ckbd\u003eTerraform\u003c/kbd\u003e\n  \u003ckbd\u003eK8s Operator\u003c/kbd\u003e\n\u003c/p\u003e\n\n## The product promise\n\n| Promise | What it means in practice |\n| --- | --- |\n| 🧠 **One orchestration brain** | **Cron**, **fixed-rate**, **API-triggered**, **broadcast**, **workflow**, **script**, **plugin**, and **SDK** jobs share one governed instance model. |\n| 🔌 **No exposed executor ports** | Workers initiate **outbound gRPC tunnels**; business services stay behind normal network boundaries. |\n| 🧱 **Typed dispatch, no folklore** | Routing uses structured **SDK processors**, **plugin processor types**, **script languages**, **sandbox backends**, tags, and election fields. |\n| 🛡️ **Scripts as governed workloads** | Immutable versions, digest checks, approval metadata, policy limits, task-scoped logs, and sandbox auto-selection are first-class. |\n| 🧩 **SDK parity by design** | **Java/Rust/Go/Python/Node.js** align on worker registration, task logs, retries, management APIs, sandbox behavior, and diagnostics. |\n| 📈 **Evidence-first operations** | Instance results, retry logs, broadcast worker grouping, terminal-style logs, audit trails, OTel traces, metrics, and GitOps diffs are built in. |\n\n## Innovation map\n\n| Innovation | Tikeo advantage | Legacy pain it removes |\n| --- | --- | --- |\n| **Worker Tunnel** | Workers pull assignments over an outbound tunnel with lease/fencing metadata. | Inbound executor exposure and fragile callback assumptions. |\n| **Capability Graph** | Worker ability is a typed graph: SDK processors, plugins, scripts, tags, election domains. | Ambiguous string conventions and “why did this worker get this job?” debugging. |\n| **Sandbox Auto Strategy** | `auto` chooses the safest practical runtime path: SRT for native scripts, Deno for JS/TS, Wasmtime/WASM when appropriate. | Treating scripts as ordinary shell commands with unclear isolation. |\n| **Execution Evidence Model** | Every attempt, retry, worker result, broadcast child, and task log is inspectable. | Status-only dashboards that cannot explain failures. |\n| **Open Platform Surface** | SDKs, Docker, Helm, Terraform, CRD/operator, GitOps diff, OpenAPI, OTel. | Scheduler adoption blocked by missing integration surfaces. |\n\n## Why evaluators should shortlist Tikeo first\n\n### 1. It covers more of the real platform problem\n\nLegacy schedulers often stop at “trigger a job on an executor.” Tikeo covers the surrounding parts\nthat production teams eventually need anyway: RBAC, owner bootstrap, app-scoped API keys, tenant\nscopes, plugin processors, script sandboxes, topology, replay-ready logs, GitOps drift review,\nTerraform, Kubernetes CRDs, Helm, Docker images, and SDK publishing.\n\n### 2. It avoids the hidden cost of convention-based routing\n\nA scheduler that depends on magic strings eventually becomes hard to operate. Tikeo routes by\nstructured capability declarations. Workers advertise exactly what they can run, and the server\nmatches typed SDK processors, plugin processor types, and script languages/backends explicitly.\n\n### 3. It treats script execution as a security product, not a checkbox\n\nTikeo’s script model assumes scripts are powerful and risky. The platform separates script type from\nsandbox backend, supports `auto` sandbox selection, and can resolve SRT/Deno/WASM-oriented paths\nwithout defaulting to heavyweight Docker/Podman unless explicitly requested.\n\n### 4. It is built for open-source adoption and central-package publishing\n\nThe repo contains independent SDK packages, examples, Compose stacks, Helm/K8s/Terraform assets,\nrelease workflows, and documentation entry points. It is meant to be consumed by real teams, not just\nstudied as a demo.\n\n## Decision summary\n\n| Choose Tikeo when you need... | Why this is decisive |\n| --- | --- |\n| **A platform, not just a timer** | Jobs, workflows, workers, scripts, plugins, RBAC, audit, and IaC are designed together. |\n| **Multi-language worker adoption** | Teams can keep business code in Java, Rust, Go, Python, or Node.js without losing platform consistency. |\n| **Security-conscious script execution** | Script governance and sandbox choice are part of the model, not an afterthought. |\n| **Cloud-native operating model** | Kubernetes, Terraform, Docker, OTel, and release assets are first-class project surfaces. |\n| **Clear failure forensics** | Task logs, retry logs, worker attempts, audit trails, and topology make failures reviewable. |\n\n## Tikeo vs. XXL-Job vs. PowerJob\n\nThis is not a “feature-count flex.” It is the difference between a classic Java job scheduler and a\ncloud-native orchestration control plane. The original Tikeo design reviewed XXL-Job and PowerJob at\narchitecture level and intentionally replaces their hardest platform limits: inbound executor ports,\nDB-lock leadership, Java-first runtime assumptions, weak script isolation, and status-only operations.\n\n### Executive comparison radar\n\n| Advanced capability | Tikeo advantage | XXL-Job / PowerJob tradeoff |\n| --- | --- | --- |\n| ☁️ **Cloud-native public service model** | **Server and workers can live in different containers, namespaces, clusters, VPCs, or clouds.** Workers dial out over gRPC/HTTP2 tunnel; business pods do not need inbound execution ports. | XXL-Job admin calls executors; PowerJob server calls worker addresses. This is awkward behind NAT, mesh gateways, private pods, and cross-cluster boundaries. |\n| 🐳 **Deployment surface** | **Docker, Compose, Helm, K8s CRD/operator, Terraform provider, GitOps diff, systemd, bare-metal config, and cross-platform release assets** are maintained as first-class surfaces. | Deployable, but not designed as an IaC/GitOps-first platform product. |\n| 🗳️ **Cluster coordination** | **Raft/fencing based server ownership** plus structured worker-domain master election avoids global DB scheduling locks and makes ownership observable. | XXL-Job relies on DB lock patterns; PowerJob mixes DB lock/currentServer/PING-style election instead of durable consensus. |\n| 🔌 **Worker networking** | **Outbound Worker Tunnel** carries registration, dispatch, heartbeats, task logs, and results over one controlled channel. No worker Service/port is required by default. | Executor/worker side must be reachable, configured, and protected as an inbound service. |\n| ⚡ **Performance posture** | **Rust native control plane + gRPC/protobuf + Tokio + compact containers** target low startup latency, stable memory, no JVM warm-up, and efficient long-running services. | JVM-based platforms are mature but carry JVM memory floor, warm-up behavior, larger images, and heavier dependency trees. |\n| 🧠 **Unified orchestration model** | Cron, fixed-rate, API triggers, workflows, broadcast, scripts, plugins, retry/misfire, logs, and audit share one instance/evidence model. | Features are often split across scheduler paths, executor callbacks, local worker state, or plugin conventions. |\n| 🛡️ **Script and plugin governance** | Script type is separate from sandbox backend. `auto` prefers lightweight SRT/Deno/WASM paths, with Docker/Podman/container used explicitly when desired. Immutable versions, digest checks, approvals, grants, and runtime logs are first-class. | Script execution exists, but typically behaves like host-side code execution or processor extension rather than a governed sandbox product. |\n| 🧩 **Cross-language worker clusters** | Java, Rust, Go, Python, and Node.js workers follow the same tunnel, structured capability, retry, logging, sandbox, and management API contracts. **One worker cluster can mix languages** while dispatch still uses typed capabilities instead of language silos. | Primarily Java-first adoption model; mixed-language fleets usually become custom integration work. |\n| 🗄️ **Multi-DB compatibility** | Development can start on SQLite while production can run PostgreSQL or MySQL with tested migration/repository compatibility and Compose profiles. | Typically tied more tightly to one primary relational backend and deployment assumption. |\n| 🔍 **Evidence-first operations** | Terminal-style instance logs, per-worker broadcast results, retry attempts, audit trails, workflow replay bundles, metrics, file logs, and OpenTelemetry traces are designed for incident review. | Traditional scheduler dashboards often answer “status” faster than “why exactly did this happen?” |\n\n### Detailed product matrix\n\n| Evaluation axis | Tikeo | XXL-Job | PowerJob |\n| --- | --- | --- | --- |\n| **Platform role** | ✅ **Full orchestration platform**: jobs, workflows, workers, scripts, plugins, RBAC, observability, IaC. | Mature Java job scheduler. | Mature Java distributed job platform. |\n| **Worker connection model** | ✅ **Outbound gRPC/HTTP2 Worker Tunnel** with lease, generation, fencing, structured registration, task logs, and results. | Admin/executor callback model; executor reachability matters. | Worker server/address model; worker reachability matters. |\n| **Inbound worker ports** | ✅ **Not required by default** for business workers; only the Tikeo server exposes management and tunnel entrypoints. | Usually required for executors. | Usually required for workers. |\n| **Cloud-native deployment** | ✅ **Docker, Compose, Helm, K8s CRD/operator, Terraform provider, GitOps diff**, plus systemd/bare-metal templates. | Deployable, but not GitOps/IaC-first. | Deployable, but not GitOps/IaC-first. |\n| **Cluster ownership** | ✅ **Raft + fencing token** server scheduling ownership; structured worker-cluster master election for ordered dispatch domains. | MySQL lock style coordination. | DB lock + server election mechanisms, not durable consensus-first design. |\n| **Resource profile** | ✅ **Native Rust control plane** designed for compact images, fast startup, predictable memory, and no JVM warm-up. | Java/Spring runtime footprint. | Java/Spring/Akka/Vert.x style footprint and multi-component runtime. |\n| **Routing contract** | ✅ **Typed SDK/plugin/script capabilities**; no magic string parsing. | Name/string oriented. | Name/tag oriented. |\n| **Language ecosystem** | ✅ **Java · Rust · Go · Python · Node.js** SDK parity; the same logical worker cluster can include workers written in different languages. | Primarily Java ecosystem. | Primarily Java ecosystem. |\n| **Database engines** | ✅ **SQLite for local/dev, PostgreSQL and MySQL for production**, with migration and repository compatibility smoke coverage. | Primarily MySQL-oriented deployment. | Primarily MySQL/H2-oriented deployment. |\n| **Script execution** | ✅ **Governed versions + digest checks + SRT/Deno/WASM/V8/container** strategy. | Script execution exists but is not a full sandbox governance product. | Processor-focused; sandbox governance is not the center. |\n| **Workflow UX** | ✅ **Workflow canvas + topology + impact analysis + replay-ready execution data.** | Basic scheduling-centric views. | Workflow support, less focused on typed sandbox + SDK parity. |\n| **Security model** | ✅ **Owner bootstrap, RBAC matrix, opaque sessions, API keys, tenant scopes, audit trails, TLS/mTLS readiness.** | Admin/user model. | Admin/user model. |\n| **Observability** | ✅ **OpenTelemetry, metrics, task logs, file logs, audit logs, worker grouping, replay bundles.** | Traditional operations/logs. | Traditional operations/logs. |\n| **Best fit** | Teams building an internal orchestration platform, not just a cron replacement. | Java teams wanting a familiar scheduler. | Java teams wanting distributed job execution. |\n\n**Short version:** choose Tikeo when you want a modern orchestration control plane; choose legacy\nschedulers only when you intentionally want a narrower Java-first scheduler.\n\n### Evaluation checklist\n\nIf your scheduler shortlist includes these requirements, Tikeo should move to the top:\n\n- [x] **Workers cannot expose inbound ports** because they run inside K8s namespaces, private VPCs, NAT, service mesh, or customer networks.\n- [x] **Docker/Compose/K8s/Helm/Terraform/GitOps** must be part of the product, not examples bolted on later.\n- [x] **Server scheduling ownership should not depend on a global DB lock**; you want Raft/fencing-style ownership evidence.\n- [x] **Worker service clusters need deterministic master election** for ordered dispatch without adding another distributed lock.\n- [x] **Multi-language workers** must share one platform contract across Java, Rust, Go, Python, and Node.js — even inside the same worker fleet.\n- [x] **Multiple database engines** are required: SQLite for fast local bootstrap, PostgreSQL/MySQL for production and team environments.\n- [x] **Script sandbox governance** must support lightweight defaults and explicit runtime policy instead of “just run shell on the host.”\n- [x] **Performance and resource footprint matter**: native server, compact images, no JVM warm-up, stable memory behavior.\n- [x] **Workflow + topology visualization** should show dependencies, impact, replay data, and per-worker broadcast results.\n- [x] **RBAC + API-Key + audit + OTel + durable logs** are required for real platform operations.\n\n## Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/docs/tikeo-architecture.en.svg\" alt=\"Tikeo architecture diagram\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\nThe server owns scheduling, persistence, governance, RBAC, workflows, and dispatch decisions. Workers\nown execution and advertise what they can safely run. Scripts are dispatched as immutable versions and\nexecuted only by workers that expose compatible sandbox runners.\n\n### Core flows\n\n| Flow | What happens |\n| --- | --- |\n| **Job scheduling** | Cron/fixed/API triggers create instances, apply retry/misfire policy, and enqueue dispatch work. |\n| **Worker registration** | A worker dials the tunnel, sends structured capabilities, receives authoritative `worker_id`, and renews its lease. |\n| **Dispatch** | The server matches namespace/app, worker state, master election, and typed capabilities before assigning work. |\n| **Execution evidence** | Workers emit task-scoped logs and result payloads; broadcast mode stores per-worker attempts and outcomes. |\n| **Governance** | RBAC, API keys, tenant scopes, script approvals, audit logs, and GitOps diff keep changes reviewable. |\n\n## Quick start\n\n### 1. Start the control plane\n\n```bash\n./scripts/dev.sh\n```\n\nThis starts the Rust server and React web console, streams logs to the terminal, and also writes local\nlogs under `.dev/`.\n\nOpen \u003chttp://127.0.0.1:5173\u003e. A fresh database routes you to first-run owner setup. After the owner is\ncreated, registration closes and users/roles are managed inside the console.\nThe local SQLite database lives at `.dev/tikeo-dev.db` and is ignored by Git; pulling the repository\nor switching branches must not replace your local runtime data.\n\n### 2. Seed real evaluation data\n\n```bash\n./scripts/dev-seed.sh\n```\n\nThe seed data gives you namespaces, apps, sample jobs, scripts, workflows, audit records, and instance\nlogs so you can evaluate the console immediately instead of staring at an empty product.\nThe seed script is non-destructive by default: if `ns-dev-*` rows already exist, it prints counts and\nleaves local edits unchanged. Use `./scripts/dev-seed.sh --refresh` only when you intentionally want\nto refresh the seeded demo rows.\n\n### 3. Start a worker in your preferred language\n\n```bash\n# Rust\n(cd examples/rust/worker-demo \u0026\u0026 cargo run)\n\n# Go\n(cd examples/go/worker-demo \u0026\u0026 go run .)\n\n# Python\n(cd examples/python/worker-demo \u0026\u0026 python -m pip install -e ../../../sdks/python/tikeo -e . \u0026\u0026 python -m tikeo_python_worker_demo)\n\n# Node.js / Bun\n(cd examples/nodejs/worker-demo \u0026\u0026 bun install \u0026\u0026 bun start)\n\n# Java / Spring Boot 4\n(cd examples/java/spring-boot4-worker-demo \u0026\u0026 ./scripts/run-demo-worker.sh)\n```\n\n### 4. Trigger and inspect\n\nIn the web console:\n\n1. Open **Workers** and confirm the worker appears with structured capabilities.\n2. Open **Jobs** and trigger a seeded SDK/script/plugin job.\n3. Open **Instances** and inspect status, retry attempts, per-worker broadcast results, and terminal-style logs.\n4. Open **Topology** or **Workflows** to inspect dependencies and visual orchestration.\n\nThat path validates the whole value proposition: **control plane**, **worker tunnel**, **SDK execution**,\n**capability matching**, **task logs**, **retry/result evidence**, and **visual operations**.\n\nExpected proof points after the quick start:\n\n| Proof point | Where to see it |\n| --- | --- |\n| **Worker is connected** | Workers page shows the registered worker and structured capabilities. |\n| **Dispatch is structured** | Job trigger selects workers by namespace/app and typed processor/script/plugin capability. |\n| **Execution is explainable** | Instances page shows status, retry progress, worker id, result, and terminal logs. |\n| **Workflows are visible** | Workflow and topology pages show dependencies instead of hiding orchestration in code. |\n\n## What you can build with Tikeo\n\nThese are not separate products you need to stitch together. They are Tikeo operating modes.\n\n| Scenario | High-value keywords | How Tikeo helps |\n| --- | --- | --- |\n| **Internal platform scheduler** | `Worker Tunnel` · `RBAC` · `API-Key` | Give every service team a governed way to register processors and trigger jobs without opening inbound ports. |\n| **Data and reconciliation jobs** | `Retry` · `Misfire` · `Task Logs` | Run recurring or API-triggered tasks with retries, logs, app scopes, and language-specific SDKs. |\n| **Script operations hub** | `SRT` · `Deno` · `WASM` · `Digest` | Approve scripts, release immutable versions, run them in declared sandboxes, and keep output tied to instances. |\n| **Workflow automation** | `Canvas` · `Topology` · `Replay` | Compose jobs into visual workflows and inspect topology/impact before changing dependencies. |\n| **Kubernetes platform integration** | `Helm` · `CRD` · `Terraform` | Use Helm, CRDs, operator status, Terraform diff, and Docker images without rewriting the scheduler. |\n| **Auditable operations** | `Audit` · `OTel` · `Worker Results` | Trace who changed what, which worker ran what, why dispatch failed, and what happened on every retry. |\n\n## Configuration that operators actually need\n\nConfig files live in `config/` and can be overridden with `TIKEO__...` environment variables.\n\n```toml\n[storage]\ndatabase_url = \"postgres://tikeo:tikeo@postgres:5432/tikeo\"\n\n[observability.logging]\nlevel = \"info\"\nlog_dir = \"./logs\"\n\n[observability.tracing]\nenabled = true\notlp_endpoint = \"http://otel-collector:4318/v1/traces\"\n```\n\nStorage support:\n\n| Backend | Recommended use |\n| --- | --- |\n| SQLite | Local development, demos, single-node smoke validation. |\n| PostgreSQL | Production and shared environments. |\n| MySQL | Production environments where MySQL is the platform standard. |\n| CockroachDB-compatible PostgreSQL wire | Distributed SQL environments using PostgreSQL protocol compatibility. |\n\n## SDKs that behave the same way\n\n| Language | Package | Runtime requirement | Best for | Logging contract |\n| --- | --- | --- | --- | --- |\n| Java | `net.tikeo:tikeo`, Spring Boot starters | **Java 17+**; tested in CI on Temurin 21. | Enterprise Spring workers and management automation. | SLF4J diagnostics; task logs through `TaskContext`. |\n| Rust | `tikeo` | **Rust 1.95+** (`rust-version = \"1.95\"`). | Native workers, high-performance runtimes, sandbox-capable services. | `SdkLogConfig`, console + optional `tikeo-sdk.log`. |\n| Go | Go module | **Go 1.26+** (`go 1.26`). | Platform services, operators, cloud-native workers. | `Logger` bridge, console + optional `tikeo-sdk.log`. |\n| Python | `tikeo` | **Python 3.11+**; tested in CI on Python 3.12. | Data jobs, automation, scripting-friendly workers. | stdlib `logging`, console + optional `tikeo-sdk.log`. |\n| Node.js | `@yhyzgn/tikeo` | **Node.js 24+**; Bun is used for repository build/test scripts. | JS/TS workers and web-platform automation. | `configureSdkLogging`, console + optional `tikeo-sdk.log`. |\n\nAll SDKs follow the same rule: SDK diagnostics describe worker/runtime lifecycle; task logs describe a\nspecific job instance. That separation prevents unrelated process noise from polluting execution logs.\n\n## Install SDKs from central registries\n\nUse exactly one SDK dependency per worker service. Do **not** add upstream/transitive Tikeo\nmodules yourself: Gradle, Maven, Cargo, Go, pip, npm, pnpm, and Bun resolve the required upstream\npackages from the single dependency you choose.\n\nVersion placeholders in this section:\n\n- Replace `${TIKEO_VERSION}` with the version shown by the matching top-of-README package badge\n  (`release`, `Java core`, `Boot 3 starter`, `Rust SDK`, `Node.js SDK`, and so on).\n- Go module commands use tag syntax, so use `v${TIKEO_VERSION}`.\n- npm, PyPI, crates.io, and Maven Central use `${TIKEO_VERSION}` without a leading `v`.\n\n| Language | Central registry | Package name | Runtime requirement | Install target |\n| --- | --- | --- | --- | --- |\n| Java | Maven Central | `net.tikeo:*` | Java 17+ | One `net.tikeo` artifact at `${TIKEO_VERSION}`. Default: `tikeo-spring-boot-starter`. |\n| Rust | crates.io | `tikeo` | Rust 1.95+ | `${TIKEO_VERSION}` |\n| Go | Go module proxy | `github.com/yhyzgn/tikeo/sdks/go/tikeo` | Go 1.26+ | tag `v${TIKEO_VERSION}` |\n| Python | PyPI | `tikeo` | Python 3.11+ | `${TIKEO_VERSION}` |\n| Node.js | npm | `@yhyzgn/tikeo` | Node.js 24+ | `${TIKEO_VERSION}` |\n\n### Java / Maven Central\n\nDefault choice for new Java services is **Spring Boot 4** with `net.tikeo:tikeo-spring-boot-starter`.\nChoose **one** artifact for each application. Spring Boot starters bring in the matching core SDK and\nSpring adapter transitively, so do not also declare `tikeo` or `tikeo-spring*` unless you are doing\nmanual dependency mediation.\n\n| Artifact | Add this single dependency when... | Gradle Kotlin DSL line |\n| --- | --- | --- |\n| `net.tikeo:tikeo-spring-boot-starter` | Default for new Java services: Spring Boot 4 / Spring Framework 7 auto-configuration. | `implementation(\"net.tikeo:tikeo-spring-boot-starter:${TIKEO_VERSION}\")` |\n| `net.tikeo:tikeo-spring-boot3-starter` | Spring Boot 3 / Spring Framework 6 auto-configuration. | `implementation(\"net.tikeo:tikeo-spring-boot3-starter:${TIKEO_VERSION}\")` |\n| `net.tikeo:tikeo-spring-boot2-starter` | Spring Boot 2 / Spring Framework 5 auto-configuration. | `implementation(\"net.tikeo:tikeo-spring-boot2-starter:${TIKEO_VERSION}\")` |\n| `net.tikeo:tikeo` | Plain Java worker, management client, sandbox tooling, or low-level Worker Tunnel integration. | `implementation(\"net.tikeo:tikeo:${TIKEO_VERSION}\")` |\n| `net.tikeo:tikeo-spring` | Advanced/manual Spring Framework 7 adapter without the Boot starter. | `implementation(\"net.tikeo:tikeo-spring:${TIKEO_VERSION}\")` |\n| `net.tikeo:tikeo-spring6` | Advanced/manual Spring Framework 6 adapter without the Boot starter. | `implementation(\"net.tikeo:tikeo-spring6:${TIKEO_VERSION}\")` |\n| `net.tikeo:tikeo-spring5` | Advanced/manual Spring Framework 5 adapter without the Boot starter. | `implementation(\"net.tikeo:tikeo-spring5:${TIKEO_VERSION}\")` |\n\nGradle Kotlin DSL examples:\n\n```kotlin\nrepositories {\n    mavenCentral()\n}\n\ndependencies {\n    // Default for new Java services: Spring Boot 4.\n    implementation(\"net.tikeo:tikeo-spring-boot-starter:${TIKEO_VERSION}\")\n\n    // Pick exactly one of these alternatives instead when your runtime requires it:\n    // implementation(\"net.tikeo:tikeo-spring-boot3-starter:${TIKEO_VERSION}\") // Spring Boot 3\n    // implementation(\"net.tikeo:tikeo-spring-boot2-starter:${TIKEO_VERSION}\") // Spring Boot 2\n    // implementation(\"net.tikeo:tikeo:${TIKEO_VERSION}\")                      // plain Java\n    // implementation(\"net.tikeo:tikeo-spring:${TIKEO_VERSION}\")               // manual Spring Framework 7\n    // implementation(\"net.tikeo:tikeo-spring6:${TIKEO_VERSION}\")              // manual Spring Framework 6\n    // implementation(\"net.tikeo:tikeo-spring5:${TIKEO_VERSION}\")              // manual Spring Framework 5\n}\n```\n\nMaven POM examples — copy **exactly one** dependency block:\n\n```xml\n\u003cdependencies\u003e\n  \u003c!-- Default for new Java services: Spring Boot 4 / Spring Framework 7. --\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003enet.tikeo\u003c/groupId\u003e\n    \u003cartifactId\u003etikeo-spring-boot-starter\u003c/artifactId\u003e\n    \u003cversion\u003e${TIKEO_VERSION}\u003c/version\u003e\n  \u003c/dependency\u003e\n\n  \u003c!-- Spring Boot 3 / Spring Framework 6. --\u003e\n  \u003c!--\n  \u003cdependency\u003e\n    \u003cgroupId\u003enet.tikeo\u003c/groupId\u003e\n    \u003cartifactId\u003etikeo-spring-boot3-starter\u003c/artifactId\u003e\n    \u003cversion\u003e${TIKEO_VERSION}\u003c/version\u003e\n  \u003c/dependency\u003e\n  --\u003e\n\n  \u003c!-- Spring Boot 2 / Spring Framework 5. --\u003e\n  \u003c!--\n  \u003cdependency\u003e\n    \u003cgroupId\u003enet.tikeo\u003c/groupId\u003e\n    \u003cartifactId\u003etikeo-spring-boot2-starter\u003c/artifactId\u003e\n    \u003cversion\u003e${TIKEO_VERSION}\u003c/version\u003e\n  \u003c/dependency\u003e\n  --\u003e\n\n  \u003c!-- Plain Java core SDK. --\u003e\n  \u003c!--\n  \u003cdependency\u003e\n    \u003cgroupId\u003enet.tikeo\u003c/groupId\u003e\n    \u003cartifactId\u003etikeo\u003c/artifactId\u003e\n    \u003cversion\u003e${TIKEO_VERSION}\u003c/version\u003e\n  \u003c/dependency\u003e\n  --\u003e\n\n  \u003c!-- Manual Spring Framework 7 adapter without Boot auto-configuration. --\u003e\n  \u003c!--\n  \u003cdependency\u003e\n    \u003cgroupId\u003enet.tikeo\u003c/groupId\u003e\n    \u003cartifactId\u003etikeo-spring\u003c/artifactId\u003e\n    \u003cversion\u003e${TIKEO_VERSION}\u003c/version\u003e\n  \u003c/dependency\u003e\n  --\u003e\n\n  \u003c!-- Manual Spring Framework 6 adapter without Boot auto-configuration. --\u003e\n  \u003c!--\n  \u003cdependency\u003e\n    \u003cgroupId\u003enet.tikeo\u003c/groupId\u003e\n    \u003cartifactId\u003etikeo-spring6\u003c/artifactId\u003e\n    \u003cversion\u003e${TIKEO_VERSION}\u003c/version\u003e\n  \u003c/dependency\u003e\n  --\u003e\n\n  \u003c!-- Manual Spring Framework 5 adapter without Boot auto-configuration. --\u003e\n  \u003c!--\n  \u003cdependency\u003e\n    \u003cgroupId\u003enet.tikeo\u003c/groupId\u003e\n    \u003cartifactId\u003etikeo-spring5\u003c/artifactId\u003e\n    \u003cversion\u003e${TIKEO_VERSION}\u003c/version\u003e\n  \u003c/dependency\u003e\n  --\u003e\n\u003c/dependencies\u003e\n```\n\n#### Spring Boot starter configuration\n\nBoot starters are property-driven. They create the processor registry, Worker Tunnel client,\nlifecycle hook, sandbox runner registries, and optional management client.\n\n```yaml\ntikeo:\n  worker:\n    enabled: true\n    auto-startup: true\n    dry-run: ${TIKEO_WORKER_DRY_RUN:false}\n    endpoint: ${TIKEO_WORKER_ENDPOINT:http://127.0.0.1:9998}\n    client-instance-id: ${TIKEO_WORKER_CLIENT_INSTANCE_ID:}\n    state-dir: ${TIKEO_WORKER_STATE_DIR:}\n    namespace: ${TIKEO_WORKER_NAMESPACE:default}\n    app: ${TIKEO_WORKER_APP:default}\n    cluster: ${TIKEO_WORKER_CLUSTER:default}\n    region: ${TIKEO_WORKER_REGION:default}\n    capabilities: [java, spring-boot]\n    labels:\n      worker_pool: ${TIKEO_WORKER_POOL:java-blue}\n      runtime: java\n\n  management:\n    enabled: ${TIKEO_MANAGEMENT_ENABLED:false}\n    endpoint: ${TIKEO_MANAGEMENT_ENDPOINT:http://127.0.0.1:9999}\n    api-key: ${TIKEO_MANAGEMENT_API_KEY:}\n    namespace: ${TIKEO_MANAGEMENT_NAMESPACE:default}\n    app: ${TIKEO_MANAGEMENT_APP:default}\n```\n\n```java\nimport net.tikeo.processor.TaskContext;\nimport net.tikeo.processor.TaskOutcome;\nimport net.tikeo.processor.TikeoProcessor;\nimport org.slf4j.Logger;\nimport org.slf4j.LoggerFactory;\nimport org.springframework.stereotype.Component;\n\n@Component\npublic final class BillingProcessors {\n    private static final Logger log = LoggerFactory.getLogger(BillingProcessors.class);\n\n    @TikeoProcessor(\"billing.reconcile\")\n    public TaskOutcome reconcile(TaskContext context, String payload) {\n        log.info(\"billing reconcile started instance={} payloadBytes={}\", context.instanceId(), payload.length());\n        return new TaskOutcome(true, \"processed:\" + payload);\n    }\n}\n```\n\n#### Plain Java core SDK configuration\n\nPlain Java does not use `application.yml`. Build `WorkerRegistration`, provide a `TaskProcessor`,\nthen start `GrpcTikeoWorkerClient` yourself.\n\n```java\nimport net.tikeo.processor.TaskOutcome;\nimport net.tikeo.processor.TaskProcessor;\nimport net.tikeo.worker.WorkerCapabilitySet;\nimport net.tikeo.worker.WorkerClusterElection;\nimport net.tikeo.worker.WorkerRegistration;\nimport net.tikeo.worker.client.GrpcTikeoWorkerClient;\nimport java.time.Duration;\nimport java.util.List;\nimport java.util.Map;\n\npublic final class TikeoPlainJavaWorker {\n    public static void main(String[] args) {\n        var registration = new WorkerRegistration(\n            \"orders-java-1\",\n            \"default\",\n            \"orders\",\n            \"local\",\n            \"local\",\n            List.of(\"java\"),\n            new WorkerCapabilitySet(\n                List.of(\"java\"),\n                List.of(\"billing.reconcile\"),\n                List.of(),\n                List.of()\n            ),\n            WorkerClusterElection.enabledByDefault(),\n            Map.of(\"worker_pool\", \"java-core\")\n        );\n\n        TaskProcessor processor = context -\u003e {\n            // Prefer your normal SLF4J logger plus TikeoTaskLogbackAppender in Logback.\n            // TaskContext.logInfo/logError remains available as a direct fallback.\n            context.logInfo(\"plain Java task started\");\n            return new TaskOutcome(true, \"ok:\" + context.processorName());\n        };\n\n        var client = new GrpcTikeoWorkerClient(\n            System.getenv().getOrDefault(\"TIKEO_WORKER_ENDPOINT\", \"http://127.0.0.1:9998\"),\n            registration,\n            processor,\n            Duration.ofSeconds(10)\n        );\n        Runtime.getRuntime().addShutdownHook(new Thread(client::close));\n        client.start();\n    }\n}\n```\n\nFor management API access from plain Java, create `HttpTikeoJobClient(endpoint, apiKey, namespace, app)` directly and inject the API key from your Secret store.\n\n#### Non-Boot Spring Framework configuration\n\nUse `tikeo-spring`, `tikeo-spring6`, or `tikeo-spring5` when you have a Spring Framework application\nwithout Boot auto-configuration. You must define the registry and Worker client beans yourself.\n\n```java\nimport net.tikeo.spring.processor.TikeoProcessorRegistry;\nimport net.tikeo.spring.worker.SpringTikeoTaskProcessor;\nimport net.tikeo.worker.WorkerClusterElection;\nimport net.tikeo.worker.WorkerRegistration;\nimport net.tikeo.worker.client.GrpcTikeoWorkerClient;\nimport net.tikeo.worker.client.TikeoWorkerClient;\nimport java.time.Duration;\nimport java.util.List;\nimport java.util.Map;\nimport org.springframework.context.ApplicationContext;\nimport org.springframework.context.annotation.Bean;\nimport org.springframework.context.annotation.Configuration;\n\n@Configuration\nclass TikeoSpringWorkerConfiguration {\n    @Bean\n    TikeoProcessorRegistry tikeoProcessorRegistry() {\n        return new TikeoProcessorRegistry();\n    }\n\n    @Bean(initMethod = \"start\", destroyMethod = \"close\")\n    TikeoWorkerClient tikeoWorkerClient(\n        ApplicationContext applicationContext,\n        TikeoProcessorRegistry registry\n    ) {\n        registry.scanExistingBeans(applicationContext);\n        var registration = new WorkerRegistration(\n            \"orders-spring-1\",\n            \"default\",\n            \"orders\",\n            \"local\",\n            \"local\",\n            List.of(\"java\", \"spring\"),\n            registry.workerCapabilities(),\n            WorkerClusterElection.enabledByDefault(),\n            Map.of(\"worker_pool\", \"spring-manual\")\n        );\n        return new GrpcTikeoWorkerClient(\n            System.getenv().getOrDefault(\"TIKEO_WORKER_ENDPOINT\", \"http://127.0.0.1:9998\"),\n            registration,\n            new SpringTikeoTaskProcessor(registry),\n            Duration.ofSeconds(10)\n        );\n    }\n}\n```\n\n### Rust / crates.io\n\n```bash\ncargo add tikeo@${TIKEO_VERSION}\n```\n\n```toml\n[dependencies]\ntikeo = \"${TIKEO_VERSION}\"\n```\n\n### Go / Go module proxy\n\n```bash\ngo get github.com/yhyzgn/tikeo/sdks/go/tikeo@v${TIKEO_VERSION}\n```\n\n```go\nimport \"github.com/yhyzgn/tikeo/sdks/go/tikeo\"\n```\n\n### Python / PyPI\n\n```bash\npython -m pip install \"tikeo==${TIKEO_VERSION}\"\n```\n\n```python\nfrom tikeo import Client, local_config\n```\n\n### Node.js / npm\n\n```bash\nbun add @yhyzgn/tikeo@${TIKEO_VERSION}\nnpm install @yhyzgn/tikeo@${TIKEO_VERSION}\npnpm add @yhyzgn/tikeo@${TIKEO_VERSION}\n```\n\n```ts\nimport { Client, WorkerConfig } from \"@yhyzgn/tikeo\";\n```\n\n### Worker runtime configuration shared by SDKs\n\nThese are Worker registration/runtime fields common to the Java, Rust, Go, Python, and Node.js SDKs.\nLanguage-specific wrappers may expose them as Java records, Rust structs, Go structs, Python dataclasses,\nTypeScript classes, or Spring Boot properties.\n\n| Field | Default in SDK helpers | Meaning |\n| --- | --- | --- |\n| `endpoint` | usually `http://127.0.0.1:9998` in demos | Worker Tunnel endpoint reachable from the worker process. |\n| `clientInstanceId` / `client_instance_id` | required for core SDK helpers; Boot can generate/persist it | Stable client-side hint. The server still assigns the authoritative `worker_id`. |\n| `namespace` | `default` | Tenant/environment namespace used for dispatch and management scoping. |\n| `app` | `default` | Application scope used for routing and management operations. |\n| `cluster` | `local` in non-Java helpers; Java Boot default is `default` | Worker cluster or environment shard. |\n| `region` | `local` in non-Java helpers; Java Boot default is `default` | Worker region/zone. |\n| `name` | usually the client instance id | Operator-facing worker name when the language SDK exposes it. |\n| `version` | `dev` in Go/Python/Node helpers | Worker/application build version when exposed by the SDK. |\n| `heartbeatEvery` / `heartbeat-interval-millis` | `10s` / `10000` | Worker lease renewal cadence. |\n| `capabilities` | `[]` | Legacy/operator metadata; dispatch routing uses structured capabilities where available. |\n| `structuredCapabilities` | empty | SDK processors, script runners, plugin processors, and structured tags used for routing. |\n| `labels` | `{}` | Free-form operational metadata such as `worker_pool`, `runtime`, `team`, or `tier`. |\n| `election.enabled` | `true` | Worker-cluster master election flag in registration. |\n| `election.domain` | blank | Blank means `namespace/app/cluster/region`. |\n| `election.priority` | `100` | Deterministic election priority; lower values win. |\n\n## Run Tikeo services\n\nTikeo can run as Docker Compose services, direct binaries on conventional servers, systemd services,\nor Kubernetes workloads. The server exposes the HTTP API/web proxy target on `9090` and the Worker\nTunnel on `9998`; the web console container exposes port `80` internally.\n\n### Realtime console streams and proxies\n\nTikeo Web uses Server-Sent Events (SSE) for realtime workflow timelines, instance logs, Worker\ncluster state, and dispatch queue updates. When the HTTP API is behind nginx, a load balancer, WAF,\nCDN, or Kubernetes Ingress, configure the network path for long-lived `text/event-stream` responses:\n\n- disable response buffering, proxy caching, and gzip/compression buffering for `/api/v1/**/stream`;\n- set read/idle timeouts well above the 15 second SSE keep-alive cadence; `60s` is a minimum and\n  `300s+` is safer for operator consoles;\n- do not use SSE endpoints for health checks; use `/readyz` or `/healthz`;\n- allow authenticated long-lived `GET` responses without `Content-Length`;\n- redact the `token` query parameter in proxy/LB/WAF logs because browser `EventSource` cannot send\n  an `Authorization` header and the Web console uses `?token=...` fallback.\n\nSee the full [SSE realtime deployment notes](docs/docs/deployment/sse-realtime.md) for nginx,\nload balancer, WAF, and Kubernetes Ingress examples.\n\n### Notification channel secret references\n\nNotification provider credentials are configured on each Notification Center channel row, not as one\nshared global provider setting. Put each row's webhook URL, signing key, routing key, SMTP URL,\nSMTP password, authorization header, or app-style credential reference in that channel's\n`secretRefs` object:\n\n```json\n{\n  \"name\": \"billing-feishu-prod\",\n  \"provider\": \"feishu\",\n  \"config\": {\"messageType\": \"interactive\"},\n  \"secretRefs\": {\n    \"url\": \"env:TIKEO_NOTIFICATION_CHANNEL_BILLING_FEISHU_WEBHOOK_URL\",\n    \"signingKey\": \"env:TIKEO_NOTIFICATION_CHANNEL_BILLING_FEISHU_SIGNING_KEY\"\n  }\n}\n```\nUse direct credentials for webhook URLs, tokens, and passwords in the drawer for convenience. Direct values are stored server-side and take effect immediately without service restarts. For deployment flexibility, you can also use `env:NAME` or bare `NAME` variables to resolve from the Server process environment.\nIf a plugin or app-style provider needs `appId`/`appSecret`, store those values or refs in the same channel row's `secretRefs`; the current built-in Feishu/Lark custom bot uses `url` plus optional `signingKey`.\n\n### Docker Compose: SQLite default\n\nUse this for the fastest local product evaluation. It builds the server and web images locally unless\nyou override `TIKEO_IMAGE` / `TIKEO_WEB_IMAGE`.\n\n```bash\ncp deploy/compose/tikeo.env.example .env\nDOCKER_BUILDKIT=1 docker compose --env-file .env up -d --build\ncurl -fsS http://127.0.0.1:${TIKEO_HTTP_PORT:-9090}/readyz\nopen http://127.0.0.1:${TIKEO_WEB_PORT:-8080}\n```\n\n### Docker Compose: PostgreSQL\n\n```bash\ncp deploy/compose/tikeo.env.example .env\nDOCKER_BUILDKIT=1 docker compose --env-file .env \\\n  -f docker-compose.postgres.yml \\\n  up -d --build\ncurl -fsS http://127.0.0.1:${TIKEO_HTTP_PORT:-9090}/readyz\n```\n\n### Docker Compose: MySQL\n\n```bash\ncp deploy/compose/tikeo.env.example .env\nDOCKER_BUILDKIT=1 docker compose --env-file .env \\\n  -f docker-compose.mysql.yml \\\n  up -d --build\ncurl -fsS http://127.0.0.1:${TIKEO_HTTP_PORT:-9090}/readyz\n```\n\n### Docker without Compose\n\nRun the control plane and web container manually when you already manage the database yourself.\n\n```bash\ndocker network create tikeo || true\ndocker volume create tikeo-data\n\ndocker run -d --name tikeo-server --network tikeo \\\n  -p 9090:9090 -p 9998:9998 \\\n  -v tikeo-data:/data \\\n  -e TIKEO__STORAGE__DATABASE_URL='sqlite:///data/tikeo.db?mode=rwc' \\\n  yhyzgn/tikeo-server:0.2.0 serve --config /app/config/container.toml\n\ndocker run -d --name tikeo-web --network tikeo \\\n  -p 8080:80 \\\n  yhyzgn/tikeo-web:0.2.0\n\ncurl -fsS http://127.0.0.1:9090/readyz\n```\n\nFor PostgreSQL/MySQL, replace `TIKEO__STORAGE__DATABASE_URL` with the database URL exposed by your\nplatform and keep credentials in your secret manager.\n\n### Non-Docker binary / VM / bare metal\n\nUse this path for conventional servers, VMs, Supervisor, or manually managed process runners.\nProduction environments should prefer PostgreSQL or MySQL and durable log directories.\n\n```bash\ncargo build --release --bin tikeo\ninstall -d ./var/lib/tikeo ./logs\ncp config/dev.toml ./tikeo.toml\nTIKEO__OBSERVABILITY__LOGGING__LOG_DIR=./logs \\\n  ./target/release/tikeo serve --config ./tikeo.toml\ncurl -fsS http://127.0.0.1:9090/readyz\n```\n\nSystemd deployment uses the checked-in unit files:\n\n```bash\nsudo useradd --system --home /var/lib/tikeo --shell /usr/sbin/nologin tikeo || true\nsudo install -d -o tikeo -g tikeo /opt/tikeo/bin /var/lib/tikeo /var/log/tikeo /etc/tikeo\nsudo install -m 0755 target/release/tikeo /opt/tikeo/bin/tikeo\nsudo install -m 0644 config/container.toml /etc/tikeo/tikeo.toml\nsudo install -m 0644 deploy/systemd/tikeo.env /etc/tikeo/tikeo.env\nsudo install -m 0644 deploy/systemd/tikeo.service /etc/systemd/system/tikeo.service\nsudo systemctl daemon-reload\nsudo systemctl enable --now tikeo\nsystemctl status tikeo --no-pager\n```\n\n### Kubernetes manifests and operator\n\nUse Kubernetes when the control plane should run inside a cluster and workers connect from business\nnamespaces or external services. Start with Helm for normal installs; use the CRD/operator path when\nyou want GitOps drift review through `TikeoManifest` resources.\n\n```bash\nkubectl create namespace tikeo --dry-run=client -o yaml | kubectl apply -f -\nkubectl apply -f deploy/k8s/crd/tikeo-manifest-crd.yaml\nkubectl get crd | grep tikeo\n```\n\nFor a simple Kubernetes smoke deployment without Helm, apply the checked-in manifest:\n\n```bash\nkubectl apply -f deploy/k8s/tikeo.yaml\nkubectl -n tikeo rollout status deploy/tikeo-server\nkubectl -n tikeo rollout status deploy/tikeo-web\n```\n\nThe operator directory contains the controller implementation, RBAC sample, and `TikeoManifest`\nsample for the GitOps diff flow:\n\n```bash\nkubectl apply -f deploy/k8s/crd/tikeo-manifest-crd.yaml\nkubectl -n tikeo apply -f deploy/k8s/operator/config/rbac/role.yaml\nkubectl -n tikeo apply -f deploy/k8s/operator/config/samples/tikeo-manifest.yaml\n```\n\nRun the controller according to `deploy/k8s/operator/README.md` or package it as the release\noperator image for your cluster.\n\n### Helm\n\nInstall from the local chart during development:\n\n```bash\nhelm upgrade --install tikeo ./deploy/helm/tikeo \\\n  --namespace tikeo \\\n  --create-namespace\nkubectl -n tikeo rollout status deploy/tikeo-server\nkubectl -n tikeo rollout status deploy/tikeo-web\n```\n\nInstall a pinned release image set:\n\n```bash\nhelm upgrade --install tikeo ./deploy/helm/tikeo \\\n  --namespace tikeo \\\n  --create-namespace   --set server.image.repository=yhyzgn/tikeo-server   --set server.image.tag=0.2.0   --set web.image.repository=yhyzgn/tikeo-web   --set web.image.tag=0.2.0\n```\n\nProduction clusters should override database settings, ingress/TLS, secret references, resource\nrequests, log collection, and OpenTelemetry endpoints in a values file:\n\n```bash\nhelm upgrade --install tikeo ./deploy/helm/tikeo \\\n  --namespace tikeo \\\n  --create-namespace   --values ./my-tikeo-values.yaml\n```\n\nIf you plan to run more than one Server pod, do not treat it as a normal replica bump. Use the Raft HA overlay and read the dedicated deployment guide first: [Server HA and cluster modes](https://docs.tikeo.net/docs/deployment/server-ha). It includes the topology diagrams, mode comparison, failover behavior, and the current active-passive scheduling trade-off.\n\nCurrent production HA semantics:\n\n| Topic | Current behavior | Trade-off |\n| --- | --- | --- |\n| Server HA | Raft active-passive with `StatefulSet` and `tikeo-server-headless`. | More Server pods improve failover, not scheduling throughput. |\n| Scheduling owner | Exactly one elected Leader reports `canSchedule=true` and runs schedule/dispatch/retry loops. | Followers serve API/health/Raft transport but do not split task dispatch. |\n| Worker Tunnel | Followers reject registration with `FailedPrecondition`; SDKs reconnect until routed to the Leader. | Worker Tunnel exposure must support gRPC/HTTP2 and reconnect/backoff. |\n| External locks | Redis/Dragonfly locks are intentionally not used for core scheduler ownership. | Future multi-active scheduling must use Raft shard ownership with fencing. |\n\n```bash\nkubectl -n tikeo create secret generic tikeo-raft-transport \\\n  --from-literal=transport-token=\"$(openssl rand -hex 32)\"\nhelm upgrade --install tikeo ./deploy/helm/tikeo \\\n  --namespace tikeo \\\n  --create-namespace \\\n  --values deploy/helm/tikeo/examples/values-external-postgres.yaml \\\n  --values deploy/helm/tikeo/examples/values-raft-ha.yaml\nkubectl -n tikeo rollout status statefulset/tikeo-server\n```\n\n### Deployment paths\n\n| Path | Use it when |\n| --- | --- |\n| `docker-compose.yml` | You want the fastest local product evaluation with SQLite. |\n| `docker-compose.postgres.yml` / `docker-compose.mysql.yml` | You want a complete server + web + database stack for PostgreSQL or MySQL. |\n| `deploy/systemd/` | You run Tikeo on VMs or bare-metal hosts. |\n| `deploy/helm/tikeo/` | You deploy the control plane into Kubernetes. |\n| `deploy/k8s/operator/` | You want CRD-based GitOps drift review. |\n| `deploy/terraform/provider/` | You want manifest export/diff in Terraform workflows. |\n\n## Observability and troubleshooting\n\nTikeo is designed so operators can answer the questions that matter:\n\n- **Why did this instance dispatch or not dispatch?** Check instance logs and capability/governance messages.\n- **Which worker executed the task?** Inspect instance results and broadcast worker grouping.\n- **What did the script output?** Read task-scoped terminal logs, not generic process logs.\n- **What changed before the failure?** Use audit logs, GitOps diff, and job/workflow versions.\n- **Where is latency coming from?** Use OpenTelemetry, metrics, and SDK/server diagnostics.\n\n## Repository map\n\n```text\ncrates/            Rust server crates, scheduling, storage, worker tunnel, HTTP API\nweb/               React + Ant Design management console\nsdks/              Java, Rust, Go, Python, and Node.js SDKs\nexamples/          Runnable worker demos per language\ndeploy/            Compose, Helm, K8s operator, Terraform provider, systemd, smoke tests\ndocs/              Operations, reports, localized docs, and README assets\ndesign/            Architecture and roadmap records\nscripts/           Development, seeding, release, and verification helpers\n```\n\n## Verification\n\n```bash\ncargo test --workspace\n(cd web \u0026\u0026 bun run typecheck \u0026\u0026 bun run build)\n(cd sdks/java \u0026\u0026 ./gradlew test --no-daemon)\n(cd sdks/rust/tikeo \u0026\u0026 cargo test --all-features)\n(cd sdks/go/tikeo \u0026\u0026 go test ./...)\n(cd sdks/python/tikeo \u0026\u0026 python -m pytest)\n(cd sdks/nodejs/tikeo \u0026\u0026 bun test \u0026\u0026 bun run build)\n```\n\n## Support Tikeo\n\nIf Tikeo saves you evaluation time or gives your team a clearer orchestration path, please consider giving the repository a ⭐. It helps more platform engineers discover the project.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=yhyzgn/tikeo\u0026type=Date)](https://www.star-history.com/#yhyzgn/tikeo\u0026Date)\n\n## License\n\nMIT. Build boldly, operate carefully, and keep execution evidence precise.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyhyzgn%2Ftikeo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyhyzgn%2Ftikeo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyhyzgn%2Ftikeo/lists"}