Skip to main content

​
Installation

Get Container Kit up and running on your macOS system. This guide covers system requirements, installation methods, and initial setup.

​
System Requirements

IMPORTANT: Container Kit requires macOS 26.0 or later and is only compatible with Apple Silicon Macs.
Before installing Container Kit, ensure your system meets these requirements:
  • macOS 26.0+ (Required - older versions not supported)
  • Apple Silicon Mac (M1/M2/M3/M4 - Intel Macs not supported)
  • Xcode Command Line Tools

​
Install Xcode Command Line Tools

If you don’t already have Xcode Command Line Tools installed, run: 
xcode-select --install
This will prompt a GUI installer to set up the necessary development tools.

​
Installation Methods

Container Kit can be installed in two ways: downloading pre-built releases or building from source. During the active development phase, building from source is recommended.
Pre-built releases may not be available during the development phase. Use the “Build from Source” option below if downloads are unavailable.
1

Download the latest release

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

Open the DMG file

Double-click the downloaded .dmg file to mount the disk image. A Finder window will open showing the Container Kit application.
3

Install to Applications

Drag the Container Kit icon to your Applications folder to install it.
# The DMG installer will show a visual interface for this step
# Simply drag Container Kit.app to the Applications folder icon
4

Launch Container Kit

Launch Container Kit from:
  • Applications folder - Open Finder → Applications → Container Kit
  • Spotlight - Press Cmd + Space and type “Container Kit”
  • Terminal - Run open -a "Container Kit"
Building from source gives you the latest features and allows you to contribute to the project.
1

Install prerequisites

Ensure you have the required development tools:
# Install Xcode Command Line Tools
xcode-select --install

# Install pnpm (if not already installed)
npm install -g pnpm
Container Kit uses pnpm as its package manager for faster installs and better disk space efficiency.
2

Clone the repository

Clone the Container Kit repository from GitHub:
git clone https://github.com/etherCorps/ContainerKit.git
cd ContainerKit
3

Install dependencies

Install all Node.js and Rust dependencies:
pnpm install
This will install:
  • Frontend dependencies (Svelte, TailwindCSS, TypeScript, etc.)
  • Build tools (Vite, Tauri CLI, etc.)
  • Rust dependencies (configured in src-tauri/Cargo.toml)
4

Download Apple Container CLI

Container Kit relies on Apple’s official container CLI. Download it using the provided script:
./scripts/download-apple-container-cli.sh
This script will:
  • Download container-0.10.0-installer-signed.pkg from Apple’s GitHub
  • Extract the installer package
  • Copy bin and libexec directories to src-tauri/binaries/sidecar/apple-container/
  • Create an Apple Silicon-specific binary copy at container-aarch64-apple-darwin
  • Clean up temporary files
The Apple Container CLI is bundled as a sidecar binary and will be included in your built application.
5

Build the application

Build Container Kit for production:
pnpm tauri:build
This command will:
  • Generate database migrations from schema
  • Build the frontend with Vite
  • Compile the Rust backend
  • Create a signed .app bundle
  • Generate a .dmg installer
The built application will be located at:
  • App Bundle: src-tauri/target/release/bundle/macos/Container Kit.app
  • DMG Installer: src-tauri/target/release/bundle/dmg/Container Kit_0.10.0_aarch64.dmg
6

Install and run

You can now run Container Kit in several ways:
# Option 1: Run directly from build output
open "src-tauri/target/release/bundle/macos/Container Kit.app"

# Option 2: Install the DMG to Applications folder
# (Double-click the DMG file and drag to Applications)

# Option 3: Run in development mode
pnpm tauri dev

​
First Launch

When you launch Container Kit for the first time, you’ll need to complete a few setup steps:
1

Security permissions

macOS may show a security warning for applications downloaded from the internet. To allow Container Kit to run:
  1. Open System Settings → Privacy & Security
  2. Scroll down to the Security section
  3. Click Open Anyway next to the Container Kit warning
During the development phase, the app may not be signed and notarized. Apple is currently not allowing enrollment in the developer program for this project.
2

Grant system permissions

Container Kit requires certain system permissions for container management:
  • Full Disk Access - For accessing container data and sandboxed app files
  • Automation - For terminal integration and container operations
macOS will prompt you to grant these permissions when needed. You can also configure them manually:
  1. Open System Settings → Privacy & Security
  2. Navigate to Full Disk Access and Automation
  3. Enable Container Kit in both sections
3

Initial configuration

Follow the welcome wizard to configure your environment:
  • Choose your preferred theme (Light/Dark/System)
  • Configure container storage locations
  • Set up default container networking options
Most settings are one-time setup and can be changed later in Settings.

​
Verification

Verify that Container Kit is installed correctly: 
# Check that the Apple Container CLI is available
open -a "Container Kit"

# The application should launch without errors
# Check the About section for version information
You should see:
  • Version: 0.10.0
  • Product Name: Container Kit
  • Identifier: com.ethercorps.container-kit

​
Updating Container Kit

​
Automatic Updates

Container Kit includes an auto-updater that checks for new releases. When an update is available:
  1. You’ll see a notification in the app
  2. Click “Update” to download and install
  3. The app will restart automatically
Auto-updates require a valid code signature. During development, you may need to update manually.

​
Manual Updates

To manually update Container Kit: For DMG installations:
  1. Download the latest .dmg from GitHub Releases
  2. Drag the new version to Applications (replacing the old one)
For source builds: 
cd ContainerKit
git pull origin main
pnpm install
./scripts/download-apple-container-cli.sh
pnpm tauri:build

​
Troubleshooting

​
Common Installation Issues

If you see “Container Kit can’t be opened because it is from an unidentified developer”:
  1. Right-click the app and select “Open”
  2. Click “Open” in the confirmation dialog
  3. Or go to System Settings → Privacy & Security → Security and click Open Anyway
Ensure Xcode Command Line Tools are properly installed:
# Check if installed
xcode-select -p

# If not installed or having issues, reinstall
sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install
If the download script fails:
  1. Check your internet connection
  2. Verify the version in scripts/download-apple-container-cli.sh is available
  3. Manually download from Apple Container Releases
  4. Extract to src-tauri/binaries/sidecar/apple-container/
Install pnpm globally:
npm install -g pnpm

# Or use corepack (built into Node.js 16.13+)
corepack enable
corepack prepare pnpm@latest --activate

​
Next Steps

Now that Container Kit is installed, you’re ready to start managing containers:

Quick Start Guide

Get up and running with your first container

Contributing

Learn how to contribute to Container Kit development

Build docs developers (and LLMs) love

Get started for freeTalk to us