{"id":25986950,"url":"https://github.com/okerew/osxiec","last_synced_at":"2025-03-05T12:37:43.109Z","repository":{"id":248118749,"uuid":"827811109","full_name":"Okerew/osxiec","owner":"Okerew","description":"Native Docker-like solution for macOS developed by Okerew. It has it own containers. It leverages native macOS features to provide containerization capabilities, albeit with some limitations compared to Docker.","archived":false,"fork":false,"pushed_at":"2025-03-04T18:07:37.000Z","size":450,"stargazers_count":28,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-04T18:35:33.483Z","etag":null,"topics":["alternative","apple","c","containers","darwin","darwin-containers","darwin-core","darwincontainers","docker","image-container","isolated","isolated-environments","isolated-worker","kubernetes","macos","macos-containers","macoscontainers","native","osx","solution"],"latest_commit_sha":null,"homepage":"https://osxiec.glitch.me","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Okerew.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":"2024-07-12T12:29:27.000Z","updated_at":"2025-03-04T17:48:57.000Z","dependencies_parsed_at":"2025-03-04T18:27:52.817Z","dependency_job_id":"bcf42822-8116-4a43-a4f1-c4596d162286","html_url":"https://github.com/Okerew/osxiec","commit_stats":null,"previous_names":["okerew/osxiec"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Okerew%2Fosxiec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Okerew%2Fosxiec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Okerew%2Fosxiec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Okerew%2Fosxiec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Okerew","download_url":"https://codeload.github.com/Okerew/osxiec/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242031298,"owners_count":20060579,"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":["alternative","apple","c","containers","darwin","darwin-containers","darwin-core","darwincontainers","docker","image-container","isolated","isolated-environments","isolated-worker","kubernetes","macos","macos-containers","macoscontainers","native","osx","solution"],"created_at":"2025-03-05T12:37:42.321Z","updated_at":"2025-03-05T12:37:43.088Z","avatar_url":"https://github.com/Okerew.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Osxiec\n\nOSXIEC is a native docker-like solution for macOS developed by Okerew. It leverages native macOS features to provide containerization capabilities, albeit with some limitations compared to Docker.\n\n\u003ca href=\"https://youtu.be/CkJT0STyIZE\" target=\"_blank\"\u003e\n \u003cimg src=\"https://github.com/user-attachments/assets/d45e77d8-9532-482f-b4f6-874a301f4916\" alt=\"Watch the video\" /\u003e\n\u003c/a\u003e\nIf it says that macOS can't identify if it is malware or not, close it go into settings and allow it to be executed.\n\n____\n\n\n## Dependencies\n**HomeBrew for installing dependencies**\n```sh\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n```\n**Curl**\n```sh\nbrew install curl\n```\n**Readline**\n```sh\nbrew install readline\n```\n\n**Json-c**\n```sh\nbrew install json-c@0.17\n```\n\n**Xcode**\nhttps://apps.apple.com/us/app/xcode/id497799835?mt=12\n\n### Build Dependencies\n**Ninja for building**\n```sh\nbrew install ninja\n```\n**Cmake for building**\n``` sh\nbrew install cmake\n```\n## Installation\n\n**Quick way with command line**\n\nArm architecture\n```sh\ncurl -L -o osxiec_cli.tar.gz https://github.com/Okerew/osxiec/releases/download/%s/osxiec_cli.tar.gz \u0026\u0026 tar -xvzf osxiec_cli.tar.gz \u0026\u0026 cd osxiec_cli \u0026\u0026 sudo sh install.sh\n```\nreplace %s with the latest version\n______\n\n86_64 architecture\n```sh\ncurl -L -o osxiec_cli_86_64.tar.gz https://github.com/Okerew/osxiec/releases/download/%s/osxiec_cli_86_64.tar.gz \u0026\u0026 tar -xvzf osxiec_cli_86_64.tar.gz \u0026\u0026 cd osxiec_cli_86_64 \u0026\u0026 sudo sh install.sh\n```\nreplace %s with the latest version\n____\nGui\n```sh\ncurl -L -o osxiec_gui.tar.gz https://github.com/Okerew/osxiec/releases/download/%s/osxiec_gui.tar.gz \u0026\u0026 sudo cp osxiec_gui.tar.gz /Applications \n```\nreplace %s with the latest version\n\n______\n1. **Download the Release**:\n   Download the `osxiec_cli.tar.gz` and `osxiec_gui.tar.gz` if you want a gui app file from the releases section.\n2. **Extract the Archive**:\n   ```sh\n   tar -xvzf osxiec_cli.tar.gz\n   ```\n   For gui version\n   ```sh\n   tar -xvzf osxiec_gui.tar.gz\n   ```\n\n3. **Run installation script in the extracted cli directory**:\n   ```sh\n   sudo sh install.sh \n   ```\n4. **If downloaded osxiec_gui**\n   ```\n   Copy app bundle from osxiec_gui.tar.gz to /Applications then run the app bundle or run osxiec.jar \n   ```\n\nTo update to a new release, repeat steps 1, 2, and 3 if using osxiec_gui also step 4.\n## Usage\n\n**Containerize a Directory**: containerizes a directory\n```sh\nsudo osxiec -contain {directory_path} {some_name}.bin {path_to_config_file_in_directory_path} {container_config_file}\n```\n\n**Create a cluster ( virtualized network )** create a cluster\n```sh\nsudo osxiec -network create {network_name} {vlan_id}\n```\n**Remove a vlan network** removes a vlan network\n```sh\nsudo osxiec -network remove {network_name} {vlan_id}\n```\n**Run with vlan config** run with vlan config\n``` sh\nsudo osxiec -run {some_name.bin} {network_name} -port {PORT_NUMBER}\n```\nport argument is optional\n\n**Version** checks the current version, updates\n```sh\nosxiec --version\n```\n**Pull** pulls an image from osxiec hub\n```sh\nosxiec -pull {container_name}\n```\n**Search** searches osxiec hub\n```sh\nosxiec -search {search_term_for_osxiec_hub}\n```\n**Upload** allows to upload a file to osxiec hub\n```sh\nosxiec -upload {filename} {username} {password} {description}\n```\n**Convert to Docker** converts to docker\n```sh\nosxiec -convert-to-docker {bin_file} {output_directory} {base_image} [custom_dockerfile]\n```\n**Clean** this will clean the container volume images from /tmp\n```sh\nsudo osxiec -clean\n```\n\n**Detach** detaches the container images\n```sh\nosxiec -detach\n```\n\n**Help** shows all the commands\n```sh\nosxiec -help\n```\n\n**Deploy** deploys a container\n```sh\nsudo osxiec -deploy {path_to_config} -port {PORT_NUMBER}\n```\n\n**Scan** scans a container for security vulnerabilities\n```sh\nosxiec -scan {some_name.bin}\n```\n\n**Deploym** deploys multiple containers, this is a work in progress, for now it works mostly fine with start config\n```sh\nsudo osxiec -deploym {config_file}\n```\n\n**Oexec** executes a container in offline mode without any networking or usage of ports\n```sh\nsudo osxiec -oexec {bin_file_path}\n```\n**Gexec** executes a container in gui mode\n```sh\nsudo osxiec -gexec {bin_file_path}\n```\n**Extract** extracts files and folders from a container\n```sh\nsudo osxiec -extract {bin_file_path}\n```\n\n**Convert to oci** converts to an oci container\n```sh\nosxiec -convert-to-oci {bin_file_path} {output_path} {arch} {author} \n```\n\n**Craft** crafts a container from a directory and a bin input file\n```sh\nsudo osxiec -craft {directory_path} {bin_input_file} {output_file} {start_config_file} {container_config_file}\n```\n\n**Start** starts a container a stopped container\n```sh\nsudo osxiec -start {volume_name} {network} -port {PORT_NUMBER} \n```\nport is optional\n\n**Ostart** starts a container a stopped container in offline mode\n```sh\nsudo osxiec -ostart {volume_name} \n```\n**Gstart** starts a container a stopped container in gui mode\n```sh\nsudo osxiec -gstart {volume_name}\n```\n**Api** an api that exposes some more functions of the cli\n```sh\nosxiec -api {argument}\n```\n\n**Update** updates configuration of a container\n```sh\nsudo osxiec -update\n```\n\n**Check for update** checks for update\n```sh\nsudo osxiec -check-for-update\n```\n**copy-volume** Copies files form a container volume to a directory\n```sh\nsudo osxiec -copy-volume {volume_name} {target_directory}\n```\n\n**bcn** Broadcasts a command to the container network\n```sh\nsudo osxiec -bcn {network_name} {command}\n```\n\n## Creating a container\nMake sure to include any dependencies or executables you can obtain these by searching for where a dependency or executable is located and copying it along with it's dependencies.\n\n\n**Example structure**\n``` \n[\n    \"container_name\",\n    {\n        \"some_content\",\n        \"subfolder1\" [\n           executable1\n           \"some_content\"\n         ]\n        \"start_config_file\"\n        \"some_executable\"\n        \"dependency\"\n    }    \n    \n]\n```\n\u003cbr\u003e\n\n**Script Example:**\nFor example if you have a node project make sure to include somewhere the node executable in the directory you want to contain, then run the script with the node executable.\n\n``` js\nconsole.log(\"Hello World\")\n```\n\nDo `path/to/node_executable_in_container/ script.js`\n\n\u003cbr\u003e\n\n**Containing**\n\nTo contain a directory run the `osxiec -contain {directory_path} {container_name} {start_config_file}`\n\nThis will also scan the container for security vulnerabilities.\n## Executing a container\nAfter creating a container or downloading one.\n**You can execute one with**\n\n`osxiec -oexec {container_name}`\n\nThis will execute it in offline mode. If you want to execute it in online mode see the next point.\n\n**Run with vlan**\n\nIf you have created a vlan network like said in the next point you can run the container with\n\n```osxiec -run {container_name} {network_name}```\n\nYou can also add the port argument with `-port {PORT_NUMBER}`\n\n**When executing**\n\u003cbr\u003e\nNormally it will start a listener which will allow it to communicate with other containers.\n![Screenshot 2024-07-24 at 18 11 30](https://github.com/user-attachments/assets/50d308ce-60bc-4355-a60d-a05430cea2df)\n\nIf you want to access the container terminal just press enter.\n![Screenshot 2024-07-24 at 18 11 45](https://github.com/user-attachments/assets/32762bb2-0eb0-492e-9d04-1fcf1b8b80f8)\n\n\n## Container commands\n1. **help** shows all the commands\n2. **debug** debugs the container\n3. **scale** scales the resources of the container\n4. **osxs** Execute an osxs script file\n5. **xs** Execute an osxs script command\n6. **autoscale** automatically scales the resources of the container\n7. **status** shows the status of the container\n8. **stop** stops the container.\n9. **wait** waits for a command(background task) in a container to stop.\n10. **ps** shows all the running commands(background tasks) in the container.\n11. **pause** pauses all background tasks in the container\n12. **unpause** unpauses all background tasks in the container\n13. **br** runs a command in background\n\n## Creating a vlan network\nTo create a network you can run `osxiec -network create {network_name} {vlan_id}`\n\nThe network_name can be any string like \"test\" for example.\n\nThe vlan id can be any number from 1-4094.\n\nFor example `osxiec -network create test 6`\n## Converting to Docker\n**Create docker file**\n``` dockerfile\n# Test Dockerfile for osxiec to Docker conversion\n\n# Use a lightweight base image\nFROM alpine:latest\n\n# Set the working directory in the container\nWORKDIR /app\n\n# Copy the application files from the osxiec container\n# Note: This will be handled by the conversion script, so we don't need COPY instructions here\n\n# Install any needed packages\nRUN apk add --no-cache python3 py3-pip\n\n# Set environment variables (these will be overwritten by the conversion script if not using a custom Dockerfile)\nENV MEMORY_SOFT_LIMIT=256m\nENV MEMORY_HARD_LIMIT=512m\nENV CPU_PRIORITY=20\n\n# Make port 8080 available to the world outside this container\nEXPOSE 8080\n\n# Run a simple Python HTTP server when the container launches\nCMD [\"python3\", \"-m\", \"http.server\", \"8080\"]\n```\n**Run convert-to-docker**\n\nFor this example\n```sh\nosxiec -convert-to-docker {container_name} {output_directory} alpine:latest samples/dockerfile\n```\n\n## Deploying\n**Create a config file**\n```\nsource_dir=/path/to/source/directory\ncontainer_file=/path/to/output/container.bin\nnetwork_name=my_network\nstart_config=/path/to/start_config.sh\n```\n**Deploy**\n```sh\nsudo osxiec -deploy {path_to_config_file} \n``` \nYou can also use `-port {PORT_NUMBER}`\n\n**Deploym**\nyou can also deploy multiple containers, this is a work in progress though.\n```sh\nsudo osxiec -deploym {config_file} {PORT_NUMBER1} {PORT_NUMBER2} etc.\n``` \n**Config**\n\n```\npath_to_container1_config {network_name}\npath_to_container2_config {network_name}\n```\n\n## Osxiec Script\nOsxiec script is a scripting language created for managing osxiec containers.\n### Syntax\n**Set Memory**\n```sh\nSET_MEMORY {memory_soft} {memory_hard}\n```\n**Set CPU Priority**\n```sh\nSET_CPU {cpu_priority}\n```\n**Execute**\n```sh\nEXECUTE {command}\n```\n**Conditional Execution**\n```sh\nIF {condition} EXECUTE {command}\n```\n**Sleep**\n```sh\nSLEEP {seconds}\n```\n**Log**\n```sh\nLOG {message}\n```\n**Execute File**\n```sh\nEXECUTE_FILE {path_to_script}\n```\n**Set Variable**\n```sh\nSET {variable} {value}\n```\n**While Loop**\n```sh\nWHILE {condition} {commands} END\n```\n**For Loop**\n```sh\nFOR {variable} TO {2variable} STEP {value} {commands} END\n```\n\n**ELSE**\n```sh\nIF {condition} ELSE {commands} END\n```\nNote ELSE statement for now doesn't work with LOG and is a work in progress\n\n**Example**\n```\n# This is an example script for the OSXIEC scripting language\nSET counter 0\nSET limit 10\n\n# Loop from 0 to 10\nFOR counter=0 TO limit STEP 2\n    IF counter==5\n        LOG \"Counter is 5\"\n    END\n    SLEEP 1\nEND\n\nIF $var==5 LOG Variable is 5 ELSE LOG Variable is not 5\n\n# Loop while counter is less than limit\nWHILE counter\u003climit\n    IF counter==5\n        LOG \"Counter is 5\"\n    END\n    SET counter $(($counter + 1))\n    SLEEP 1\nEND\n\n# Log the start of the script\nLOG Starting script for $container_name\n\n# Set container memory limits\nSET_MEMORY $mem_soft $mem_hard\n\n# Set CPU priority\nSET_CPU $cpu_priority\n\n# Execute a command\nEXECUTE echo \"Container $container_name initialized\"\n\n# Conditional execution\nSET status running\nIF status==running EXECUTE echo \"Container is operational\"\n\n# Sleep for 2 seconds\nSLEEP 2\n\n# Echo some information\nECHO Container $container_name is configured with:\nECHO - Memory limits: $mem_soft MB (soft) / $mem_hard MB (hard)\nECHO - CPU priority: $cpu_priority\n```\n\n## Debugging\n\nWhen in a container, you can use the following commands to debug the container.\n\u003cbr\u003e\nTo start debugging `debug`\n\u003cbr\u003e\nThen you can use these commands\n___\n``` \nstep\n```\nwhich steps to the next command\n___\n``` \nbreak \u003ccommand\u003e\n```\nCreates a breakpoint at the specified command\n___\n``` \nprint \u003cvar\u003e\n```\nPrints the value of the specified variable of the container\n___\n``` \nprint\n```\nPrints the whole container state\n___\n``` \nhelp\n```\nShows what you can do\n___\n``` \ncontinue\n```\nContinues execution of the container\n_____\n### \u003ca href=\"https://osxiec.glitch.me\"\u003eOsxiec Container Hub\u003c/a\u003e\nThis is a place where you can upload your containers to.\n![Screenshot 2024-07-24 at 18 25 20](https://github.com/user-attachments/assets/451f7851-ac64-4d59-9654-6729906fd01d)\n\n___\n### \u003ca href=\"https://github.com/Okerew/osxiec_gui\"\u003eOsxiec Gui\u003c/a\u003e\nThis is the source code for the gui version of osxiec.\n![Screenshot 2024-07-24 at 12 05 58](https://github.com/user-attachments/assets/42d858e1-e4fd-4a82-b2e8-f86a7c35be38)\n\n___\n### \u003ca href=\"https://github.com/Okerew/osxiec_terminal.git\"\u003eOsxiec Terminal\u003c/a\u003e\nA terminal emulator specifically created for osxiec\n___\n## Building\n**Git clone the repository**\n``` sh\ngit clone https://github.com/Okerew/osxiec.git\n```\n**Go to the directory**\n``` sh\ncd osxiec\n```\n**Build the osxiec executable**\n``` sh\nmkdir {build-directory}\ncd {build-directory}\ncmake -S .. -B . -G \"Ninja\"\nninja\n```\n\n**Give permissions to scripts if needed**\n``` sh\nsudo chmod +x scripts/osxiec_deploy_multiple.sh\nsudo chmod +x scripts/install.sh\n```\n**Finalize**\nto make it work put all executables in a one folder, copy there install.sh and run it\n\n### Build java gui\nGit clone the gui\n```sh\ngit clone https://github.com/Okerew/osxiec_gui.git\n```\n\nGo to the directory\n```sh\ncd osxiec_gui\n```\nBuild the class\n```sh\njavac OsxiecApp.java\n```\nBuild the jar\n```sh\njar -cvfe osxiec.jar OsxiecApp OsxiecApp.class\n```\n\nCopy jar into app bundle, remove the previous one\n```sh\ncp osxiec.jar osxiec.app/Contents/Resources\n```\nIf using the one from release, delete the previous one\n\nCopy the icon into Contents/Resources\n\nFinally, copy the run_app_bundle.sh into the bundle as osxiec_gui\n```sh\ncp run_app_bundle.sh osxiec.app/Contents/MacOS/osxiec_gui\n```\n## Plugins\n**Example plugin** can be seen in samples/sample_plugin.c, this should make you understand how osxiec loads plugins.\n\n**Build plugin**\n``` sh\ngcc -shared -fPIC -o {plugin_name}.so {plugin_name}.c  \n```\n\n**Install plugin**\n\n``` sh \nsudo cp {plugin_name}.so  ~/.osxiec/plugins\n```\nAfter this on the execution of osxiec command the plugin will be loaded.\n## Notes\n\n- **Not a Docker Replacement**:\n  While OSXIEC offers similar functionality to Docker, it lacks some advanced features of Docker. It is more supposed to be a quicker testing tool than docker on macOS, it is not designed to replace it, just to test basic ideas and software, distribute macOS software.\n- **macOS Only**:\n  OSXIEC uses native macOS features and is not compatible with other operating systems.\n- **Isolation Limitations**:\n  Due to macOS limitations, complete isolation like in Linux is not possible. The contained directory will have some access to the outside environment, you can have a start config file if needed.\n- **Supported Features**:\n  Despite its limitations, OSXIEC provides isolation using namespaces, setuid, image layers, basic user process control, memory and CPU control, and special permissions using user IDs and group IDs, unpacking the image into a disk image(APFS), vlans.\n- **Support**: Remember that not everything will work fully for example node won't work fully because it is making sys calls which spawn things outside the container, in this example local things that do not rely on the repl server will work.\n- **Temps**: If you need a lot of storage for the moment, and you used a container use the clean command.\n- **Why is chroot not used?**\n  Chroot requires for SIP to be disabled, which causes many security risks, chroot can be easily exited by any process, using the normal macOS restrictions is way more secure, reliable,\n  having it disabled causes many permission issues.\n- **Sandbox deprecation error** yes I know that sandbox innit is deprecated but there isn't really an alternative for it unless I would use xcode and there is no way I am using it to rebuild this.\n\n- **If you want to remove ips from the network do it by editing the file in private/etc/network_{network_name}.conf file**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fokerew%2Fosxiec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fokerew%2Fosxiec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fokerew%2Fosxiec/lists"}