{"id":27185071,"url":"https://github.com/threefoldtech/mycelium","last_synced_at":"2025-07-17T17:40:20.925Z","repository":{"id":173644807,"uuid":"626346286","full_name":"threefoldtech/mycelium","owner":"threefoldtech","description":null,"archived":false,"fork":false,"pushed_at":"2023-12-01T14:59:25.000Z","size":788,"stargazers_count":1,"open_issues_count":13,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2023-12-01T16:32:53.538Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/threefoldtech.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}},"created_at":"2023-04-11T09:30:16.000Z","updated_at":"2024-02-28T11:40:28.021Z","dependencies_parsed_at":"2023-09-21T18:33:15.590Z","dependency_job_id":"c969445b-941b-4055-bc44-ad6dcff695c6","html_url":"https://github.com/threefoldtech/mycelium","commit_stats":null,"previous_names":["leesmet/masterproef_v2","leesmet/mycelium","threefoldtech/mycelium"],"tags_count":16,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Fmycelium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Fmycelium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Fmycelium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Fmycelium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/threefoldtech","download_url":"https://codeload.github.com/threefoldtech/mycelium/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248074976,"owners_count":21043490,"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","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":"2025-04-09T17:10:26.724Z","updated_at":"2025-07-17T17:40:20.868Z","avatar_url":"https://github.com/threefoldtech.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mycelium\n\nMycelium is an IPv6 overlay network written in Rust. Each node that joins the overlay\nnetwork will receive an overlay network IP in the 400::/7 range.\n\n## V0.5.x to V0.6.x upgrade\n\nWe are currently upgrading the public nodes to v0.6.x from the previous v0.5.x.\nTo make these transitions as smooth as possible, the hosted public nodes will be\nupgraded over a period of time. For this reason, the list of public nodes is split\ninto [a list of nodes running the latest version](#hosted-public-nodes-v06x),\nand [a list of nodes on the legacy version](#hosted-public-nodes-legacy). Users\nshould aim to upgrade their running nodes to the new version when possible.\n\n## Features\n\n- Mycelium, is locality aware, it will look for the shortest path between nodes\n- All traffic between the nodes is end-2-end encrypted\n- Traffic can be routed over nodes of friends, location aware\n- If a physical link goes down Mycelium will automatically reroute your traffic\n- The IP address is IPV6 and linked to private key\n- A simple reliable messagebus is implemented on top of Mycelium\n- Mycelium has multiple ways how to communicate quic, tcp, ... and we are working on holepunching for Quick which means P2P traffic without middlemen for NATted networks e.g. most homes\n- Scalability is very important for us, we tried many overlay networks before and got stuck on all of them, we are trying to design a network which scales to a planetary level\n- You can run mycelium without TUN and only use it as reliable message bus.\n\n\u003e We are looking for lots of testers to push the system\n\n\u003e [see here for docs](https://github.com/threefoldtech/mycelium/tree/master/docs)\n\n## Running\n\n\u003e Currently, Linux, macOS and Windows are supported.\n\n### Linux and macOS\n\nGet an useable binary, either by downloading [an artifact from a release](https://github.com/threefoldtech/mycelium/releases),\nor by [checking out and building the code yourself](#developing).\n\n### Windows\n\nDownload the [mycelium_installer.msi](https://github.com/threefoldtech/mycelium/releases/latest/download/mycelium_installer.msi) and run the installer.\n\n### Run Mycelium\n\nOnce you have an useable binary, simply start it. If you want to connect to other\nnodes, you can specify their listening address as part of the command (combined\nwith the protocol they are listening on, usually TCP). Check the next section if\nyou want to connect to hosted public nodes.\n\n```sh\nmycelium --peers tcp://188.40.132.242:9651 quic://185.69.166.8:9651\n\n#other example with other tun interface if utun3 (the default) would already be used\n#also here we use sudo e.g. on OSX\nsudo mycelium --peers tcp://188.40.132.242:9651 quic://185.69.166.8:9651 --tun-name utun9\n\n```\n\nBy default, the node will listen on port `9651`, though this can be overwritten\nwith the `-p` flag.\n\nTo check your own info\n\n```bash\nmycelium inspect --json\n{\n  \"publicKey\": \"abd16194646defe7ad2318a0f0a69eb2e3fe939c3b0b51cf0bb88bb8028ecd1d\",\n  \"address\": \"5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca\"\n}\n# test that network works, ping to anyone in the network\nping6 54b:83ab:6cb5:7b38:44ae:cd14:53f3:a907\n```\n\nThe node uses a `x25519` key pair from which its identity is derived. The private key of this key pair\nis saved in a local file (32 bytes in binary format). You can specify the path to this file with the\n`-k` flag. By default, the file is saved in the current working directory as `priv_key.bin`.\n\n### Running without TUN interface\n\nIt is possible to run the system without creating a TUN interface, by starting with the `--no-tun` flag.\nObviously, this means that your node won't be able to send or receive L3 traffic. There is no interface\nto send packets on, and consequently no interface to send received packets out of. From the point of\nother nodes, your node will simply drop all incoming L3 traffic destined for it. The node **will still\nroute traffic** as normal. It takes part in routing, exchanges route info, and forwards packets not\nintended for itself.\n\nThe node also still allows access to the [message subsystem](#message-system).\n\n## Configuration\n\nMycelium can be started with an **optional** configuration file using the `--config-file`\noption, which offers the same capabilities as the command line arguments.\n\nIf no configuration file is specified with `--config-file`, Mycelium will search for one\nin a default location based on the operating system:\n\n- Linux: $HOME/.config/mycelium.toml\n- Windows: %APPDATA%/ThreeFold Tech/Mycelium/mycelium.toml\n- Mac OS: $HOME/Library/Application Support/ThreeFold Tech/Mycelium/mycelium.toml\n\nCommand line arguments will override any settings found in the configuration file.\n\n## Hosted public nodes v0.6.x\n\nA couple of public nodes are provided, which can be freely connected to. This allows\nanyone to join the global network. These are hosted in 3 geographic regions, on both\nIPv4 and IPv6, and supporting both the Tcp and Quic protocols. The nodes are the\nfollowing:\n\n| Node ID | Region | IPv4 | IPv6 | Tcp port | Quic port | Mycelium IP |\n| ------- | ------- | -------------- | --------------------------------- | -------- | --------- | -------------------------------------- |\n| 04 | BE | 185.69.166.8 | 2a02:1802:5e:0:ec4:7aff:fe51:e36b | 9651 | 9651 | 549:8bce:fa45:e001:cbf8:f2e2:2da6:a67c |\n| 06 | FI | 65.109.18.113 | 2a01:4f9:5a:1042::2 | 9651 | 9651 | 488:74ac:8a31:277b:9683:c8e:e14f:79a7 |\n| 08 | US-WEST | 5.78.122.16 | 2a01:4ff:1f0:8859::1 | 9651 | 9651 | 4de:b695:3859:8234:d04c:5de6:8097:c27c |\n| 09 | SG | 5.223.43.251 | 2a01:4ff:2f0:3621::1 | 9651 | 9651 | 5eb:c711:f9ab:eb24:ff26:e392:a115:1c0e |\n| 10 | IND | 142.93.217.194 | 2400:6180:100:d0::841:2001 | 9651 | 9651 | 445:465:fe81:1e2b:5420:a029:6b0:9f61 |\n\nThese nodes are all interconnected, so 2 peers who each connect to a different node\n(or set of disjoint nodes) will still be able to reach each other. For optimal performance,\nit is recommended to connect to all of the above at once however. An example connection\nstring could be:\n\n`--peers tcp://188.40.132.242:9651 \"quic://[2a01:4f8:212:fa6::2]:9651\" tcp://185.69.166.7:9651 \"quic://[2a02:1802:5e:0:ec4:7aff:fe51:e36b]:9651\" tcp://65.21.231.58:9651 \"quic://[2a01:4f9:5a:1042::2]:9651\" \"tcp://[2604:a00:50:17b:9e6b:ff:fe1f:e054]:9651\" quic://5.78.122.16:9651 \"tcp://[2a01:4ff:2f0:3621::1]:9651\" quic://142.93.217.194:9651`\n\nIt is up to the user to decide which peers he wants to use, over which protocol.\nNote that quotation may or may not be required, depending on which shell is being\nused. IPv6 addresses should of course only be used if your ISP provides you with\nIPv6 connectivity.\n\n## Hosted public nodes legacy\n\nThese nodes are currently running v0.5.x. They can still be used but will be upgraded\nto the latest release in the (near) future. Users should update their local nodes\nas soon as possible.\n\n| Node ID | Region | IPv4 | IPv6 | Tcp port | Quic port | Mycelium IP |\n| ------- | ------- | --------------- | --------------------------------- | -------- | --------- | -------------------------------------- |\n| 01 | DE | 188.40.132.242 | 2a01:4f8:221:1e0b::2 | 9651 | 9651 | 54b:83ab:6cb5:7b38:44ae:cd14:53f3:a907 |\n| 02 | DE | 136.243.47.186 | 2a01:4f8:212:fa6::2 | 9651 | 9651 | 40a:152c:b85b:9646:5b71:d03a:eb27:2462 |\n| 03 | BE | 185.69.166.7 | 2a02:1802:5e:0:ec4:7aff:fe51:e80d | 9651 | 9651 | 597:a4ef:806:b09:6650:cbbf:1b68:cc94 |\n| 05 | FI | 65.21.231.58 | 2a01:4f9:6a:1dc5::2 | 9651 | 9651 | 410:2778:53bf:6f41:af28:1b60:d7c0:707a |\n| 07 | US-EAST | 209.159.146.190 | 2604:a00:50:17b:9e6b:ff:fe1f:e054 | 9651 | 9651 | 4ab:a385:5a4e:ef8f:92e0:1605:7cb6:24b2 |\n\n### Private network\n\nMycelium supports running a private network, in which you must know the network name\nand a PSK (pre shared key) to connect to nodes in the network. For more info, check\nout [the relevant docs](/docs/private_network.md).\n\n## API\n\nThe node starts an HTTP API, which by default listens on `localhost:8989`. A different\nlistening address can be specified on the CLI when starting the system through the\n`--api-addr` flag. The API allows access to [send and receive messages](#message-system),\nand will later be expanded to allow admin functionality on the system. Note that\nmessage are sent using the identity of the node, and a future admin API can be\nused to change the system behavior. As such, care should be taken that this API\nis not accessible to unauthorized users.\n\n## Message system\n\nA message system is provided which allows users to send a message, which is essentially just \"some data\"\nto a remote. Since the system is end-to-end encrypted, a receiver of a message is sure of the authenticity\nand confidentiality of the content. The system does not interpret the data in any way and handles it\nas an opaque block of bytes. Messages are sent with a deadline. This means the system continuously\ntries to send (part of) the message, until it either succeeds, or the deadline expires. This happens\nsimilar to the way TCP handles data. Messages are transmitted in chunks, which are embedded in the\nsame data stream used by L3 packets. As such, intermediate nodes can't distinguish between regular L3\nand message data.\nThe primary way to interact with the message system is through [the API](#api). The message API is\ndocumented in [an OpenAPI spec in the docs folder](docs/api.yaml). For some more info about how to\nuse the message system, see [the message docs](/docs/message.md).\n\nMessages can be categorized by topics, which can be configured with whitelisted subnets and socket forwarding paths.\nFor detailed information on how to configure topics, see the [Topic Configuration Guide](/docs/topic_configuration.md).\nuse the message system, see [the message docs](/docs/message.md).\n\n## Inspecting node keys\n\nUsing the `inspect` subcommand, you can view the address associated with a public key. If no public key is provided, the node will show\nits own public key. In either case, the derived address is also printed. You can specify the path to the private key with the `-k` flag.\nIf the file does not exist, a new private key will be generated. The optional `--json` flag can be used to print the information in json\nformat.\n\n```sh\nmycelium inspect a47c1d6f2a15b2c670d3a88fbe0aeb301ced12f7bcb4c8e3aa877b20f8559c02\nPublic key: a47c1d6f2a15b2c670d3a88fbe0aeb301ced12f7bcb4c8e3aa877b20f8559c02\nAddress: 47f:b2c5:a944:4dad:9cb1:da4:8bf7:7e65\n```\n\n```sh\nmycelium inspect --json\n{\n  \"publicKey\": \"955bf6bea5e1150fd8e270c12e5b2fc08f08f7c5f3799d10550096cc137d671b\",\n  \"address\": \"54f:b680:ba6e:7ced:355f:346f:d97b:eecb\"\n}\n```\n\n## Developing\n\nThis project is built in Rust, and you must have a rust compiler to build the code\nyourself. Please refer to [the official rust documentation](https://www.rust-lang.org/)\nfor information on how to install `rustc` and `cargo`. This project is a workspace,\nhowever the binaries (`myceliumd` and `myceliumd-private`) are explicitly _not_\npart of this workspace. The reason for this is the way the cargo resolver unifies\nfeatures. Making both binaries part of the workspace would make the library build\nfor the regular binary include the code for the private network, and since that\nis internal code it won't be removed at link time.\n\nFirst make sure you have cloned the repo\n\n```sh\ngit clone https://github.com/threefoldtech/mycelium.git\ncd mycelium\n```\n\nIf you only want to build the library, you can do so from the root of the repo\n\n```sh\ncargo build\n```\n\nIf you instead want to build a binary, that must be done from the appropriate subdirectory\n\n```sh\ncd myceliumd\ncargo build\n```\n\nRefer to the README files in those directories for more info.\n\nIn case a release build is required, the `--release` flag can be added to the cargo\ncommand (`cargo build --release`).\n\n## Cross compilation\n\nFor cross compilation, it is advised to use the [`cross`](https://github.com/cross-rs/cross)\nproject. Alternatively, the standard way of cross compiling in rust can be used\n(by specifying the `--target` flag in the `cargo build` command). This might require\nsetting some environment variables or local cargo config. On top of this, you should\nalso provide the `vendored-openssl` feature flag to build and statically link a copy\nof openssl.\n\n## Remarks\n\n- The overlay network uses some of the core principles of the Babel routing protocol (\u003chttps://www.irif.fr/~jch/software/babel/\u003e).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreefoldtech%2Fmycelium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthreefoldtech%2Fmycelium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreefoldtech%2Fmycelium/lists"}