https://github.com/okerew/osxiec
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.
https://github.com/okerew/osxiec
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
Last synced: about 1 year ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/okerew/osxiec
- Owner: Okerew
- License: epl-2.0
- Created: 2024-07-12T12:29:27.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-04T18:07:37.000Z (about 1 year ago)
- Last Synced: 2025-03-04T18:35:33.483Z (about 1 year ago)
- 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
- Language: C
- Homepage: https://osxiec.glitch.me
- Size: 439 KB
- Stars: 28
- Watchers: 4
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Osxiec
OSXIEC 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.
If it says that macOS can't identify if it is malware or not, close it go into settings and allow it to be executed.
____
## Dependencies
**HomeBrew for installing dependencies**
```sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
**Curl**
```sh
brew install curl
```
**Readline**
```sh
brew install readline
```
**Json-c**
```sh
brew install json-c@0.17
```
**Xcode**
https://apps.apple.com/us/app/xcode/id497799835?mt=12
### Build Dependencies
**Ninja for building**
```sh
brew install ninja
```
**Cmake for building**
``` sh
brew install cmake
```
## Installation
**Quick way with command line**
Arm architecture
```sh
curl -L -o osxiec_cli.tar.gz https://github.com/Okerew/osxiec/releases/download/%s/osxiec_cli.tar.gz && tar -xvzf osxiec_cli.tar.gz && cd osxiec_cli && sudo sh install.sh
```
replace %s with the latest version
______
86_64 architecture
```sh
curl -L -o osxiec_cli_86_64.tar.gz https://github.com/Okerew/osxiec/releases/download/%s/osxiec_cli_86_64.tar.gz && tar -xvzf osxiec_cli_86_64.tar.gz && cd osxiec_cli_86_64 && sudo sh install.sh
```
replace %s with the latest version
____
Gui
```sh
curl -L -o osxiec_gui.tar.gz https://github.com/Okerew/osxiec/releases/download/%s/osxiec_gui.tar.gz && sudo cp osxiec_gui.tar.gz /Applications
```
replace %s with the latest version
______
1. **Download the Release**:
Download the `osxiec_cli.tar.gz` and `osxiec_gui.tar.gz` if you want a gui app file from the releases section.
2. **Extract the Archive**:
```sh
tar -xvzf osxiec_cli.tar.gz
```
For gui version
```sh
tar -xvzf osxiec_gui.tar.gz
```
3. **Run installation script in the extracted cli directory**:
```sh
sudo sh install.sh
```
4. **If downloaded osxiec_gui**
```
Copy app bundle from osxiec_gui.tar.gz to /Applications then run the app bundle or run osxiec.jar
```
To update to a new release, repeat steps 1, 2, and 3 if using osxiec_gui also step 4.
## Usage
**Containerize a Directory**: containerizes a directory
```sh
sudo osxiec -contain {directory_path} {some_name}.bin {path_to_config_file_in_directory_path} {container_config_file}
```
**Create a cluster ( virtualized network )** create a cluster
```sh
sudo osxiec -network create {network_name} {vlan_id}
```
**Remove a vlan network** removes a vlan network
```sh
sudo osxiec -network remove {network_name} {vlan_id}
```
**Run with vlan config** run with vlan config
``` sh
sudo osxiec -run {some_name.bin} {network_name} -port {PORT_NUMBER}
```
port argument is optional
**Version** checks the current version, updates
```sh
osxiec --version
```
**Pull** pulls an image from osxiec hub
```sh
osxiec -pull {container_name}
```
**Search** searches osxiec hub
```sh
osxiec -search {search_term_for_osxiec_hub}
```
**Upload** allows to upload a file to osxiec hub
```sh
osxiec -upload {filename} {username} {password} {description}
```
**Convert to Docker** converts to docker
```sh
osxiec -convert-to-docker {bin_file} {output_directory} {base_image} [custom_dockerfile]
```
**Clean** this will clean the container volume images from /tmp
```sh
sudo osxiec -clean
```
**Detach** detaches the container images
```sh
osxiec -detach
```
**Help** shows all the commands
```sh
osxiec -help
```
**Deploy** deploys a container
```sh
sudo osxiec -deploy {path_to_config} -port {PORT_NUMBER}
```
**Scan** scans a container for security vulnerabilities
```sh
osxiec -scan {some_name.bin}
```
**Deploym** deploys multiple containers, this is a work in progress, for now it works mostly fine with start config
```sh
sudo osxiec -deploym {config_file}
```
**Oexec** executes a container in offline mode without any networking or usage of ports
```sh
sudo osxiec -oexec {bin_file_path}
```
**Gexec** executes a container in gui mode
```sh
sudo osxiec -gexec {bin_file_path}
```
**Extract** extracts files and folders from a container
```sh
sudo osxiec -extract {bin_file_path}
```
**Convert to oci** converts to an oci container
```sh
osxiec -convert-to-oci {bin_file_path} {output_path} {arch} {author}
```
**Craft** crafts a container from a directory and a bin input file
```sh
sudo osxiec -craft {directory_path} {bin_input_file} {output_file} {start_config_file} {container_config_file}
```
**Start** starts a container a stopped container
```sh
sudo osxiec -start {volume_name} {network} -port {PORT_NUMBER}
```
port is optional
**Ostart** starts a container a stopped container in offline mode
```sh
sudo osxiec -ostart {volume_name}
```
**Gstart** starts a container a stopped container in gui mode
```sh
sudo osxiec -gstart {volume_name}
```
**Api** an api that exposes some more functions of the cli
```sh
osxiec -api {argument}
```
**Update** updates configuration of a container
```sh
sudo osxiec -update
```
**Check for update** checks for update
```sh
sudo osxiec -check-for-update
```
**copy-volume** Copies files form a container volume to a directory
```sh
sudo osxiec -copy-volume {volume_name} {target_directory}
```
**bcn** Broadcasts a command to the container network
```sh
sudo osxiec -bcn {network_name} {command}
```
## Creating a container
Make 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.
**Example structure**
```
[
"container_name",
{
"some_content",
"subfolder1" [
executable1
"some_content"
]
"start_config_file"
"some_executable"
"dependency"
}
]
```
**Script Example:**
For 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.
``` js
console.log("Hello World")
```
Do `path/to/node_executable_in_container/ script.js`
**Containing**
To contain a directory run the `osxiec -contain {directory_path} {container_name} {start_config_file}`
This will also scan the container for security vulnerabilities.
## Executing a container
After creating a container or downloading one.
**You can execute one with**
`osxiec -oexec {container_name}`
This will execute it in offline mode. If you want to execute it in online mode see the next point.
**Run with vlan**
If you have created a vlan network like said in the next point you can run the container with
```osxiec -run {container_name} {network_name}```
You can also add the port argument with `-port {PORT_NUMBER}`
**When executing**
Normally it will start a listener which will allow it to communicate with other containers.
If you want to access the container terminal just press enter.
## Container commands
1. **help** shows all the commands
2. **debug** debugs the container
3. **scale** scales the resources of the container
4. **osxs** Execute an osxs script file
5. **xs** Execute an osxs script command
6. **autoscale** automatically scales the resources of the container
7. **status** shows the status of the container
8. **stop** stops the container.
9. **wait** waits for a command(background task) in a container to stop.
10. **ps** shows all the running commands(background tasks) in the container.
11. **pause** pauses all background tasks in the container
12. **unpause** unpauses all background tasks in the container
13. **br** runs a command in background
## Creating a vlan network
To create a network you can run `osxiec -network create {network_name} {vlan_id}`
The network_name can be any string like "test" for example.
The vlan id can be any number from 1-4094.
For example `osxiec -network create test 6`
## Converting to Docker
**Create docker file**
``` dockerfile
# Test Dockerfile for osxiec to Docker conversion
# Use a lightweight base image
FROM alpine:latest
# Set the working directory in the container
WORKDIR /app
# Copy the application files from the osxiec container
# Note: This will be handled by the conversion script, so we don't need COPY instructions here
# Install any needed packages
RUN apk add --no-cache python3 py3-pip
# Set environment variables (these will be overwritten by the conversion script if not using a custom Dockerfile)
ENV MEMORY_SOFT_LIMIT=256m
ENV MEMORY_HARD_LIMIT=512m
ENV CPU_PRIORITY=20
# Make port 8080 available to the world outside this container
EXPOSE 8080
# Run a simple Python HTTP server when the container launches
CMD ["python3", "-m", "http.server", "8080"]
```
**Run convert-to-docker**
For this example
```sh
osxiec -convert-to-docker {container_name} {output_directory} alpine:latest samples/dockerfile
```
## Deploying
**Create a config file**
```
source_dir=/path/to/source/directory
container_file=/path/to/output/container.bin
network_name=my_network
start_config=/path/to/start_config.sh
```
**Deploy**
```sh
sudo osxiec -deploy {path_to_config_file}
```
You can also use `-port {PORT_NUMBER}`
**Deploym**
you can also deploy multiple containers, this is a work in progress though.
```sh
sudo osxiec -deploym {config_file} {PORT_NUMBER1} {PORT_NUMBER2} etc.
```
**Config**
```
path_to_container1_config {network_name}
path_to_container2_config {network_name}
```
## Osxiec Script
Osxiec script is a scripting language created for managing osxiec containers.
### Syntax
**Set Memory**
```sh
SET_MEMORY {memory_soft} {memory_hard}
```
**Set CPU Priority**
```sh
SET_CPU {cpu_priority}
```
**Execute**
```sh
EXECUTE {command}
```
**Conditional Execution**
```sh
IF {condition} EXECUTE {command}
```
**Sleep**
```sh
SLEEP {seconds}
```
**Log**
```sh
LOG {message}
```
**Execute File**
```sh
EXECUTE_FILE {path_to_script}
```
**Set Variable**
```sh
SET {variable} {value}
```
**While Loop**
```sh
WHILE {condition} {commands} END
```
**For Loop**
```sh
FOR {variable} TO {2variable} STEP {value} {commands} END
```
**ELSE**
```sh
IF {condition} ELSE {commands} END
```
Note ELSE statement for now doesn't work with LOG and is a work in progress
**Example**
```
# This is an example script for the OSXIEC scripting language
SET counter 0
SET limit 10
# Loop from 0 to 10
FOR counter=0 TO limit STEP 2
IF counter==5
LOG "Counter is 5"
END
SLEEP 1
END
IF $var==5 LOG Variable is 5 ELSE LOG Variable is not 5
# Loop while counter is less than limit
WHILE counter
To start debugging `debug`
Then you can use these commands
___
```
step
```
which steps to the next command
___
```
break
```
Creates a breakpoint at the specified command
___
```
print
```
Prints the value of the specified variable of the container
___
```
print
```
Prints the whole container state
___
```
help
```
Shows what you can do
___
```
continue
```
Continues execution of the container
_____
### Osxiec Container Hub
This is a place where you can upload your containers to.
___
### Osxiec Gui
This is the source code for the gui version of osxiec.
___
### Osxiec Terminal
A terminal emulator specifically created for osxiec
___
## Building
**Git clone the repository**
``` sh
git clone https://github.com/Okerew/osxiec.git
```
**Go to the directory**
``` sh
cd osxiec
```
**Build the osxiec executable**
``` sh
mkdir {build-directory}
cd {build-directory}
cmake -S .. -B . -G "Ninja"
ninja
```
**Give permissions to scripts if needed**
``` sh
sudo chmod +x scripts/osxiec_deploy_multiple.sh
sudo chmod +x scripts/install.sh
```
**Finalize**
to make it work put all executables in a one folder, copy there install.sh and run it
### Build java gui
Git clone the gui
```sh
git clone https://github.com/Okerew/osxiec_gui.git
```
Go to the directory
```sh
cd osxiec_gui
```
Build the class
```sh
javac OsxiecApp.java
```
Build the jar
```sh
jar -cvfe osxiec.jar OsxiecApp OsxiecApp.class
```
Copy jar into app bundle, remove the previous one
```sh
cp osxiec.jar osxiec.app/Contents/Resources
```
If using the one from release, delete the previous one
Copy the icon into Contents/Resources
Finally, copy the run_app_bundle.sh into the bundle as osxiec_gui
```sh
cp run_app_bundle.sh osxiec.app/Contents/MacOS/osxiec_gui
```
## Plugins
**Example plugin** can be seen in samples/sample_plugin.c, this should make you understand how osxiec loads plugins.
**Build plugin**
``` sh
gcc -shared -fPIC -o {plugin_name}.so {plugin_name}.c
```
**Install plugin**
``` sh
sudo cp {plugin_name}.so ~/.osxiec/plugins
```
After this on the execution of osxiec command the plugin will be loaded.
## Notes
- **Not a Docker Replacement**:
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.
- **macOS Only**:
OSXIEC uses native macOS features and is not compatible with other operating systems.
- **Isolation Limitations**:
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.
- **Supported Features**:
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.
- **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.
- **Temps**: If you need a lot of storage for the moment, and you used a container use the clean command.
- **Why is chroot not used?**
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,
having it disabled causes many permission issues.
- **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.
- **If you want to remove ips from the network do it by editing the file in private/etc/network_{network_name}.conf file**