{"id":39358267,"url":"https://github.com/fgrosse/prox","last_synced_at":"2026-01-18T02:39:33.084Z","repository":{"id":144209952,"uuid":"254859194","full_name":"fgrosse/prox","owner":"fgrosse","description":"A process runner for Procfile-based applications","archived":false,"fork":false,"pushed_at":"2024-07-13T08:54:02.000Z","size":12145,"stargazers_count":13,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-22T22:41:14.561Z","etag":null,"topics":["foreman","go","golang","process-runner","procfile"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fgrosse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-11T12:06:27.000Z","updated_at":"2024-08-14T08:00:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"c675f028-72c1-47fe-a493-749ab60cfa00","html_url":"https://github.com/fgrosse/prox","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/fgrosse/prox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrosse%2Fprox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrosse%2Fprox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrosse%2Fprox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrosse%2Fprox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fgrosse","download_url":"https://codeload.github.com/fgrosse/prox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrosse%2Fprox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28526591,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"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":["foreman","go","golang","process-runner","procfile"],"created_at":"2026-01-18T02:39:32.684Z","updated_at":"2026-01-18T02:39:33.069Z","avatar_url":"https://github.com/fgrosse.png","language":"Go","readme":"# Prox [![Unit Tests](https://github.com/fgrosse/prox/actions/workflows/test.yml/badge.svg)](https://github.com/fgrosse/prox/actions/workflows/test.yml) [![GitHub release](https://img.shields.io/github/tag/fgrosse/prox.svg?style=flat)](https://github.com/fgrosse/prox/releases)  [![License](https://img.shields.io/github/license/fgrosse/prox.svg)](https://github.com/fgrosse/prox/blob/master/LICENSE) [![GoDoc](https://godoc.org/github.com/fgrosse/prox?status.svg)](https://godoc.org/github.com/fgrosse/prox)\n\nProx is a process runner for Procfile-based applications inspired by [foreman][foreman].\nWith `prox` you can run several processes defined in a `Procfile` concurrently\nwithin a single terminal. All process outputs are merged but prefixed with their\ncorresponding process names. One of the major use cases for this is the local\ndevelopment of an application that consist of multiple processes (e.g.\nmicroservices and storage backends). With a process runner you can easily start\nthis \"stack\" of applications and inspect its output in a single shell while\ninteracting with the application.\n\nYou may ask why not just use *docker* for local development since it provides\nsimilar functionality to run multiple processes, especially when using docker-compose.\nThe reason is ease of development and a fast development cycle also for small\ncode changes. It just takes longer than necessary to recompile a binary and\nadditionally build the docker image. Also the extra file system and process isolation\nthat are one of dockers many benefits in a production environment can become quite\na nuisance during local development.\n\n## Features\n\nProx primary use case is as a development tool to run your entire application stack\non your local machine. Apart from running all components, Proxs primary goal is to\nhelp you understand what the application is doing and sometimes help to debug why\na component has crashed.\n\n### Error reporting\n\nLike other process managers, prox will stop the entire stack when one of the\nmanaged processes has crashed. This way the system fails fast and it is the\ndevelopers task to understand and fix the problem. This usually entails searching\nthrough the log output for the first fatal error which caused the system to go down.\nProx helps with this by reporting the name and exit code of the process that was\nthe root cause for the stack shutdown.\n\n### Log parsing\n\nToday it is good practice for applications to emit structured log output so it\ncan be parsed and used easily. Prox detects if a process encodes its logs as JSON\nand can use this information to reformat and color the output. By default this is\nused to highlight error messages but the user can specify custom formatting as well.\n\nIn the future log parsing can also be used during error reporting to print the\nlast error message of the component which crashed the stack.\n\n### Prox Server\n\nAnother thing that distinguishes Prox from [other foreman clones](#similar-projects)\nis that when prox starts the application, it will also listen on a unix socket for\nrequests. This makes it possible to interact with a running Prox instance in\nanother terminal, for instance to tail the logs of a subset of processes. This can\nbe useful when working with many processes where the merged output of all\napplications can be rather spammy and is hard to be read by humans.\n\nThe current version of the prox server only implements tailing but you can take\na look at the [IDEAS.md](IDEAS.md) file for other functionality that might be\nimplemented later on.\n\n## Proxfile\n\nAdvanced users can use a slightly more complicated `Proxfile` which serves as an\nopt-in alternative to the `Procfile` but with more features (see [usage below](#advanced-proxfile-usage)).\n\n## Installation\n\nAll you need to run prox is a single binary. You can either use a prebuilt\nbinary or build prox from source.\n\n### Prebuilt binaries\n\nDownload the binary from the [releases page][releases] and extract the `prox` binary\nsomewhere in your path.\n\n### Building from source\n\nIf you want to compile prox from source you need a working installation of Go\nversion 1.9 or greater.\n\nYou can either install prox directly via `go get` or use the `make install` target.\nThe preferred way is the installation via make since this compiles version information\ninto the `prox` binary. You can inspected the version of your prox binary via\n`prox version`. This is helpful when reporting issues and debugging but it is\notherwise of no use.\n\n```bash\ngo get -v github.com/fgrosse/prox/cmd/prox\ncd $GOPATH/src/github.com/fgrosse/prox\nmake install\n```\n\n## Usage\n\nYou always need a `Procfile` or `Proxfile` which defines all processes that you want to run.\n\n### Simple Procfile usage\n\n```bash\n$ cat Procfile\n# You can use comments, empty lines are ignored as well\nworker: my-worker -v /etc/foo # prox uses your $PATH and passes arguments and flags as expected\n\nfoo-service: CONFIG_DIR=$PWD/config foo-serve # You can set and use environment variables per job\nbar-service: bar-serve # Additionally all processes inherit your shells environment\nbaz-service: baz-serve # If there is a .env file it will be used to set variables for all processes\n```\n\nOptionally you can create a `.env` file which must contain a new-line delimited\nlist of key=value pairs which specify additional environment variables that are\nexported to all processes defined within the `Procfile`.\n\n```bash\n$ cat .env\nNAMESPACE=production\nFOO_URL=file://home/fgrosse/src/github.com/foo/bar\n\n# Again you may use empty lines and comments starting with '#'\nETCD_ENDPOINT=localhost:2379\nLOG=*:debug,xxx:info,cache:error,db:info\n\n# You can also use environment variables that you have defined earlier or that\n# are defined in the shell that started prox.\nPATH=/etc/foo/$NAMESPACE/baz:$PATH\n\n# Spaces are allowed in values without any extra quoting\nGREETING=hello world\n```\n\nThen change into the directory which contains your `Procfile` and `.env` and start\nprox.\n\n```bash\n$ prox\necho1    │ I am a process\necho2    │ Hello World\nredis    │ 14773:C 03 Oct 21:17:26.487 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo\nredis    │ 14773:C 03 Oct 21:17:26.487 # Redis version=4.0.1, bits=64, commit=00000000, modified=0, pid=14773, just started\n…\n```\n\nIn order to follow the logs of a _specific_ process open another terminal.\n\n```bash\nprox tail redis\nredis    │ 15249:M 03 Oct 21:21:13.044 # Server initialized\nredis    │ 15249:M 03 Oct 21:21:13.045 * DB loaded from disk: 0.000 seconds\nredis    │ 15249:M 03 Oct 21:21:13.045 * Ready to accept connections\n…\n``` \n\nFor a detailed description of all prox commands and flags refer to the output\nof `prox help`.\n\n### Advanced Proxfile usage\n\nInstead of using a standard `Procfile` and `.env` file you can combine both in a\n`Proxfile`. Additionally this gives you access to more features such as custom\ncoloring of structured log output.\n\n```bash\n$ cat Proxfile\nversion: 1 # The Proxfile file format is versioned\n\n# Internally the Proxfile is parsed as YAML.\n# You can use comments, empty lines are ignored as well.\n\nprocesses:\n  redis: redis-server # Like the Procfile you specify processes as \"name: shell script\"\n\n  foo-service:\n    script: foo-service --debug -a -b 42\n    env:\n      - \"CONFIG_DIR=$PWD/config foo-serve\"\n\n  echo:\n    script: \"echo $LISTEN_ADDR\"\n    env:\n      - \"LISTEN_ADDR=localhost:1232\"\n\n  example-3:\n    script: my-app\n    tags:\n      errors:\n        color: red\n        condition:\n          field: level\n          value: \"/error|fatal/i\"\n```\n\n## Similar Projects\n\n- [foreman][foreman]: the original process runner by [David Dollar][foreman-blog]\n- [forego][forego]: a 1-1 port of foreman to Go\n- [goreman][goreman]: another clone of foreman with some undocumented RPC functionality via TCP ports (Go)\n- [honcho][honcho]: a Python port of foreman\n- [spm][spm]: Simple Process Manager with client/server communication via unix sockets (Go)\n- [overmind][overmind]: a process manager for Procfile-based applications that relies on tmux sessions\n- [and more …][more-similar]\n\n## Dependencies\n\nProx uses [go mod][go-mod] as dependency management tool. All vendored dependencies\nare specified in the [go.mod](go.mod) file and their licenses are copied into\n[LICENSE-THIRD-PARTY](LICENSE-THIRD-PARTY). Prox itself mainly relies on the Go\nstandard library, [zap][zap] for logging, [cobra/viper][cobra] for the CLI and\n[pkg/errors][pkg-errors] for error wrapping as well as [hashicorp/go-multierror][multi-errors].\n\n## License\n\nProx is licensed under the BSD 2-clause License. Please see the [LICENSE](LICENSE)\nfile for details. The individual licenses of the vendored dependencies can be\nfound in the [LICENSE-THIRD-PARTY](LICENSE-THIRD-PARTY) file.\n\n## Contributing\n\nContributions are always welcome (use pull requests). Before you start working on\na bigger feature its always best to discuss ideas in a new github issue. For each\npull request make sure that you covered your changes and additions with unit tests.\n\nPlease keep in mind that I might not always be able to respond immediately but I\nusually try to react within a week or two ☺.\n\n[foreman]: https://github.com/ddollar/foreman\n[forego]: https://github.com/ddollar/forego\n[honcho]: https://github.com/nickstenning/honcho\n[goreman]: https://github.com/mattn/goreman\n[spm]: https://github.com/bytegust/spm\n[overmind]: https://github.com/DarthSim/overmind\n[releases]: https://github.com/fgrosse/prox/releases\n[foreman-blog]: http://blog.daviddollar.org/2011/05/06/introducing-foreman.html\n[more-similar]: https://github.com/ddollar/foreman#ports\n[go-mod]: https://github.com/golang/go/wiki/Modules\n[zap]: https://godoc.org/go.uber.org/zap\n[cobra]: https://github.com/spf13/cobra\n[pkg-errors]: https://github.com/pkg/errors\n[multi-errors]: https://github.com/hashicorp/go-multierror\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgrosse%2Fprox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffgrosse%2Fprox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgrosse%2Fprox/lists"}