NOTICE: This project is currently in ALPHA. Expect bugs, incomplete features, and significant changes between versions.
placeholderOS is a custom operating system designed for CC: Tweaked, the popular Minecraft mod that adds programmable computers to the game. This project provides the core kernel for the OS.
placeholderOS-kernel is an experimental implementation platform for exploring security concepts, process management, and multi-user access control within ComputerCraft.
- Multi-user Authentication: Secure user accounts with permission levels.
- Permission Groups: Tiered access system (
guest,user,admin,trusted,system). - Command Shell Interface: Built-in, streamlined command processing.
- Modular Architecture: Public API layer separated from protected internal logic.
- Guarded Kernel API: Programmatic access for GUI applications with permission enforcement.
src/- Internal system modules (process manager, scheduler, permissions).src/api/- Public, guarded APIs for applications (e.g.,src/api/kernel.lua).docs/- Usage guides and complete documentation.
Note: For backward compatibility, require("src.kernel") works by pointing to src/api/kernel.lua via a shim.
By default, all internal modules under src.* are protected from being required by unprivileged programs. The only public entry points allowed for standard programs are APIs under src.api.* (and the src.kernel shim).
This protection is enforced at runtime by src/api/secure_loader.lua. Kernel code and privileged processes (admin, system, or trusted) can still access internal modules. You can customize this policy directly inside src/api/secure_loader.lua.
- Getting Started - Basic setup and application integration guide.
- API Reference - Detailed kernel API function reference.
The kernel provides a Lua API for programmatic interaction. When calling kernel functions, applications should check returned error codes, as permission checks may reject unauthorized operations.
local kernel = require("src.kernel")
-- Start kernel with default shell
kernel.run()
-- Start kernel without shell (GUI Mode)
kernel.run({ no_shell = true })
-- Alternative: Separate init and run execution
kernel.init({ no_shell = true })
kernel.run()
local kernel = require("src.kernel")
-- Create a new process
local pid = kernel.create_process(func, "process_name", "user", { "basic" })
-- Fetch process information
local proc = kernel.get_process(pid)
-- Process controls
kernel.suspend_process(pid)
kernel.resume_process(pid)
kernel.kill_process(pid)
-- List active processes
local processes = kernel.list_processes()
The kernel supports custom GUI shells and applications by running headlessly using the no_shell = true boot flag. GUI applications can spawn processes and utilize the Kernel API while operating within their user permission limits.
See docs/GETTING_STARTED.md for full GUI implementation examples.
This project is licensed under the GNU Affero General Public License v3.0.
For issues, bug reports, or feature requests, please open an issue in this repository.