placeholderOS-kernel (ALPHA)

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 aims to provide a kernel for the OS.

About

placeholderOS-kernel is being developed by APT SHOW INCORPORATED as an experimental platform for exploring security concepts and user management within ComputerCraft. The kernel manages the core functionality of the OS, including:

• 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: Designed for easy extension
• Kernel API: Programmatic access to kernel functions for GUI applications

Documentation

• Getting Started - Basic setup and usage guide
• API Reference - Complete function reference

Kernel API

The kernel provides a Lua API for programmatic access to core functions. This allows GUI applications and other programs to interact with the kernel directly.

Basic Usage

localkernel=require("src.kernel")
-- Start kernel with shell (default)kernel.run()
-- Start kernel without shell (GUI mode)kernel.run({no_shell=true})
-- Or using separate init and runkernel.init({no_shell=true})
kernel.run()

Boot Flags

The kernel.init() and kernel.run() functions accept an options table with boot flags:

• no_shell (boolean): Disable the default shell interface. When true, the kernel runs without the login/shell system, suitable for GUI applications.

-- Example: Start kernel in GUI modekernel.run({no_shell=true})

Process Management

-- Create a new processlocalpid=kernel.create_process(func, "process_name", "user", {"basic"})
-- Get process informationlocalproc=kernel.get_process(pid)
-- List all processeslocalprocesses=kernel.list_processes()
-- Kill a processkernel.kill_process(pid)
-- Suspend/resume processeskernel.suspend_process(pid)
kernel.resume_process(pid)

Scheduler Control

-- Start/stop the scheduler#placeholderOS-kernel (ALPHA)
[![License: AGPLv3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
![Version](https://img.shields.io/badge/version-1.0.0--alpha-red)
![Status](https://img.shields.io/badge/status-alpha-red)
>**NOTICE:**ThisprojectiscurrentlyinALPHA. Expectbugs, incompletefeatures, andsignificantchangesbetweenversions.
placeholderOSisacustomoperatingsystemdesignedfor [CC: Tweaked](https://tweaked.cc), thepopularMinecraftmodthataddsprogrammablecomputerstothegame. ThisprojectprovidesakernelfortheOS.
##AboutplaceholderOS-kernelisanexperimentalplatformforexploringsecurityconceptsandusermanagementwithinComputerCraft. ThekernelmanagescoreOSfunctionalityincludingauthentication, permissions, andprocessscheduling.
Keyfeatures:
-Multi-userauthenticationandpermissiongroups-Commandshellinterface-ModulararchitectureandaguardedKernelAPI##Projectlayout-`src/` — internalmodules (process, scheduler, perms, etc.)
-`src/api/` — public, guardedAPIsforprograms (e.g., `src/api/kernel.lua`)
-`docs/` — documentationForbackwardcompatibility, `require("src.kernel")` stillworks (itloadsashimthatforwardsto`src/api/kernel.lua`).
##ProtectedinternalmodulesBydefaulttheprojectnowprotectsallmodulesunder`src.*` frombeingrequiredbyunprivilegedprograms. TheonlyexceptionsarepublicAPIsunder`src.api.*` andthekernelshim`src.kernel`. Thisisenforcedby`src/api/secure_loader.lua` whichoverrides`require` atruntime.
Kernelcodeandprivilegedprocesses (admin/system/trusted) canstillrequireprotectedmodules. Tochangethepolicy, edit`src/api/secure_loader.lua` — youcanbroadenornarrowprotection, orswitchtoawhitelistapproachifdesired.
##Documentation- [GettingStarted](./docs/GETTING_STARTED.md)
- [APIReference](./docs/API_REFERENCE.md)
##KernelAPI (summary)
ThekernelprovidesaguardedLuaAPIforprogrammaticaccesstocorefunctions. APIconsumersshouldalwayshandleerrorsreturnedfromkernelwrapperfunctionsbecausepermissionchecksmayrejectoperations.
Basicusage:
```lualocalkernel=require("src.kernel") -- shim to src.api.kernel-- Start kernel with shell (default)kernel.run()
-- Start kernel without shell (GUI mode)kernel.run({no_shell=true})

Process management and scheduler control are available via the kernel API. Many operations require admin, system, or trusted permissions; see docs/API_REFERENCE.md for details.

GUI Support

The kernel supports GUI applications by running without the default shell (use kernel.run({no_shell = true})). GUI apps can create processes and interact with the kernel API but must respect permission restrictions.

Example GUI usage is shown in docs/GETTING_STARTED.md.

Current State

This project is in ALPHA; expect API changes. The kernel skeleton, login flow, and permission system are present and actively being improved.

License

This project is licensed under the GNU Affero General Public License v3.0.

Contact

Open an issue on this repository for questions or feature requests.