{"id":38452108,"url":"https://github.com/bolt-observer/agent","last_synced_at":"2026-01-17T04:49:01.543Z","repository":{"id":62530183,"uuid":"525713658","full_name":"bolt-observer/agent","owner":"bolt-observer","description":"bolt-agent enables you to automate your node management through our bolt.observer platform","archived":false,"fork":false,"pushed_at":"2023-09-12T17:07:08.000Z","size":2026,"stargazers_count":14,"open_issues_count":4,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-06-21T00:17:43.088Z","etag":null,"topics":["alerting","channel","lightning","lightning-network"],"latest_commit_sha":null,"homepage":"","language":"Go","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/bolt-observer.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-17T09:00:57.000Z","updated_at":"2024-04-28T02:29:34.000Z","dependencies_parsed_at":"2024-06-20T23:28:40.293Z","dependency_job_id":null,"html_url":"https://github.com/bolt-observer/agent","commit_stats":null,"previous_names":[],"tags_count":76,"template":false,"template_full_name":null,"purl":"pkg:github/bolt-observer/agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolt-observer%2Fagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolt-observer%2Fagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolt-observer%2Fagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolt-observer%2Fagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bolt-observer","download_url":"https://codeload.github.com/bolt-observer/agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolt-observer%2Fagent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28496579,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T04:31:57.058Z","status":"ssl_error","status_checked_at":"2026-01-17T04:31:45.816Z","response_time":85,"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":["alerting","channel","lightning","lightning-network"],"created_at":"2026-01-17T04:49:00.955Z","updated_at":"2026-01-17T04:49:01.533Z","avatar_url":"https://github.com/bolt-observer.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent\n\nBolt-agent is a tool for workflow based node management automation through [bolt.observer](https://bolt.observer) platform.\n\n## Contents:\n\n### bolt-agent\n\nutility to monitor and manage lightning node\n\nThe usage should be pretty self explanatory:\n\n```\nNAME:\n   bolt-agent - Utility to monitor and manage lightning node\n\nUSAGE:\n   bolt-agent [global options] command [command options] [arguments...]\n\nVERSION:\n   v0.2.2\n\nCOMMANDS:\n   help, h  Shows a list of commands or help for one command\n\nGLOBAL OPTIONS:\n   --allowedentropy value      allowed entropy in bits for channel balances (default: 64)\n   --apikey value              api key\n   --channel-whitelist value   path to file containing a whitelist of channels\n   --interval value            interval to poll - 10s, 1m, 10m or 1h (default: \"10s\")\n   --lnddir value              path to lnd's base directory (default: \"/home/user/.lnd\")\n   --macaroonpath value        path to macaroon file\n   --private                   report private data as well (default: false)\n   --preferipv4                if you have the choice between IPv6 and IPv4 prefer IPv4 (default: false)\n   --rpcserver value           host:port of ln daemon (default: \"localhost:10009\")\n   --tlscertpath value         path to TLS certificate (default: \"/home/user/.lnd/tls.cert\")\n   --channel-whitelist value   path to file containing a whitelist of channels\n   --verbosity value           log level for V logs (default: 0)\n   --help, -h                  show help\n   --version, -v               print the version\n\nADVANCED OPTIONS:\n   --datastore-url             datastore URL (default: agent-api.bolt.observer:443)\n   --ignorecln                 ignore CLN socket (default: false)\n   --keepalive value           keepalive interval (if nothing changed after this time an empty message will be sent) (default: \"60s\")\n   --public value              used together with --channel-whitelist (default: false)\n   --url value                 report url (default: \"https://ingress.bolt.observer/api/node-data-report/\")\n   --userest                   use REST API when true instead of gRPC (default: false)\n   --fetch-invoices            fetch invoices (default: 0)\n   --fetch-forwards            fetch forwards (default: 0)\n   --fetch-payments            fetch payments (default: 0)\n   --noplugins                 disable plugins (default: false)\n\nGLOG OPTIONS (described in https://github.com/google/glog#setting-flags):\n   --verbosity (instead of -v)\n   --logtostderr\n   --stderrthreshold\n   --alsologtostderr\n   --vmodule\n   --log_dir\n   --log_backtrace_at\n```\n\nAgent works with LND and CoreLightning and tries the best to have sane defaults so you can just start it up on your node without further hassle.\n\nExample:\n```\nbolt-agent --apikey key\n```\n\nOnly thing that is mandatory is the apikey which can also be provided through `API_KEY` environment variable:\n```\nexport API_KEY=changeme\nbolt-agent\n```\n\nAgent is using `glog` library for logging which needs writable `/tmp` (use `--logtostderr` to prevent writing to filesystem).\n\nFlag `--private` means whether you want to report data for private (\"unannounced\") channels too (when true). The default is false.\nThere is an advanced option of filtering what channels exactly are reported documented in \"Filtering on agent side\" section.\n\nFor more information about what exactly is reported read [DATA.md](./DATA.md).\n\n#### Advanced options\n\nIf you have a custom LND directory (`/storage` in the example) you might need:\n\n```\nbolt-agent --lnddir /storage/lnd/ --tlscertpath /storage/lnd/data/secrets/lnd.cert\n```\n\nbut that should be it.\n\nBy default it will try to communicate with LND using local gRPC connection and `readonly.macaroon`.\n\nYou can use `--userest` to start using REST API - in that case `--rpcserver` can be complete URL to the endpoint.\n\n```\nbolt-agent --userest --rpcserver https://bolt.observer/endpoint\n```\n\nFor CoreLightning it will use UNIX domain socket. By default agent will try to use `~/.lightning/bitcoin/lightning-rpc`.\nIf that file exists program will default to CoreLightning so if have LND installed on the node too and do not want to use CLN there is a flag\n`--ignorecln`. You can manually override name of UNIX domain socket using `--rpcserver` flag.\nExample:\n\n```\nbolt-agent --rpcserver /storage/cln/socket\n```\n\nMake sure agent is running with correct permissions to access the socket.\n\nThere is support for remote connections via commando plugin but you cannot use that option via command-line flags at the moment. We suggest to use\n`socat` utility if you wish to monitor a remote CLN node.\n\n## Install\n\nWe provide a standalone statically compiled binary. The targets are `linux` (amd64 build for GNU/Linux), `rasp` (aarch64 build for GNU/Linux) suitable for installation on your Raspberry PI and `darwin` (amd64 build for MacOS).\nIf you need some different architecture that is no problem except that you will have to build the binaries yourself (so you will need to install Golang). You can also open an issue / pull request to extend the defaults (or provide better naming).\n\n\n### Script\n\nYou can run:\n```\ncurl https://bolt.observer/agent | sh\n```\nto install the latest version of agent.\n\nThe executed script is present [here](./install.sh) so you can first check what it does. Or you can also do a manual installation.\n\n### Nix\n\nIf you have [Nix](https://nixos.org/) with [flake support](https://nixos.wiki/wiki/Flakes) you can do:\n```\nnix profile install 'github:bolt-observer/agent'\n```\n\n### Manual installation steps\n\nScript will execute same steps that you can invoke manually:\n\n* fetch latest revision from https://github.com/bolt-observer/agent/releases\n\n```\nwget https://github.com/bolt-observer/agent/releases/download/v0.2.2/bolt-agent-v0.2.2-linux.zip https://github.com/bolt-observer/agent/releases/download/v0.2.2/manifest-v0.2.2.txt.asc https://github.com/bolt-observer/agent/releases/download/v0.2.2/manifest-v0.2.2.txt\n```\n\n* verify integrity\n\n```\nwget -qO- https://raw.githubusercontent.com/bolt-observer/agent/main/scripts/keys/developers.asc | gpg --import\ngpg --verify manifest-v0.2.2.txt.asc manifest-v0.2.2.txt\n```\n\nand you should see:\n```\ngpg:                using RSA key F4B8B3B59C1E5AA39A1B9636E897355718E1DBF4\ngpg: Good signature from \"Gregor Pogacnik \u003cgregor@bolt.observer\u003e\" [ultimate]\n```\n\nor\n\n```\ngpg:                using RSA key 04AC8A162C036B650A271A6360886AC6567069C5\ngpg: Good signature from \"bolt \u003ctomaz@bolt.observer\u003e\" [ultimate]\n```\n\n* unpack the compressed binary\n\n```\nunzip bolt-agent-v0.2.2-linux.zip\n```\n\n* copy the binary to a common place\n\n```\ncp bolt-agent-v0.2.2-linux /usr/local/bin/bolt-agent\n```\n\n* start the binary\n\n```\nbolt-agent -apikey changeme\n```\n\n* you may want to run the agent as a systemd service (we have a simple systemd template [here](./bolt-agent.service))\n\nYou need to do that only once:\n\n```\nwget https://raw.githubusercontent.com/bolt-observer/agent/main/bolt-agent.service\ncp bolt-agent.service /etc/systemd/system/bolt-agent.service\n$EDITOR /etc/systemd/system/bolt-agent.service # to change API_KEY\nsystemctl daemon-reload\nsystemctl enable bolt-agent\nsystemctl start bolt-agent\n```\n\n## Docker\n\nYou can use the docker image from GitHub:\n\nUsage:\n\n```\ndocker run -v /tmp:/tmp -e API_KEY=changeme ghcr.io/bolt-observer/agent:v0.2.2\n```\n\n## Filtering on agent side\n\nYou can limit what channnels are reported using `--channel-whitelist` option. It specifies a local file path to be used as a whitelist of what channels to report.\nChannel IDs are short channel identifiers in LND format (a valid id is `792080480214450176` but not `720393x2228x0`)\nWhen adding `--private` to `--channel-whitelist` this means every private channel AND whatever is listed in the file. There is also `--public` to allow all public channels.\nUsing the options without `--channel-whitelist` makes no sense since by default all public channels are reported however it has to be explicit with `--channel-whitelist` in order\nto automatically allow all public channels (beside what is allowed through the file).\nIf you set `--private` and `--public` then no matter what you add to the `--channel-whitelist` file everything will be reported.\n\nThe file looks like this:\n\n```\n# Comments start with a # character\n# You can list pubkeys for example:\n0288037d3f0bdcfb240402b43b80cdc32e41528b3e2ebe05884aff507d71fca71a # bolt.observer\n# which means any channel where peer pubkey is this\n# or you can specify a specific short channel id e.g.,\n759930760125546497\n# too, invalid lines like\nwhatever\n# will be ignored (and logged as a warning, aliases also don't work!)\n# Validity for channel id is not checked (it just has to be numeric), thus:\n1337\n# is perfectly valid (altho it won't match and thus allow the reporting of\n# any additional channel).\n# Empty files means nothing - in whitelist context: do not report anything.\n```\n\n## Components\n\nInternally we use:\n* [nodedata](./nodedata): an abstraction for running the periodic checks and reporting balance related changes\n* [filter](./filter): this is used to filter specific channels on the agent side\n* [checkermonitoring](./checkermonitoring): is used for reporting metrics via Graphite (not used directly in bolt-agent here)\n* [lightning](./lightning): an abstraction around lightning node API (that furthermore heavily depends on common code from [lnd](https://github.com/lightningnetwork/lnd))\n* [lnsocket](./lnsocket): a way to establish a commando connection with CLN nodes\n* [agent](./agent): is the GRPC client for reporting payment data\n* [actions](./actions): is the GRPC client for getting what actios to invoke\n* [raw](./raw): is the connection between [agent](./agent) API and [lightning](./lightning) API\n* [plugins](./plugins): contains the plugins\n\nYou might want to read about [boltz plugin](./plugins/boltz/README.md).\n\n## Dependencies\n\nThis code depends on some [common code](https://github.com/bolt-observer/go_common).\n\n## Documentation\n\nRead complete documentation on: [https://docs.bolt.observer](https://docs.bolt.observer).\n\n## Troubleshooting\n\nDo:\n```\ngo get -v github.com/lightningnetwork/lnd@v0.15.4-beta\n```\nor else you get an ancient version and everything breaks (should be good due to go.mod/sums now).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbolt-observer%2Fagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbolt-observer%2Fagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbolt-observer%2Fagent/lists"}