{"id":45981237,"url":"https://github.com/headlesshq/headlessmc","last_synced_at":"2026-02-28T18:02:59.199Z","repository":{"id":38009381,"uuid":"480523771","full_name":"headlesshq/headlessmc","owner":"headlesshq","description":"Minecraft on the command line","archived":false,"fork":false,"pushed_at":"2025-12-16T17:06:02.000Z","size":3400,"stargazers_count":297,"open_issues_count":23,"forks_count":32,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-12-19T07:55:13.876Z","etag":null,"topics":["bytecode","cli","console","headless","launcher","lwjgl","minecraft","minecraft-console-client","minecraft-launcher"],"latest_commit_sha":null,"homepage":"https://headlesshq.github.io/headlessmc/","language":"Java","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/headlesshq.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-04-11T19:31:53.000Z","updated_at":"2025-12-16T13:08:17.000Z","dependencies_parsed_at":"2023-11-13T12:29:53.656Z","dependency_job_id":"a4391cd1-0ff8-4947-b8a9-3e81d74f0472","html_url":"https://github.com/headlesshq/headlessmc","commit_stats":null,"previous_names":["headlesshq/headlessmc"],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/headlesshq/headlessmc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headlesshq%2Fheadlessmc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headlesshq%2Fheadlessmc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headlesshq%2Fheadlessmc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headlesshq%2Fheadlessmc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/headlesshq","download_url":"https://codeload.github.com/headlesshq/headlessmc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headlesshq%2Fheadlessmc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29946463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T17:57:52.716Z","status":"ssl_error","status_checked_at":"2026-02-28T17:57:31.974Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["bytecode","cli","console","headless","launcher","lwjgl","minecraft","minecraft-console-client","minecraft-launcher"],"created_at":"2026-02-28T18:02:59.104Z","updated_at":"2026-02-28T18:02:59.186Z","avatar_url":"https://github.com/headlesshq.png","language":"Java","readme":"\u003c!--suppress HtmlDeprecatedAttribute --\u003e\n\u003cdiv align=\"right\"\u003e\n  \u003ca href=\"https://github.com/xiaofanforfabric/headlessmc\"\u003e中文\u003c/a\u003e | English\n\u003c/div\u003e\n\n\u003ch1 align=\"center\" style=\"font-weight: normal;\"\u003e\u003cb\u003eHeadlessMc\u003c/b\u003e\u003c/h1\u003e\n\u003cp align=\"center\"\u003eA command line launcher for Minecraft Java Edition.\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cimg src=\"headlessmc-web/page/logo.png\" alt=\"logo\" style=\"width:200px;\"\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003ca href=\"https://github.com/headlesshq/mc-runtime-test\"\u003eMc-Runtime-Test\u003c/a\u003e | HMC | \u003ca href=\"https://github.com/headlesshq/hmc-specifics\"\u003eHMC-Specifics\u003c/a\u003e | \u003ca href=\"https://github.com/headlesshq/hmc-optimizations\"\u003eHMC-Optimizations\u003c/a\u003e\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/6a86b3e62d3b47909de670b09737f8fd)](https://app.codacy.com/gh/headlesshq/headlessmc/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![GitHub All Releases](https://img.shields.io/github/downloads/headlesshq/HeadlessMc/total.svg)](https://github.com/headlesshq/HeadlessMc/releases)\n![](https://github.com/headlesshq/HeadlessMc/actions/workflows/gradle-publish.yml/badge.svg)\n![GitHub](https://img.shields.io/github/license/headlesshq/HeadlessMc)\n[![Docker Image Size](https://img.shields.io/docker/image-size/3arthqu4ke/headlessmc)](https://hub.docker.com/r/3arthqu4ke/headlessmc/)\n![Github last-commit](https://img.shields.io/github/last-commit/headlesshq/HeadlessMc)\n\n\u003c/div\u003e\n\n\u003e [!NOTE]\n\u003e We are currently working on HeadlessMc 3.0, which will revamp it completly (With Picocli etc.)!\n\u003e Progress can be tracked on the [v3](https://github.com/headlesshq/headlessmc/tree/v3) branch.\n\n\u003e [!WARNING]\n\u003e NOT AN OFFICIAL MINECRAFT PRODUCT. NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT.\n\u003e \n\u003e HeadlessMc will not allow you to play without having bought Minecraft! \n\u003e Accounts will always be validated.\n\u003e Offline accounts can only be used to run the game headlessly in CI/CD pipelines.\n\nHeadlessMc (HMC) allows you to launch Minecraft Java Edition from the command line.\nIt can manage clients, servers and mods.\nIt can run the client in headless mode, without a Screen, controlled by the command line.\nThis e.g. can allow you to test the game in your CI/CD pipeline with [mc-runtime-test](https://github.com/headlesshq/mc-runtime-test).\n\n\u003e [!TIP]  \n\u003e Read our new, beautiful documentation [here](https://headlesshq.github.io/headlessmc).\n\n## Quickstart\n\n1. Download the `headlessmc-launcher.jar` from the releases tab and install a Java version \u0026geq; 8.\n    - If you want additional features such as plugins and launching the game inside the same JVM, use the `headlessmc-launcher-wrapper.jar` instead.\n    - You do not need to install java if you download one of the GraalVM executables instead.\n2. Run the launcher with `java -jar headlessmc-launcher.jar` in your terminal.\n    - Or e.g. `./headlessmc-launcher-linux` if you use a GraalVM executable.\n3. HeadlessMc will generally not allow you to start the game without an account. \nLogin to your Minecraft account by executing the `login` command and follow the instructions.\n4. Launch the game with `launch \u003cmodloader\u003e:\u003cversion\u003e`, e.g. `launch fabric:1.21.4 -lwjgl`.\nThe `lwjgl` flag will make the game run in headless mode.\n\nRead [more](https://headlesshq.github.io/headlessmc/getting-started/).\n\n### HeadlessMc-Specifics\n\nThe [hmc-specifics](https://github.com/headlesshq/hmc-specifics) are mods\nthat you can place inside your .minecraft/mods folder.\nTogether with HeadlessMc they allow you to control the game via the command line, e.g.\nby sending chat messages and commands with `msg \"\u003cmessage\u003e\"`,\nvisualizing the menus displayed by Minecraft via `gui` and clicking through menus via `click`.\n\nRead [more](https://headlesshq.github.io/headlessmc/specifics/).\n\n### Docker \n\nA preconfigured [docker image](https://hub.docker.com/r/3arthqu4ke/headlessmc/) exists,\nwhich comes with Java 8, 17 and 21 installed.\nPull it via `docker pull 3arthqu4ke/headlessmc:latest`\nand run it with `docker run -it 3arthqu4ke/headlessmc:latest`.\nInside the container you can use the `hmc` command anywhere.\n\n### Android\n\nHeadlessMc can run inside Termux.\n* Download Termux from F-Droid, NOT from the PlayStore.\n* Install Java: `apt update \u0026\u0026 apt upgrade $ apt install openjdk-\u003cversion\u003e`\n* Download the headlessmc-launcher-wrapper.jar into Termux.\n* Disable JLine, as we could not get it to work on Termux for now,\n  by adding `hmc.jline.enabled=false` to the HeadlessMC/config.properties.\n* Now you can use HeadlessMc like you would on Desktop or Docker.\n\n### Web\n\nHeadlessMc can run inside the browser, kinda.\nFirst, there is CheerpJ, a WebAssembly JVM,\nbut it does not support all features we need to launch the game.\nThe CheerpJ instance can be tried out [here](https://headlesshq.github.io/headlessmc/).\nSecondly, there is [container2wasm](https://github.com/headlesshq/hmc-container2wasm),\nwhich can translate the HeadlessMc Docker container\nto WebAssembly and the run it inside the browser, but this is extremely slow.\n\n### Servers\n\nHeadlessMc also has support for Minecraft servers.\nIt can install and run Paper, Fabric, Vanilla, Purpur, Forge and Neoforge servers.\nInstrumentation for servers is currently not supported.\nUse the following commands:\n```\n\u003e server add paper 1.21.5\nAdded paper server: paper-1.21.5-54.\n\n\u003e server list\nid   type    version   name\n0    paper   1.21.5    paper-1.21.5-54\n\n\u003e server eula paper-1.21.5-54 -accept\n...\n\n\u003e server launch paper-1.21.5-54 --jvm \"-Xmx10G -XX:+UseG1GC \u003c...\u003e\"\n...\n```\n\n### Testing\n\nOne primary goal of HeadlessMc is to enable testing for both production servers and clients.\nFor this purpose it is used in the [mc-runtime-test](https://github.com/headlesshq/mc-runtime-test).\nIt also has a built-in command testing framework.\nIt can send commands to a running process and check the output.\nTests can be specified in a json format.\nAs an example, the workflow to test if **any** Minecraft server boots successfully:\n```json\n{\n  \"name\": \"Server Test\",\n  \"steps\": [\n    {\n      \"type\": \"ENDS_WITH\",\n      \"message\": \"For help, type \\\"help\\\"\"\n    },\n    {\n      \"type\": \"SEND\",\n      \"message\": \"stop\",\n      \"timeout\": 120\n    }\n  ]\n}\n```\nIt checks for a log message that ends with `For help, type \"help\"`, \nsomething all versions of the Minecraft server output upon successful launch.\nIt then stops the server by sending the stop command to it.\nYou can write your own test and even run it against the client instead of the server,\nprovided the client has command support, e.g. via the [hmc-specifics](https://github.com/headlesshq/hmc-specifics).\nJust specify the location of your test file in the config with the key\n`hmc.test.filename`.\nAn example CI workflow that tests if HeadlessMc can launch the game with the\nhmc-specifics can be found [here](.github/workflows/hmc-specifics-test.yml).\n\n### Optimizations \n\nHeadlessMc achieves headless mode by patching the LWJGL library: \nevery of its functions is rewritten to do nothing, or to return stub values\n(you can read more about this [here](headlessmc-lwjgl/README.md)).\nThis has the advantage of being independent of Minecraft versions,\nbut comes with some overhead.\nA Minecraft version dependent approach are the [hmc-optimizations](https://github.com/headlesshq/hmc-optimizations),\nanother set of mods which patch Minecraft itself to skip all rendering code.\nAdditionally HeadlessMc also comes with the `hmc.assets.dummy` property,\nwhich replaces all assets with small dummy textures and sounds,\nwhich allows for a smaller memory footprint and much less downloads before launch.\nYou can also achieve headless mode without patching lwjgl by running headlessmc with a virtual framebuffer like\n[Xvfb](https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml).\n\n### Configuring HeadlessMc\n\u003e [!NOTE]  \n\u003e All configuration options are listed [here](https://headlesshq.github.io/headlessmc/configuration/)\n\n- HeadlessMc stores its configuration in `HeadlessMC/config.properties`.\n- On Windows and Linux Java versions in certain folders get detected automatically\n  and HeadlessMc can download missing Java distributions.\n  But you can also specify which Java installations HeadlessMc can use to run the game.\n  Open the file `HeadlessMC/config.properties` and add a key called `hmc.java.versions`,\n  with a `;` seperated list of java versions HeadlessMc can use, like this:\n    ```properties\n    hmc.java.versions=C:/Program Files/Java/jre-\u003cversion\u003e/bin/java;C:/Program Files/Java/jdk-\u003cversion\u003e/bin/java\n    ```\n- Restart HeadlessMc or use `config -refresh` and then `java -refresh`, HeadlessMc should now know which Java versions to use.\n\nProperties can also be passed as SystemProperties from the command line.\nFor available properties see the [HmcProperties](headlessmc-api/src/main/java/io/github/headlesshq/headlessmc/api/config/HmcProperties.java), the\n[LauncherProperties](headlessmc-launcher/src/main/java/io/github/headlesshq/headlessmc/launcher/LauncherProperties.java), the\n[JLineProperties](headlessmc-jline/src/main/java/io/github/headlesshq/headlessmc/jline/JLineProperties.java), the\n[LoggingProperties](headlessmc-logging/src/main/java/io/github/headlesshq/headlessmc/logging/LoggingProperties.java), the\n[RuntimeProperties](headlessmc-runtime/src/main/java/io/github/headlesshq/headlessmc/runtime/RuntimeProperties.java) or the\n[LwjglProperties](headlessmc-lwjgl/src/main/java/io/github/headlesshq/headlessmc/lwjgl/LwjglProperties.java).\n\nYou can e.g. set `hmc.gamedir` to run the game inside another directory.\n\n### In-Memory launching and GraalVM\n\nWith the `-inmemory` flag HeadlessMc can even launch the game inside the same\nJVM that is running HeadlessMc itself.\nMaking it possible to really run Minecraft anywhere, where a JVM can run.\n\nThis is not possible on GraalVM.\nAdditionally, HeadlessMc's plugin system and instrumentation process\nare also difficult to realize in GraalVM.\n\nBut we provide GraalVM images, that are basically a launcher for HeadlessMc itself:\nThey find/download a suitable Java distribution and run HeadlessMc on it,\nwithout the user having to install Java.\n\n### A Note on command arguments\n\nArguments passed to commands have to be separated using spaces. If you want to pass an Argument which contains spaces\nyou need to escape it using quotation marks, like this:\n`\"argument with spaces\"`.\nQuotation marks and backslashes can be escaped by using a backslash.\nSo `msg \"A text with spaces\"` will send the chat message `A text with spaces`,\nwhile `msg \"\\\"A text with spaces\\\"\" additional space`\nwill send the chat message `\"A text with spaces\"` and the argument `additional space` will be dropped.\n\n## Building, Developing and Contributing\n\nSimply run `./gradlew build` or import the [build.gradle](build.gradle)\ninto an IDE of your choice, and you should be good to go.\n\nIn order to keep compatibility with older Java and Minecraft versions\nHeadlessMc uses Java language level 8. It can be\nbuilt with any JDK \u0026geq; 8, but language features \u003e 8 can't be used. \nHeadlessMc uses [project lombok](https://github.com/projectlombok/lombok)\nto eliminate Java boilerplate.\n\nThe (sparse) javadoc can be found [here](https://headlesshq.github.io/headlessmc/javadoc/).\n\nContributions are welcome!\n\n### Plugins\n\nYou can also write Plugins for HeadlessMc.\nPlugins can run through the `headlessmc-launcher-wrapper`,\nwhich launches the `headlessmc-launcher` on another classloader.\nYou can find a small example [here](headlessmc-launcher-wrapper/src/testPlugin).\n\n## License and Libraries\n\nSome cool libraries we use:\n\n*   [MinecraftAuth by RaphiMC](https://github.com/RaphiMC/MinecraftAuth)\n*   [Deencapsulation by xxDark](https://github.com/xxDark/deencapsulation)\n*   [Forge-CLI by TeamKun](https://github.com/TeamKun/ForgeCLI), which we [customized](https://github.com/3arthqu4ke/ForgeCLI).\n\nHeadlessMc is licensed under the [MIT License](LICENSE).\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheadlesshq%2Fheadlessmc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheadlesshq%2Fheadlessmc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheadlesshq%2Fheadlessmc/lists"}