Skip to main content

​
Overview

Container Kit is a modern desktop application for managing Apple containers on macOS. This guide will walk you through the installation process, initial setup, and your first container operations.
Container Kit requires macOS 26.0+ and Apple Silicon (M1/M2/M3/M4). Intel Macs are not supported.

​
Prerequisites

Before installing Container Kit, ensure you have:
  • macOS 26.0 or later
  • Apple Silicon Mac (M1/M2/M3/M4)
  • Xcode Command Line Tools installed
  • Administrator access to your Mac

​
Install Xcode Command Line Tools

If you haven’t already installed the Xcode Command Line Tools, run: 
xcode-select --install

​
Installation

Pre-built releases may not be available during the development phase. Use the build from source option below if no releases are available.
1

Download the DMG

Visit the GitHub Releases page and download the latest .dmg file for your macOS version.
2

Install the Application

  1. Open the downloaded .dmg file
  2. Drag Container Kit to your Applications folder
  3. Eject the disk image
3

Launch Container Kit

Open Container Kit from:
  • Applications folder
  • Spotlight (⌘ + Space, then type “Container Kit”)
  • Terminal: open -a "Container Kit"

​
Option 2: Build from Source

Building from source gives you access to the latest development features.
1

Install Dependencies

Install Node.js and pnpm:
# Install pnpm globally
npm install -g pnpm
2

Clone the Repository

git clone https://github.com/etherCorps/ContainerKit.git
cd ContainerKit
3

Install Project Dependencies

pnpm install
4

Download Apple Container CLI

Container Kit requires the Apple Container CLI to function:
./scripts/download-apple-container-cli.sh
This script downloads and configures the necessary Apple containerization tools.
5

Build the Application

pnpm tauri:build
The built application will be located in src-tauri/target/release/bundle/.

​
First Launch Setup

​
Grant System Permissions

On first launch, Container Kit requires several system permissions:
1

Open Container Kit

Launch the application from your Applications folder.
2

Allow System Access

macOS will prompt you to grant permissions for:
  • Full Disk Access - Required for container management
  • Terminal/Shell Access - Required for executing container commands
Click Open System Settings and enable the required permissions.
3

Create Symbolic Links

Container Kit needs to create symbolic links to the Apple Container CLI:
  1. Click Setup Container CLI in the welcome screen
  2. Enter your administrator password when prompted
  3. Wait for the setup to complete
This process links the bundled container binaries to system paths.
4

Verify Installation

Container Kit will automatically verify that the containerization service is available. You should see a success message indicating the setup is complete.
If setup fails, you can manually create symlinks by running the setup process again from Settings > System > Reinstall Container CLI.

​
Start the Containerization Service

The Apple containerization service must be running to manage containers.
1

Check Service Status

Navigate to Settings > System in Container Kit to view the current service status.
2

Start the Service

Click Start Containerization Service to launch the service:
// Under the hood, Container Kit runs:
import { startContainerization } from '$lib/services/containerization/system/service';

const result = await startContainerization();
// Executes: container s start
3

Verify Status

The service status indicator should turn green, showing “Running”.
The containerization service requires administrator privileges to start. You’ll be prompted for your password.

​
Your First Container

Let’s pull an image and create your first container.
1

Pull an Image

  1. Navigate to the Images tab
  2. Click Pull Image
  3. Enter an image name, for example: nginx
  4. Click Pull
Container Kit will download the image from the registry.
2

View Your Images

The pulled image will appear in the Images list with details like:
  • Image name and tag
  • Size
  • Creation date
3

Create a Container

  1. Navigate to the Containers tab
  2. Click New Container
  3. Select the nginx image
  4. Configure container settings (name, ports, etc.)
  5. Click Create
4

Start the Container

  1. Find your new container in the list
  2. Click the Start button
  3. The status will change to “Running”

​
Understanding the Interface

​
Dashboard

The main dashboard shows:
  • Container Count - Total, running, and stopped containers
  • Image Count - Total images and disk usage
  • System Status - Containerization service status
  • Recent Activity - Latest container operations

​
Containers Tab

Manage all your containers:
  • View container list with status indicators
  • Start, stop, and remove containers
  • View container logs and details
  • Access container terminal

​
Images Tab

Manage container images:
  • View all pulled images
  • Pull new images from registries
  • Remove unused images
  • Import/export images as tar archives

​
Settings

Configure Container Kit:
  • System - Service management and CLI setup
  • Network - DNS and network configuration
  • Registry - Container registry authentication
  • Appearance - Theme and UI preferences

​
Troubleshooting First Launch

If you see “Container CLI not found” error:
  1. Ensure you downloaded the Apple Container CLI: 
    ./scripts/download-apple-container-cli.sh
  2. Verify the binaries exist in src-tauri/binaries/
  3. Retry the symbolic link creation from Settings
The CLI is required for all container operations.
If you encounter permission errors:
  1. Open System Settings > Privacy & Security
  2. Grant Full Disk Access to Container Kit
  3. Restart Container Kit
  4. Try the operation again
Some operations require administrator privileges and will prompt for your password.
If the containerization service fails to start:
  1. Check system requirements (macOS 26.0+, Apple Silicon)
  2. Ensure no other container management tools are running
  3. View service logs in Settings > System > Service Logs
  4. Try stopping and restarting: container s stop && container s start
See the Troubleshooting guide for more solutions.
If Container Kit won’t open:
  1. Right-click the app and select Open (first time only)
  2. If prompted, click Open in the security dialog
  3. Check Console.app for error messages
  4. Ensure your macOS version is 26.0 or later
During development, the app may not be code-signed. Use right-click > Open to bypass Gatekeeper.

​
Next Steps

Now that you have Container Kit installed and running:

Container Management

Learn how to create, start, stop, and manage containers

Image Management

Pull, push, import, and export container images

Networking

Configure container networks and DNS settings

Troubleshooting

Solve common issues and errors
Need help? Join our GitHub Discussions or check the troubleshooting guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us