{"id":26023756,"url":"https://github.com/pol-rivero/unix-js","last_synced_at":"2026-04-06T08:31:35.431Z","repository":{"id":210565880,"uuid":"720777899","full_name":"pol-rivero/unix-js","owner":"pol-rivero","description":"Drop your users into an enhanced replica of your own filesystem","archived":false,"fork":false,"pushed_at":"2024-11-20T07:33:07.000Z","size":325,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-26T04:49:08.916Z","etag":null,"topics":["linux","shell","terminal","unix"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/pol-rivero.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":"2023-11-19T15:18:19.000Z","updated_at":"2024-11-20T07:33:11.000Z","dependencies_parsed_at":"2024-01-18T08:39:12.356Z","dependency_job_id":"d1343cdd-e4c0-4d83-a82c-2130906a6311","html_url":"https://github.com/pol-rivero/unix-js","commit_stats":null,"previous_names":["p-rivero/unix-js","pol-rivero/unix-js"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pol-rivero/unix-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pol-rivero%2Funix-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pol-rivero%2Funix-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pol-rivero%2Funix-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pol-rivero%2Funix-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pol-rivero","download_url":"https://codeload.github.com/pol-rivero/unix-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pol-rivero%2Funix-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31464604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"online","status_checked_at":"2026-04-06T02:00:07.287Z","response_time":112,"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":["linux","shell","terminal","unix"],"created_at":"2025-03-06T11:32:18.964Z","updated_at":"2026-04-06T08:31:35.414Z","avatar_url":"https://github.com/pol-rivero.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# unix.js - A fake UNIX terminal\n\nunix.js is an easy-to-use framework for creating realistic terminal experiences and ARGs, anywhere JavaScript can run.\n\nIt's written entirely in TypeScript, and can be used in both Node.js and the browser. \n\n## How does it work?\n\nunix.js scans a directory/folder of your computer and generates a virtual filesystem from it. You can then drop your users into this alternate\nreality, and let them explore the filesystem and interact with it.\n\nExtending the functionality of unix.js is as easy as adding new files and subdirectories to the scanned directory.\nExecutable files are written in JavaScript, but to the user, they look like any other UNIX binary file.  \nFor example, you can define new terminal commands by creating files in the `/bin` directory of your virtual filesystem, or any other\npath you define as executable (`$PATH` variable in UNIX systems).\n\nScanning a directory is the recommended way to define the virtual filesystem because it's user-friendly and easy to understand, but you can also programmatically define it as a JS object if you prefer.\n\n## What's an ARG?\n\nARG stands for \"Alternate Reality Game\". It's a game that takes place in the real world, and uses real-world objects and events to tell a story.\n\nUNIX terminals are commonly used in ARGs to provide a hacker-like experience to the player. However, implementing a decent terminal is usually\nnot the main focus of the ARG writer, and so the terminal is often mediocre at best and can completely break the immersion.\n\n## Where are the virtual filesystem files stored?\n\nThe virtual filesystem is executed on the client side and is always stored in memory. This has the following implications:\n\n1. All changes are lost when the tab or app are closed. If there's demand for LocalStorage persistency, I will add it in the future.\n\n2. The virtual filesystem is limited by the amount of memory available to the browser. This is usually not a problem.\n\n3. The user can gain access to all files in the virtual filesystem, even those with an `accessType` of `hidden` or `locked`. If your users play by the rules or are not tech-savvy, this won't be a problem. However, if you want to ensure that the user cannot read a file until they have a password, you should do one of the following:\n\n    - Store the file in a server instead of the virtual filesystem.  \n    Create an executable in the filesystem that requests the password and sends it to the server. The server validates the password and sends back the file, and the executable then writes the file to the virtual filesystem.\n\n    - Encrypt the file and store it in the virtual filesystem. Create an executable in the filesystem that requests the password and decrypts the file.\n\nSee a demo of both methods [here](TODO). [TODO: add demo]\n\n\n## Why not call it *\"unix.ts\"*?\n\nSince this project is written in TypeScript, it would make sense to call it \"unix.ts\". However, \"ts\" can also stand for \"time stamp\", \nand UNIX timestamps are one of the most popular ways to represent time.  \nSince I wanted to avoid confusion and the \".js\" suffix is widely used to indicate JS/TS projects, I decided to call it \"unix.js\" instead.\n\n\n## Contributing\n\nDevelopment is done using [Bun](https://bun.sh/).\n\nThis monorepo contains the following packages:\n\n- `core`: The core library that implements the virtual filesystem and terminal.\n- `parser`: A parser for reading the user's directory and generating the virtual filesystem.\n\nFirst, go to the desired package and install the dependencies:\n\n```bash\ncd core\nbun install\n```\n\nAvailable commands:\n\n```bash\nbun run .\nbun lint\nbun test\nbun bundle\n```\n\n\n## Similar projects\n\nHere are some other fake terminals that I've found, and how they compare to unix.js:\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand\u003c/summary\u003e\n\n- unix.js\n  - The goal is to be a realistic UNIX experience, but full POSIX support is **not** a goal.\n  - Extensible (file-based or programmatically)\n  - Open source\n  - Typed with TypeScript\n  - Still in early development\n\n- [JS/UIX](https://www.masswerk.at/jsuix/)\n  - Very good UNIX clone (better than unix.js)\n  - Old project (from at least 2003)\n  - Not extensible\n  - Not open source\n  - Not typed (plain JavaScript)\n\n- [jquery.terminal](https://github.com/jcubic/jquery.terminal)\n  - Good terminal user experience\n  - Actively maintained\n  - Implements only the terminal functionality, not a UNIX filesystem\n  - Extensible by defining new commands (it's up to the developer to implement the logic)\n  - Open source\n  - Not typed (plain JavaScript)\n\n- [Terminal Temple](https://www.terminaltemple.com/)\n  - Acceptable UNIX clone (similar or slightly worse than unix.js)\n  - Recent project (from 2023)\n  - Not extensible\n  - Not open source\n  - Typed with TypeScript\n\n- [termly.js](https://simonecorsi.github.io/termly.js)\n  - Simple UNIX clone with a few commands and a rudimentary filesystem\n  - Not actively maintained (last commit from 2017, archived since 2021)\n  - Extensible (programatically)\n  - Open source\n  - Not typed (plain JavaScript)\n\n- [fake-linux-terminal](https://github.com/jcubic/fake-linux-terminal)\n  - Simple UNIX clone with a few commands and a rudimentary filesystem\n  - Not extensible\n  - Open source\n  - Not typed (plain JavaScript)\n\nIf you know of any other similar projects, please let me know by opening an issue or a pull request!\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpol-rivero%2Funix-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpol-rivero%2Funix-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpol-rivero%2Funix-js/lists"}