Using container for an opt-in SearXNG backend in a native macOS app

[NakliTechie]

I’m building Summon, an open-source native macOS launcher distributed through its own Homebrew tap. It has no account, no application server, and no telemetry.

Summon offers current-web search through an opt-in SearXNG instance. After explicit user consent, the app:

1. reuses Docker when it is already installed;
2. otherwise installs Apple container through Homebrew;
3. starts the container system;
4. pulls the SearXNG OCI image;
5. runs the service with its API bound to loopback;
6. health-checks the endpoint and stores the discovered local URL.

The loopback boundary keeps the SearXNG API local to the Mac. SearXNG still sends the user’s consented query to its configured upstream search engines;

This has been a useful consumer-app use case for container: an optional service gets per-container VM isolation without requiring Docker Desktop. The app currently shells out to the CLI because that is the clearest documented integration boundary.

I would value guidance on four points:

1. Is the CLI the recommended integration boundary for a third-party app today?
2. The technical overview says the CLI uses a client library to communicate with container-apiserver. Is that client library intended as a supported application API, or is it an implementation detail?
3. For a resident app, what lifecycle pattern is recommended for crash recovery and explicit teardown without surprising background activity?
4. What storage-management approach is recommended for an app-owned OCI image and per-container VM when the user disables the feature?

Relevant implementation:

• Installer: https://github.com/NakliTechie/summon/blob/main/Sources/SummonCore/WebSearchInstaller.swift
• Runtime script: https://github.com/NakliTechie/summon/blob/main/packaging/searxng/searxng-up.sh
• Search client: https://github.com/NakliTechie/summon/blob/main/Sources/SummonCore/WebSearch.swift

Apple documentation I used:

• https://github.com/apple/container/blob/main/docs/technical-overview.md
• https://github.com/apple/container/blob/main/docs/tutorial.md

[pulkitxm]

I maintain ac, a CLI and project runner built on Apple container, so I’ve been working through similar lifecycle questions.

For the integration boundary, I’d stick with the CLI for now and test against the versions you support. ContainerAPIClient is actually exported as a library in Package.swift, so it is available to consume. That alone doesn’t establish a compatibility guarantee for third-party apps, though. I’d leave that part for the maintainers to confirm.

One concrete thing I’d change in your startup script: the Apple path force-removes the named container whenever the initial endpoint check fails. A failed health check could mean the service is temporarily unhealthy or the saved URL is stale. I’d inspect the existing container first, reuse it if healthy, start it if stopped, and only recreate it when its configuration changes or an explicit recovery requires it. Keep its logs available when startup fails.

For crash recovery, persist the user’s enabled/disabled preference separately from the observed container state. On app launch, reconcile the two. That lets you recover an enabled service without accidentally restarting one the user disabled. Use bounded retries with backoff, and cancel pending startup/recovery work when disabling the feature.

Treat the shared runtime separately from your service. Disabling SearXNG should stop your container; it shouldn’t automatically call container system stop. Even if your app originally started the runtime, another tool may have begun using it since.

For storage, I’d offer two actions:

• Disable: stop the service and retain its settings/data.
• Remove local backend: remove the app-owned container and explicitly selected persistent data. Make image cleanup optional, since images and layers can be shared. Use the runtime’s removal commands rather than deleting its storage directories directly.

Some of this is already implemented in ac: declarative service definitions, readiness checks, JSON state output, and recorded daemon ownership. It leaves a runtime that was already running alone, and ac <project> down removes the project’s containers while preserving volumes. The lifecycle documentation may be useful as a reference even if you keep Summon’s integration directly on the Apple CLI.

[NakliTechie]

Thanks, this is useful. I checked Summon against your points: the Apple path does force-remove the named container on a failed health check, and there is no launch-time reconcile between the saved preference and the observed container state. Both are going into the next change, along with a Disable / Remove split and surfacing startup logs on failure. The integration stays on the CLI.