{"id":31803737,"url":"https://github.com/agora-org/agora","last_synced_at":"2025-10-11T01:22:20.149Z","repository":{"id":36981287,"uuid":"360669018","full_name":"agora-org/agora","owner":"agora-org","description":"File server that accepts Lightning Network payments for downloads","archived":false,"fork":false,"pushed_at":"2022-09-28T00:02:28.000Z","size":392,"stargazers_count":193,"open_issues_count":51,"forks_count":23,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-10-04T01:35:48.860Z","etag":null,"topics":["bitcoin","lightning-network","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agora-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-04-22T20:08:10.000Z","updated_at":"2025-09-12T21:58:36.000Z","dependencies_parsed_at":"2022-06-29T02:31:16.009Z","dependency_job_id":null,"html_url":"https://github.com/agora-org/agora","commit_stats":null,"previous_names":["soenkehahn/agora"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/agora-org/agora","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agora-org%2Fagora","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agora-org%2Fagora/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agora-org%2Fagora/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agora-org%2Fagora/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agora-org","download_url":"https://codeload.github.com/agora-org/agora/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agora-org%2Fagora/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002634,"owners_count":26083425,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"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":["bitcoin","lightning-network","rust"],"created_at":"2025-10-11T01:22:14.395Z","updated_at":"2025-10-11T01:22:18.517Z","avatar_url":"https://github.com/agora-org.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eAgora\u003c/h1\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://crates.io/crates/agora\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/agora.svg?logo=rust\" alt=\"crate\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/agora-org/agora/actions\"\u003e\u003cimg src=\"https://github.com/agora-org/agora/workflows/Build/badge.svg\" alt=\"build\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://t.me/agoradiscussion\"\u003e\u003cimg src=\"https://img.shields.io/static/v1?label=chat\u0026message=Telegram\u0026color=blue\u0026logo=telegram\" alt=\"chat on telegram\"/\u003e\u003c/a\u003e\n\u003c/div\u003e\n\u003cbr /\u003e\n\n`agora` serves the contents of a local directory, providing file listings and downloads over HTTP.\nFor example, you can point it at a directory full of PDFs, allowing users to browse and view the PDFs in their web browser.\nIf `agora` is connected to an [LND](https://github.com/lightningnetwork/lnd) node, it can be configured to require [Lightning Network](https://en.wikipedia.org/wiki/Lightning_Network) payments for downloads.\n\nPublic Agora instances:\n\n- [233uki7qcwiban2uvgzapsosajjx6qrv7xizmf77prh7p56n5zmlz3ad.onion](http://233uki7qcwiban2uvgzapsosajjx6qrv7xizmf77prh7p56n5zmlz3ad.onion): [@yzernik's](https://github.com/yzernik) instance, accessible over Tor\n- [Modulo Network mining spreadsheets](https://modulo.network). [Direct link to Agora instance.](http://jzqqbzci3b2jlnvvkuxp2gmfh7if5443ite3ho7wy3phnq7tz4tspbid.onion/files/).\n- A static snapshot of our decommissioned test instance is available [here](https://agora-org.github.io/agora/).\n- Open an issue or submit a PR if you run an Agora instance and would like it to appear in this readme!\n\nAgora is free software developed by [@casey](https://github.com/casey/)\nand [@soenkehahn](https://github.com/soenkehahn/).\n\n## Support, Feedback, and Discussion\n\nIf you have a question, want to request a feature, or find a bug, please feel free to [open an issue](https://github.com/agora-org/agora/issues/new) or [join our Telegram group](https://t.me/agoradiscussion).\n\nThe developers, Casey and Sönke, can also be reached [via email](mailto:casey@rodarmor.com,soenkehahn@gmail.com?subject=Agora).\n\n## Running\n\n```bash\n$ mkdir files\n$ echo 'amazing content' \u003e files/file.txt\n$ agora --directory files --http-port 1234\n$ curl http://localhost:1234/files/file.txt\n```\n\nSee `agora --help` for more configuration options.\n\n## Installation\n\nPre-built binaries for Linux, MacOS, and Windows can be found on [the releases page](https://github.com/soenkehahn/agora/releases).\n\n## Building from Source\n\n`agora` is written in [Rust](https://www.rust-lang.org/) and built with `cargo`.\nYou can install Rust with [rustup](https://rustup.rs/).\n\nInside the checked out repository, running `cargo build --release` will build `agora` and copy the binary to `./target/release/agora`.\n\nFrom within the repository, you can also run, e.g., `cargo install --locked --path . --root /usr/local`, which will copy `agora` to `/usr/local/bin/agora`.\n\n## Running with Docker\n\nThe `agora` Docker image can be pulled from [ghcr](/../../pkgs/container/agora).\n\n\n### Building Agora Docker Image\n\nThe Docker image can also be built directly from within the repository.\n\nBuilding the image:\n```bash\ndocker build --tag agora:latest .\n```\n\n### Running Agora in Docker\n\nThe Docker image can used to serve files from your host machine, and connect to your existing LND node.\n\nTo run `agora` with a local directory `~/my-files`:\n```bash\ndocker run \\\n  --network=\"host\" \\\n  -e FILES_DIR=/files \\\n  -e AGORA_PORT=8080 \\\n  -v ~/my-files:/files \\\n  agora:latest\n```\n\nTo run `agora` with a Lightning instance connected (assuming that LND RPC is running on `localhost` and port `10009` and the data dir is located in `~/.lnd`).\n```bash\ndocker run \\\n  --network=\"host\" \\\n  -e FILES_DIR=/files \\\n  -e AGORA_PORT=8080 \\\n  -e LND_RPC_AUTHORITY=localhost:10009 \\\n  -e TLS_CERT_PATH=/.lnd/tls.cert \\\n  -e INVOICES_MACAROON_PATH=/.lnd/data/chain/bitcoin/testnet/invoice.macaroon \\\n  -v ~/my-files:/files \\\n  -v ~/.lnd:/.lnd \\\n  agora:latest\n```\n\n## Releases Notifications\n\nTo receive release notifications on GitHub, you can watch this repository with [custom notification settings](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository).\n\nAdditionally, an [RSS](https://en.wikipedia.org/wiki/RSS) feed of `agora` releases is published [here](https://github.com/agora-org/agora/releases.atom).\n\n## Deployment\n\nThe `agora` binary contains its static assets, so it can be copied and run from anywhere on the filesystem.\nBy default `cargo` links to system libraries dynamically.\nYou can avoid this by using the `x86_64-unknown-linux-musl` target: `cargo build --target=x86_64-unknown-linux-musl --release`.\nThis produces a statically linked binary that runs on, e.g., Alpine and CentOS Linux.\n\n### Configuration\n\nYou can configure the network port and address `agora` listens on, and the directory it serves.\nSee `agora --help` for details.\n\n### HTTPS Configuration\n\nIf you're running `agora` on a public domain it can be configured to automatically request TLS certificates for HTTPS from [Let's Encrypt](https://letsencrypt.org/) via the [ACME](https://datatracker.ietf.org/doc/html/rfc8555) protocol.\nSee the `--acme-*` and `--https-*` flags in `agora --help` for details.\n\n### LND Configuration\n\nBy default `agora` serves files for free.\nTo charge for downloads, `agora` must be connected to an [LND](https://github.com/lightningnetwork/lnd) instance.\nThere are multiple command line flags to configure this connection, see `agora --help` for details.\n\nTo configure which files are free and which are paid, see [Access Configuration](#access-configuration) below.\n\n### Access Configuration\n\nYou can put a `.agora.yaml` configuration file into directories served by `agora` to configure access to files in that directory.\n\nAn example configuration is:\n\n```yaml\n# whether or not to charge for files\npaid: true\n# price for files in satoshis\nbase-price: 1000 sat\n```\n\nAccess configuration applies recursively to files in subdirectories.\nFor example you can put this configuration in your base directory:\n\n```yaml\npaid: false\nbase-price: 500 sat\n```\n\nThen in some subdirectories you can charge for file downloads by creating an `subdir/.agora.yaml` like this:\n\n```yaml\npaid: true\n```\n\nThe default configuration is:\n\n```yaml\npaid: false\n# `base-price` does not have a default. Setting `paid` to `true`\n# while not having a `base-price` causes an error.\nbase-price: null\n```\n\n### Custom Index Pages\n\n`agora` serves directory file listings.\nIf a `.index.md` file is present in a directory, `agora` will render the contained Markdown as HTML and include it with the file listing. `agora` expects Commonmark Markdown, extended with footnotes, [strikethrough](https://github.github.com/gfm/#strikethrough-extension-), [tables](https://github.github.com/gfm/#tables-extension-), and [task lists](https://github.github.com/gfm/#task-list-items-extension-).\n\n## Buying Files from an Agora Instance\n\nYou can navigate to any Agora instance and browse the hosted files.\nAgora instances can host a mix of free and paid files.\nFor paid files, Agora will present you a Lightning Network invoice\nthat you must pay before downloading the file.\nThese invoices can be paid with a Lightning Network wallet.\nPopular wallets include:\n\n- [Wallet of Satoshi](https://www.walletofsatoshi.com/), a hosted wallet for Android and iOS.\n- [Strike](https://strike.me/), a hosted wallet for Android, iOS, and Google Chrome.\n- [Phoenix](https://phoenix.acinq.co/), a self-custodial wallet for iOS and Android.\n- [Breez](https://breez.technology/), a self-custodial wallet for iOS and Android.\n- [River Financial](https://river.com/), a Bitcoin financial services platform with the ability to buy and sell bitcoin for USD, and make and receive Lightning Payments, for the web, iOS, and Android.\n\n## Selling Files with Agora\n\nAgora is not a hosted platform.\nIf you want to sell files through it, you'll have to host your own Agora instance.\nAgora instances require access to an [LND](https://github.com/lightningnetwork/lnd) instance\nto create invoices and query their payment status.\nLND in turn needs access to a bitcoin node\n-- e.g. [`bitcoind`](https://github.com/bitcoin/bitcoin/) --\nto query the state of the bitcoin blockchain.\n\n### Setting up `bitcoind` and LND\n\nSetting up `bitcoind` and LND is a complex topic, and many different approaches are possible.\nAn excellent guide to setting up LND on Linux is available [here](https://stopanddecrypt.medium.com/a-complete-beginners-guide-to-installing-a-lightning-node-on-linux-2021-edition-ece227cfc35d),\nand a companion guide to setting up `bitcoind`,\nto supply the Lightning Network node with information about the blockchain,\nis [here](https://stopanddecrypt.medium.com/a-complete-beginners-guide-to-installing-a-bitcoin-full-node-on-linux-2021-edition-46bf20fbe8ff).\n\n### Processing Payments with Agora\n\nIn order to process payments, Agora needs to be connected to an LND instance.\nSee the `--lnd-*` flags in `agora --help`.\n\nAdditionally, LND nodes can only receive payments if they have sufficient _inbound liquidity_.\n\n#### Inbound Liquidity\n\nLiquidity management is one of the most complicated aspects of the Lightning Network, and certainly one of the most counter-intuitive.\n\nThe basic primitive that makes up the Lightning Network is the \"payment channel\", commonly referred to as just a \"channel\".\nA channel is between two Lightning Network nodes, has a fixed capacity, is opened by making a on-chain Bitcoin transaction, and is closed by making an on-chain Bitcoin transaction.\n\nWhile the channel is open, the two parties to the channel can make payments between themselves, but do not have to publish a Bitcoin transaction for each one of these payments.\nThey only have to publish a Bitcoin transaction when they want to close the channel, which nets-out the intermediate transactions made since it was opened.\n\nAs a concrete example, let's say Alice and Bob open a channel, with Alice contributing 1 BTC when the channel is opened, and Bob contributing 0 BTC. Initially, their balances on the channel are:\n\n    Alice: 1 BTC\n    Bob:   0 BTC\n\nIn this state, Alice can send a 0.1 BTC payment to Bob, and the channel balances will be:\n\n    Alice: 0.9 BTC\n    Bob:   0.1 BTC\n\nAlice and Bob can send each other money, but only up to the amount that they have on their side of the channel.\nAt this point, Alice can send Bob up to 0.9 BTC, and Bob can send Alice up to 0.1 BTC.\n\nHowever, at the very beginning, when Bob's balance was 0 BTC, Alice could not have received any money from Bob.\nDue to a lack of inbound liquidity, which is, quite simply, money on the other side of a channel, which can be sent to you.\n\nThis is an aspect of the Lightning Network that is very different from other payment systems, and from on-chain Bitcoin payments.\nYou must arrange to have sufficient inbound liquidity to receive payments.\n\nA question you might ask is, _What if I just want to assume that the customer is good for the money and queue it up myself for settlement once I have the liquidity to spare?_\n\nLet's imagine that we were in the initial state, Alice had 1 BTC in the channel, Bob 0 BTC, and Alice let Bob make a payment to her of 1 BTC. The new balance would be:\n\n    Alice:  2 BTC\n    Bob:   -1 BTC\n\nHowever! When a Lightning Network channel is closed, you divide up the funds from the funding transaction between the parties to the channel.\nThe channel was funded with an on-chain Bitcoin transaction of 1 BTC, so there is no way to pay out 2 BTC to Alice from the initial funding transaction.\nSince both parties to a payment channel can close the channel at any time, Alice would be trusting Bob to keep the channel open until he no longer had a negative balance.\nThis is not scalable or secure, and avoiding the need for trust is the whole purpose of the Lightning Network in the first place, otherwise we could all just trade unenforceable IOUs back and forth.\n\nInbound liquidity can be sourced in a number of ways, and [in-development proposals](https://github.com/lightningnetwork/lightning-rfc/pull/878) should make it even easier in the future.\nFor now, we recommend purchasing inbound liquidity from [Bitrefill](https://www.bitrefill.com/buy/lightning-channel/).\nBitrefill offers a service where a Lightning Node operator can pay Bitrefill to open a channel with that operator's Lightning Node.\nThe operator pays Bitrefill a small amount of bitcoin and receives a channel with a much greater amount of inbound liquidity in return.\n\n## Development\n\nYou can run the tests locally with `cargo test`.\nPull requests are tested on github actions, with the workflow defined in `.github/workflows/build.yaml`.\nYou can run approximately the same tests locally with `just all`.\n(See [just](https://github.com/casey/just).)\n\n## License\n\nAgora is licensed under [the CC0](https://choosealicense.com/licenses/cc0-1.0) with the exception of third-party components listed in [`ATTRIBUTION.md`](ATTRIBUTION.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagora-org%2Fagora","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagora-org%2Fagora","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagora-org%2Fagora/lists"}