{"id":37139247,"url":"https://github.com/apoxy-dev/proximal","last_synced_at":"2026-01-14T16:03:08.570Z","repository":{"id":183553550,"uuid":"663659663","full_name":"apoxy-dev/proximal","owner":"apoxy-dev","description":"WebAssembly dev environment for Envoy Proxy. Iterate on your HTTP/TCP middleware in seconds!","archived":false,"fork":false,"pushed_at":"2023-08-08T05:57:13.000Z","size":2737,"stargazers_count":54,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-24T23:45:05.474Z","etag":null,"topics":["envoy","envoyproxy","http-proxy","http-proxy-middleware","istio","proxy-wasm","proxy-wasm-rust-sdk","reverse-proxy","tcp-proxy","wasi","wasm"],"latest_commit_sha":null,"homepage":"https://apoxy.dev","language":"Go","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/apoxy-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-07-07T20:15:17.000Z","updated_at":"2024-09-01T14:32:13.000Z","dependencies_parsed_at":"2023-07-24T23:08:50.217Z","dependency_job_id":null,"html_url":"https://github.com/apoxy-dev/proximal","commit_stats":null,"previous_names":["apoxy-dev/proximal"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/apoxy-dev/proximal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apoxy-dev%2Fproximal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apoxy-dev%2Fproximal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apoxy-dev%2Fproximal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apoxy-dev%2Fproximal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apoxy-dev","download_url":"https://codeload.github.com/apoxy-dev/proximal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apoxy-dev%2Fproximal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28425596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T15:24:48.085Z","status":"ssl_error","status_checked_at":"2026-01-14T15:23:41.940Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["envoy","envoyproxy","http-proxy","http-proxy-middleware","istio","proxy-wasm","proxy-wasm-rust-sdk","reverse-proxy","tcp-proxy","wasi","wasm"],"created_at":"2026-01-14T16:03:07.708Z","updated_at":"2026-01-14T16:03:08.560Z","avatar_url":"https://github.com/apoxy-dev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cbr /\u003e\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ca href=\"https://apoxy.dev\"\u003e\n  \u003cimg src=\"static/github-proximal.png\" alt=\"Proximal Logo\" width=\"350\"\u003e\n\u003c/a\u003e\n\u003cbr /\u003e\n\u003cbr /\u003e\n\n[![Apache 2.0 License](https://badgen.net/badge/License/Apache2.0?icon=github)](LICENSE) [![Slack Community](https://img.shields.io/badge/slack-apoxy-bde868.svg?logo=slack)](http://slack.apoxy.dev/)\n  \n\u003c/div\u003e\n\u003cbr /\u003e\n\nProximal makes it easy to develop\n[Proxy-WASM](https://github.com/proxy-wasm/spec) modules for [Envoy](https://www.envoyproxy.io)\nright on your local machine (or anywhere you can run our [Docker\nimage](https://hub.docker.com/r/apoxy/proximal)).\n\n## TL;DR\n\nDevelop WebAssembly extensions for Envoy with ease. Try running `docker run -p 8080:8080 -p 18000:18000 docker.io/apoxy/proximal:latest`\nthen visit http://localhost:8080\n\nDemo:\n\nhttps://github.com/apoxy-dev/proximal/assets/767232/97cea009-7f6c-47f9-b2d6-70146ef7ff3a\n\n### What is Proxy-WASM?\n\n[Proxy-WASM](https://github.com/proxy-wasm/spec) (WebAssembly) is a powerful technology that enables\nyou to extend the functionality of modern proxies like [Envoy](https://www.envoyproxy.io) with\nWebAssembly modules. By writing Proxy-WASM modules, you can write code in your L4/L7 proxy that inspects,\nmutates, and routes requests as they are passing through, all in a language-independent and sandboxed\nenvironment. It works with both HTTP and TCP-based connection and SDKs are available for\n[Rust](https://github.com/proxy-wasm/proxy-wasm-rust-sdk),\n[Go](https://github.com/tetratelabs/proxy-wasm-go-sdk),\n[C++](https://github.com/proxy-wasm/proxy-wasm-cpp-sdk), and\n[AssemblyScript](https://github.com/solo-io/proxy-runtime) (we're working on JavaScript and Python).\n\nThese standards based WebAssembly modules can be used with [Istio](https://istio.io/latest/docs/concepts/wasm/),\n[MOSN](https://github.com/mosn/mosn) and\n[APSIX](https://apisix.apache.org/blog/2021/11/19/apisix-supports-wasm/#how-to-use-wasm-in-apache-apisix) as well.\n\n## Why Proximal?\n\nDeveloping Proxy-WASM modules for Envoy traditionally involves cumbersome setups, complex\ntoolchains, and time-consuming testing iterations, frequently on a remote environment.\nProximal simplifies the development process and brings it to your local machine in a single process\nenvironment with a friendly UI and basic REST API.\n\nWe believe that developers have been held back from adopting this incredibly powerful technology because\nthe developer experience for WASM and Proxy-WASM has been a little rough around the edges. Proximal is here to help.\n\n### Key Features:\n\n* **Local Development**: Forget about deploying to remote environments for every code change. Proximal\n  allows you to develop and test your Proxy-WASM modules locally, saving you valuable time and\n  effort. It features a workflow engine that compiles source code into\n  WebAssembly binary (.wasm) and loads them into Envoy automatically.\n\n* **Rapid Iterations**: Change your code and see the results almost instantaneously. Proximal continuously\n  watches a working directory (even Docker mounted volumes) and triggers a rebuild/reload of your module in Envoy automatically.\n\n* **Simplified Setup + Examples**: Setting up a development environment for Proxy-WASM can be daunting. Proximal\n  streamlines the process and provides a few examples you can use to get started with minimal configuration.\n\n* **Observability**: Debugging is easier with integrated logs capture. See requests and responses in real-time.\n\n## Getting Started\n\nRun via Docker container:\n\n```shell\ndocker run -p 8080:8080 -p 9901:9901 -p 9088:9088 -p 18000:18000 -v `pwd`:/mnt docker.io/apoxy/proximal:latest\n```\n\nThe above command mounts your current working directory at `/mnt` inside the container so you can ingest local\nProxy-WASM code (e.g. `/mnt/myprojects/myawesome-proxy-wasm-go/`). Adjust as needed.\n\nBound ports:\n* `8080` - Web UI (see below) and REST API at `:8080/v1/` (see definitions in the [`//api`](https://github.com/apoxy-dev/proximal/tree/main/api) folder).\n* `18000` - Envoy listener - test your proxy configurations by sending requests to `localhost:18000`.\n* `9901` - Envoy admin UI.\n* `9088` - Temporal UI (for build workflow debugging).\n\n\n## Architecture\n\nWe rely on Envoy as the main [data plane](https://en.wikipedia.org/wiki/Forwarding_plane) processing\nengine for request routing and its WebAssembly (WASI) extension engine that implements the Proxy-WASM\nABI. The default runtime is [Chromium V8](https://v8.dev) but other runtimes such as\n[Wasmtime](https://wasmtime.dev),\n[Wamr](https://github.com/bytecodealliance/wasm-micro-runtime), and\n[WAVM](https://wavm.github.io/)\ncan be configured.\n\nThe control plane server is a single Go binary that combines an Envoy control plane (using xDS\nprotocol), a REST API server, a React app, and a [Temporal](https://temporal.io) server\n(which is linked directly via the awesome [temporalite](https://github.com/temporalio/temporalite) library)\nfor managing build workflows. The same binary also acts as a Temporal worker and manages the Envoy process.\n\nInternal state is supported by an embedded SQLite instance which produces an `sqlite3.db` file on local\ndisk. The Temporal server has its own SQLite db file - `temporalite.db`. Both of these need to be exported\nvia Docker volume mount if you want state persisted across Docker runs.\n\nCompiled `.wasm` binaries are stored on local disk in the `/tmp/proximal/` directory.\n\nHTML/CSS/JavaScript assets currently live on local filesystem but will be embedded in the binary\nitself in the future.\n\nHigh-level Design:\n\n\u003cdiv align=\"center\"\u003e\n  \n![proximal-architecture](https://github.com/apoxy-dev/proximal/assets/284347/3585bbae-b014-47cd-aa38-d47a03acacc3)\n\n\u003c/div\u003e\n\n## Known Limitations / Future Improvements\n\nKnown Limitations:\n\n* The entire setup is a single instance, single binary deal designed for local experimentation.\n  While it's possible to run it on remote host since it's packaged in Docker, replication features\n  are rather lacking.\n* TCP filters aren't yet supported.\n* Currently Proximal supports re-triggering builds from a git source manually. Automatic build\n  triggers from GitHub commit webhooks or the like aren't suppported since they would require a\n  hosted solution with a stable webhook endpoint.\n\nRoadmap:\n\n* More SDKs + Examples - [AssemblyScript](https://github.com/apoxy-dev/proximal/issues/1),\n  [C++](https://github.com/apoxy-dev/proximal/issues/2),\n  [JavaScript](https://github.com/apoxy-dev/proximal/issues/3), and\n  [Python](https://github.com/apoxy-dev/proximal/issues/4).\n* Istio examples - show how you take these modules into an existing Istio-enabled cluster.\n* K/V store integration.\n* Improved logging / tracing / accounting.\n* TCP and UDP filters.\n\nIf you're interested in any of above features (or maybe something else), feel free to drop a note to the\n[Apoxy Team](mailto:hello@apoxy.dev) or open an issue on this repo!\n\n## Contributing\n\nPatches Welcome! (no, really)\n\nProximal welcomes contributions from the community. If you find bugs, or wish to contribute code, please\ncheck out our [contribution guidelines](DEVELOPING.md) for detailed instructions.\n\n### Support and Feedback\n\nIf you encounter any issues, have questions, or want to provide feedback, we want to hear from you!\nFeel free to join our active community on Slack, raise an issue on GitHub, or shoot us an email:\n\n* [Apoxy Community Slack](http://slack.apoxy.dev/)\n* [👋 Apoxy Email](mailto:hello@apoxy.dev)\n\n## License\n\nProximal is released under the [Apache 2.0 License](LICENSE).\n\n## Credits\n\nProximal is developed and maintained by the Apoxy team. We want to thank the open-source community\nfor their contributions and support in making this project possible. Special thanks go to: [Envoy\nProxy](https://www.envoyproxy.io) community, [Proxy-WASM ABI and\nSDKs](https://github.com/proxy-wasm/spec) contributors, and fine folks at\n[Temporal](https://temporal.io).\n\n\u003cbr /\u003e\n\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://apoxy.dev\"\u003e\n  \u003cimg src=\"static/github-apoxy.png\" alt=\"Apoxy Logo\" width=\"350\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\u003cbr /\u003e\n\u003cbr /\u003e\n\n\u003cp align=\"center\"\u003e\nLet's take Proxy-WASM development to new levels with Proximal! Happy Proxying! 🚀\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapoxy-dev%2Fproximal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapoxy-dev%2Fproximal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapoxy-dev%2Fproximal/lists"}