- Closes#150, #394.
- Introduces `AttachmentConfiguration` type so that we can add key-value
options to `--network` in the future.
- Eliminates redundant `ContainersService.Item` type.
- Since we now ensure at ContainersService that hostnames will not
conflict, the network helper IP allocator now simply provides the
existing IP if for an allocation on an existing hostname, which should
handle (in an eventually consistent way) the case where a container
fails to deallocate an IP on shutdown.
We were defer closing the IO for run/exec/start fairly late in the
container run cycle which had the downside of that if the container run
failed your tty would be stuck in raw mode. This change just moves the
closing (return tty to origin state) to directly after we create the IO.
Today if you asked for a pty and also wanted to detach we'd open stdin
and then immediately close that pipe which would close the guest relay
as well. I don't believe we need stdin open unless it's asked for with
-i. Truthfully there's one extra bit here that is needed which is if -i
and -d are supplied we need to tell the daemon to open stdin, but not
send an fd (as they're client supplied and the client/cli is going to
exit immediately). That will need to be a followup, as it's mainly
useful for attach which we don't have today.
- Sets up API server as source of truth for installation root, similarly
to what was done for the data root. `system start` establishes the
install root, setting the environment variable `CONTAINER_INSTALL_ROOT`
when launching the API server.
- The API server propagates the environment variable when launching
helpers, and returns the install root to the CLI via the health check
XPC.
- Includes several fixes for detecting plugins that use app bundle
layout.
- Part of #384.
- Rename to reflect that these are not just client defaults.
- Relocate so callers don't need the heavyweight coupling to
ContainerClient to access the type.
Closes#339.
This change adds named volume support to container, providing volume
management CLI commands - `create, delete, list and inspect`. The
implementation uses EXT4 block-based persistent storage with a new
`VolumesService` actor for thread-safe operations, integrates seamlessly
with the existing container mount system through a new `.volume`
filesystem type, and provides atomic volume operations with XPC-based
API communication. Volumes are stored in isolated directories with
configurable sizes (default 512GB) and include proper cleanup and
container usage tracking for safe deletion.
Example Usage:
```
# Create a volume
container volume create mydata
# Use volume in container
container run -v mydata:/data alpine
# List volumes
container volume list
# Inspect volume details
container volume inspect mydata
# Clean up
container volume rm mydata
```
Fixes#212
This PR:
- adds a `package func resolved()` on `ClientImage` that makes use of
the new `com.apple.containerization.index.indirect` annotation to
identify and resolve wrapper indices created by Containerization;
- replace the digest displayed in `container image list` with the one of
the resolved manifest;
- use the resolved manifest for `container image inspect` if the index
is a wrapper.
This matches other container commands that rely on user arguments at the
end, such as `container run`. Closes#395.
Signed-off-by: Kathryn Baldauf <k_baldauf@apple.com>
0.5.0 introduces a new way to configure the containers and execs. This
is now done all upfront at constructor time in a callback style. I'm
very happy with the config improvements, but because IO can only be
setup at constructor time this makes it so that we need to supply IO at
creation time of the VM or exec, which isn't the end of the world. All
that really changes is `boostrap()` and `createProcess()` now take in IO
instead of slightly later in `process.start()`
readabilityHandler is a bit crummy if it's a regular file. This just
writes our own loop and exits and shuts down the write end of the pipe
if we get to the end of the file.
See discussion below for example. For multiple network interfaces in a
single container we'll want to integrate against a containerization that
includes apple/containerization#156.
The change bumps the containerization dependency to 0.2.0 and addresses
the breaking API changes.
```console
% container network
OVERVIEW: Manage container networks
USAGE: container network <subcommand>
OPTIONS:
--version Show the version.
-h, --help Show help information.
SUBCOMMANDS:
create Create a new network
delete, rm Delete one or more networks
list, ls List networks
inspect Display information about one or more networks
See 'container help network <subcommand>' for detailed help.
```
Closes https://github.com/apple/container/issues/80
Adds the following help message if you try to run `container` against a
host that hasn't started the container system:
```
❯ /usr/local/bin/container list
Error: internalError: "failed to list containers" (cause: "interrupted: "Connection invalid: ensure container system has been started with `container system start`"")
❯ /usr/local/bin/container run -it --rm docker.io/alpine
Error: interrupted: "Connection invalid: ensure container system has been started with `container system start`"
```
This PR resolves a race condition when removing a container immediately
after stopping it, caused by the `stop` command returning before the
container fully transitions to the stopped state (#130).
**Changes:**
- Enhanced `TestCLIRmRace.swift` with robust test logic and helper
methods (`containerExists`, `safeRemove`).
- Improved error handling to distinguish race conditions from successful
removals.
- Added exponential backoff retry logic for cleanup operations.
- Updated `CLITest.swift` with missing `doRemove` method.
- Fixed `BuilderStart.swift` to handle `.stopping` case.
- Improved error messages with container ID for better debugging.
**Testing:**
- ✅ All tests pass (`make test`, `make integration`).
- ✅ Verified on macOS 26.
- ✅ Race condition test validates success and failure scenarios.
- ✅ Code formatted (`make fmt`).
Hopefully, this will pass the integration tests on GitHub.
Signed-off-by: ramsyana <47033578+ramsyana@users.noreply.github.com>
Implements a way for the CLI to wait until the IO streams from the
SandboxService have been drained before closing them.
Follows the same pattern as
https://github.com/apple/containerization/pull/110
This change also performs some cleanup in the
`SandboxService.startProcess` method - splitting the code paths to
handle the init process and an exec'd process into two different private
methods to make easier reading
---------
Signed-off-by: Aditya Ramani <a_ramani@apple.com>
This PR adds a warning that the performance may be degraded when running
a debug build.
Debug build:
```
% bin/container run -it --rm alpine:latest date
Warning! Running debug build. Performance may be degraded.
Fri Jun 13 18:10:35 PDT 2025
```
Release build:
```
% bin/container run -it --rm alpine:latest date
Fri Jun 13 18:10:35 PDT 2025
```
Closes https://github.com/apple/container/issues/126
This PR additionally removes the ability to set
`disable-progress-updates` for `container create` calls while we
investigate why output get jumbled there.
Signed-off-by: Kathryn Baldauf <k_baldauf@apple.com>
Container services can be started and stopped using the `system start`
and `system stop` commands. But there is no straightforward way for
users to check if the services were already started.
This PR adds a new `system status` command that shows wether the
container services are running or not.
The command only checks the status of the apiserver for now, but it
could be expanded in the future to show more details.
Fixes#117.
Replaces the `--install-dependencies` flag with the
`(enable/disable)-kernel-install` flag. If the flag is not passed - the
default behavior is prompting the user for a response.
Also adds a make target `install-kernel`
```
➜ bin/container system start
Verifying apiserver is running...
Installing base container filesystem...
No default kernel configured.
Install the recommended default kernel from [https://github.com/kata-containers/kata-containers/releases/download/3.17.0/kata-static-3.17.0-arm64.tar.xz]? [Y/n]: n
Please use the `container system kernel set --recommended` command to configure the default kernel
➜ bin/container system start --disable-kernel-install
Verifying apiserver is running...
➜ bin/container system start --enable-kernel-install
Verifying apiserver is running...
Installing kernel...
➜ bin/container system start --help
USAGE: container system start ... [--enable-kernel-install] [--disable-kernel-install]
...
--enable-kernel-install/--disable-kernel-install
Specify if the default kernel should be installed or not.
```
---------
Signed-off-by: Aditya Ramani <a_ramani@apple.com>
When a container that was writing stdout/stderr to its dedicated
container log file was stopped and started, there was a ~20 second - 1
minute delay from when the init process was restarted and when the
output of the process was written to the log file. This also meant there
was a delay when streaming those logs using `container logs -f`. The
logs from that delay period were lost.
This change forces the container log file to update state after a
container restart which fixes the delays to the container log file. And
the` container logs -f` stream resets its position in the file on a
container restart as well.
---------
Co-authored-by: Arnav Reddy <areddy23@apple.com>
This change updates the UX when we install required dependencies at
first launch
### Fresh install - respond `y` to prompt
```
➜ bin/container system start
Verifying apiserver is running...
Installing base container filesystem...
No default kernel configured.
Install the recommended default kernel from [https://github.com/kata-containers/kata-containers/releases/download/3.17.0/kata-static-3.17.0-arm64.tar.xz]? [Y/n]: y
Installing kernel...
```
### Fresh install - respond `n` to prompt and then run the provided
command
```
➜ bin/container system start
Verifying apiserver is running...
Installing base container filesystem...
No default kernel configured.
Install the recommended default kernel from [https://github.com/kata-containers/kata-containers/releases/download/3.17.0/kata-static-3.17.0-arm64.tar.xz]? [Y/n]: n
Please use the `container system kernel set --recommended` command to configure the default kernel
➜ bin/container system kernel set --recommended
Installing the recommended kernel from https://github.com/kata-containers/kata-containers/releases/download/3.17.0/kata-static-3.17.0-arm64.tar.xz...
```
### Fresh install - respond `n` to prompt and then run a container
```
➜ bin/container system start
Verifying apiserver is running...
Installing base container filesystem...
No default kernel configured.
Install the recommended default kernel from [https://github.com/kata-containers/kata-containers/releases/download/3.17.0/kata-static-3.17.0-arm64.tar.xz]? [Y/n]: n
Please use the `container system kernel set --recommended` command to configure the default kernel
➜ bin/container run alpine uname
Error: notFound: "Default kernel not configured for architecture arm64. Please use the `container system kernel set` command to configure it
```
---------
Signed-off-by: Aditya Ramani <a_ramani@apple.com>
The output now looks like the following
#### When build against a tagged HEAD in `RELEASE` mode
```
container --version
container CLI version 0.0.2 (build: release, commit: ed4a4cb)
```
Its a bit weird to have to pass `--http` when pulling / pushing images
if we are trying to do so from a local registry
This PR adds a `RequestScheme` enum type which tries to detect if the
connection to the registry should be over http or https. This auto
detection is the default behavior and can be overridden by passing the
`--scheme http/https` flag to the `run` ,`pull`, `push` `login` and
`registry default` command
The auto detection works by looking at the hostname / IP. HTTP is used
in the following cases
- If the hostname starts with `localhost` or is `127.x.x.x`
- if the host looks like an IP from the private address space
- If the host ends with the current default dns domain name
Also in this PR:
- Removing some used CLI flag groups and TODOs
- Better error messages when registry credentials are not found for a
host
Signed-off-by: Aditya Ramani <a_ramani@apple.com>
J Logan