{"id":13431009,"url":"https://github.com/cloudflare/workerd","last_synced_at":"2026-06-27T03:02:22.199Z","repository":{"id":60274004,"uuid":"537085161","full_name":"cloudflare/workerd","owner":"cloudflare","description":"The JavaScript / Wasm runtime that powers Cloudflare Workers","archived":false,"fork":false,"pushed_at":"2026-06-22T01:36:39.000Z","size":49669,"stargazers_count":8341,"open_issues_count":598,"forks_count":657,"subscribers_count":67,"default_branch":"main","last_synced_at":"2026-06-22T05:03:05.133Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://blog.cloudflare.com/workerd-open-source-workers-runtime/","language":"C++","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/cloudflare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"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":"2022-09-15T15:15:16.000Z","updated_at":"2026-06-22T01:36:41.000Z","dependencies_parsed_at":"2026-04-02T12:15:22.193Z","dependency_job_id":"bd2488f4-58ab-46b4-ac7e-fab857b48cc8","html_url":"https://github.com/cloudflare/workerd","commit_stats":{"total_commits":3163,"total_committers":109,"mean_commits":29.01834862385321,"dds":0.7723680050584888,"last_synced_commit":"9bc5f086a19d106ac63b9137d13e6ff66b963db2"},"previous_names":[],"tags_count":495,"template":false,"template_full_name":null,"purl":"pkg:github/cloudflare/workerd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fworkerd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fworkerd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fworkerd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fworkerd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudflare","download_url":"https://codeload.github.com/cloudflare/workerd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fworkerd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34839888,"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-27T02:00:06.362Z","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":[],"created_at":"2024-07-31T02:00:59.766Z","updated_at":"2026-06-27T03:02:22.170Z","avatar_url":"https://github.com/cloudflare.png","language":"C++","funding_links":[],"categories":["C++","\u003ca name=\"cpp\"\u003e\u003c/a\u003eC++","Core Platform \u0026 SDKs","others","Repos","Libraries and Frameworks","🛠️ 开发与脚手架"],"sub_categories":["Runtime \u0026 Core Tools"],"readme":"# 👷 `workerd`, Cloudflare's JavaScript/Wasm Runtime\n\n![Banner](/docs/assets/banner.png)\n\n`workerd` (pronounced: \"worker-dee\") is a JavaScript / Wasm server runtime based on the same code that powers [Cloudflare Workers](https://workers.dev).\n\nYou might use it:\n\n* **As an application server**, to self-host applications designed for Cloudflare Workers.\n* **As a development tool**, to develop and test such code locally.\n* **As a programmable HTTP proxy** (forward or reverse), to efficiently intercept, modify, and\n  route network requests.\n\n## Introduction\n\n### Design Principles\n\n* **Server-first:** Designed for servers, not CLIs nor GUIs.\n\n* **Standard-based:** Built-in APIs are based on web platform standards, such as `fetch()`.\n\n* **Nanoservices:** Split your application into components that are decoupled and independently-deployable like microservices, but with performance of a local function call. When one nanoservice calls another, the callee runs in the same thread and process.\n\n* **Homogeneous deployment:** Instead of deploying different microservices to different machines in your cluster, deploy all your nanoservices to every machine in the cluster, making load balancing much easier.\n\n* **Capability bindings:** `workerd` configuration uses capabilities instead of global namespaces to connect nanoservices to each other and external resources. The result is code that is more composable -- and immune to SSRF attacks.\n\n* **Always backwards compatible:** Updating `workerd` to a newer version will never break your JavaScript code. `workerd`'s version number is simply a date, corresponding to the maximum [\"compatibility date\"](https://developers.cloudflare.com/workers/platform/compatibility-dates/) supported by that version. You can always configure your worker to a past date, and `workerd` will emulate the API as it existed on that date.\n\n[Read the blog post to learn more about these principles.](https://blog.cloudflare.com/workerd-open-source-workers-runtime/)\n\n### WARNING: `workerd` is not a hardened sandbox\n\n`workerd` tries to isolate each Worker so that it can only access the resources it is configured to access. However, `workerd` on its own does not contain suitable defense-in-depth against the possibility of implementation bugs. When using `workerd` to run possibly-malicious code, you must run it inside an appropriate secure sandbox, such as a virtual machine. The Cloudflare Workers hosting service in particular [uses many additional layers of defense-in-depth](https://blog.cloudflare.com/mitigating-spectre-and-other-security-threats-the-cloudflare-workers-security-model/).\n\nWith that said, if you discover a bug that allows malicious code to break out of `workerd`, please submit it to [Cloudflare's bug bounty program](https://hackerone.com/cloudflare?type=team) for a reward.\n\n## Getting Started\n\n### Supported Platforms\n\nIn theory, `workerd` should work on any POSIX system that is supported by V8 and Windows.\n\nIn practice, `workerd` is tested on:\n\n* Linux and macOS (x86-64 and arm64 architectures)\n* Windows (x86-64 architecture)\n\nOn other platforms, you may have to do tinkering to make things work.\n\n### Building `workerd`\n\nTo build `workerd`, you need:\n\n* Bazel\n  * If you use [Bazelisk](https://github.com/bazelbuild/bazelisk) (recommended), it will automatically download and use the right version of Bazel for building workerd.\n* On Linux:\n  * We use the clang/LLVM toolchain to build workerd and support version 19 and higher. Earlier versions of clang may still work, but are not officially supported.\n  * Clang 19+ (e.g. package `clang-19` on Debian Trixie). If clang is installed as `clang-\u003cversion\u003e` please create a symlink to it in your PATH named `clang`, or use `--repo_env=CC=clang-\u003cversion\u003e` on `bazel` command lines to specify the compiler name.\n\n  * libc++ 19+ (e.g. packages `libc++-19-dev` and `libc++abi-19-dev`)\n  * LLD 19+ (e.g. package `lld-19`).\n  * `python3`, `python3-distutils`, and `tcl8.6`\n* On macOS:\n  * Xcode 16.3 installation (available on macOS 15 and higher). Building with just the Xcode Command Line Tools is not being tested, but should work too.\n  * Homebrew installed `tcl-tk` package (provides Tcl 8.6)\n* On Windows:\n  * Install [App Installer](https://learn.microsoft.com/en-us/windows/package-manager/winget/#install-winget)\n    from the Microsoft Store for the `winget` package manager and then run\n    [install-deps.bat](tools/windows/install-deps.bat) from an administrator prompt to install\n    bazelisk, LLVM, and other dependencies required to build workerd on Windows.\n  * Add `startup --output_user_root=C:/tmp` to the `.bazelrc` file in your user directory.\n  * When developing at the command-line, run [bazel-env.bat](tools/windows/bazel-env.bat) in your shell first\n    to select tools and Windows SDK versions before running bazel.\n\nYou may then build `workerd` at the command-line with:\n\n```sh\nbazel build //src/workerd/server:workerd\n```\n\nYou can pass `--config=release` to compile in release mode:\n\n```sh\nbazel build //src/workerd/server:workerd --config=release\n```\n\nYou can also build from within Visual Studio Code using the instructions in [docs/vscode.md](docs/vscode.md).\n\nThe compiled binary will be located at `bazel-bin/src/workerd/server/workerd`.\n\nIf you run a Bazel build before you've installed some dependencies (like clang or libc++), and then you install the dependencies, you must resync locally cached toolchains, or clean Bazel's cache, otherwise you might get strange errors:\n\n```sh\nbazel fetch --configure --force\n```\n\nIf that fails, you can try:\n\n```sh\nbazel clean --expunge\n```\n\nThe cache will now be cleaned and you can try building again.\n\nIf you have a fairly recent clang packages installed you can build a more performant release\nversion of workerd:\n\n```sh\nbazel build --config=thin-lto //src/workerd/server:workerd\n```\n\n### Configuring `workerd`\n\n`workerd` is configured using a config file written in Cap'n Proto text format.\n\nA simple \"Hello World!\" config file might look like:\n\n```capnp\nusing Workerd = import \"/workerd/workerd.capnp\";\n\nconst config :Workerd.Config = (\n  services = [\n    (name = \"main\", worker = .mainWorker),\n  ],\n\n  sockets = [\n    # Serve HTTP on port 8080.\n    ( name = \"http\",\n      address = \"*:8080\",\n      http = (),\n      service = \"main\"\n    ),\n  ]\n);\n\nconst mainWorker :Workerd.Worker = (\n  serviceWorkerScript = embed \"hello.js\",\n  compatibilityDate = \"2023-02-28\",\n  # Learn more about compatibility dates at:\n  # https://developers.cloudflare.com/workers/platform/compatibility-dates/\n);\n```\n\nWhere `hello.js` contains:\n\n```javascript\naddEventListener(\"fetch\", event =\u003e {\n  event.respondWith(new Response(\"Hello World\"));\n});\n```\n\n[Complete reference documentation is provided by the comments in workerd.capnp.](src/workerd/server/workerd.capnp)\n\n[There is also a library of sample config files.](samples)\n\n### Running `workerd`\n\nTo serve your config, do:\n\n`workerd serve my-config.capnp`\n\nFor more details about command-line usage, use `workerd --help`.\n\nPrebuilt binaries are distributed via `npm`. Run `npx workerd ...` to use these. If you're running a prebuilt binary, you'll need to make sure your system has the right dependencies installed:\n\n* On Linux:\n  * glibc 2.35 or higher (already included on e.g. Ubuntu 22.04, Debian Bookworm)\n* On macOS:\n  * macOS 13.5 or higher\n  * The Xcode command line tools, which can be installed with `xcode-select --install`\n* x86_64 CPU with at least SSE4.2 and CLMUL ISA extensions, or arm64 CPU with CRC extension (enabled by default under armv8.1-a). These extensions are supported by all recent x86 and arm64 CPUs.\n\n### Local Worker development with `wrangler`\n\nYou can use [Wrangler](https://developers.cloudflare.com/workers/wrangler/) (v3.0 or greater) to develop Cloudflare Workers locally, using `workerd`. First, run the following command to configure Miniflare to use this build of `workerd`.\n\n```\nexport MINIFLARE_WORKERD_PATH=\"\u003cWORKERD_REPO_DIR\u003e/bazel-bin/src/workerd/server/workerd\"\n```\n\nThen, run:\n\n`wrangler dev`\n\n### Serving in production\n\n`workerd` is designed to be unopinionated about how it runs.\n\nOne good way to manage `workerd` in production is using `systemd`. Particularly useful is `systemd`'s ability to open privileged sockets on `workerd`'s behalf while running the service itself under an unprivileged user account. To help with this, `workerd` supports inheriting sockets from the parent process using the `--socket-fd` flag.\n\nHere's an example system service file, assuming your config defines two sockets named `http` and `https`:\n\n```sh\n# /etc/systemd/system/workerd.service\n[Unit]\nDescription=workerd runtime\nAfter=local-fs.target remote-fs.target network-online.target\nRequires=local-fs.target remote-fs.target workerd.socket\nWants=network-online.target\n\n[Service]\nType=exec\nExecStart=/usr/bin/workerd serve /etc/workerd/config.capnp --socket-fd http=3 --socket-fd https=4\nSockets=workerd.socket\n\n# If workerd crashes, restart it.\nRestart=always\n\n# Run under an unprivileged user account.\nUser=nobody\nGroup=nogroup\n\n# Hardening measure: Do not allow workerd to run suid-root programs.\nNoNewPrivileges=true\n\n[Install]\nWantedBy=multi-user.target\n```\n\nAnd corresponding sockets file:\n\n```sh\n# /etc/systemd/system/workerd.socket\n[Unit]\nDescription=sockets for workerd\nPartOf=workerd.service\n\n[Socket]\nListenStream=0.0.0.0:80\nListenStream=0.0.0.0:443\n\n[Install]\nWantedBy=sockets.target\n```\n\nOnce these files are in place you can enable the service -- see the systemd documentation or ask your favorite LLM for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fworkerd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudflare%2Fworkerd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fworkerd/lists"}