Networking

Networking controls how containers become reachable from your Mac and how containers or Blueprint components discover each other. Start with port publishing for host access. Use network scopes when workloads need intentional grouping, discoverability, or isolation.

Command Reference

Command	Description	Typical use
`mactain container start --publish <host:container[/proto]>`	Publishes a container port to the Mac host.	Reach a service from a browser or client on your Mac.
`mactain container create --network-scope <scope>`	Defines a standalone container in one or more scopes.	Put a container into an app-specific network group at creation time.
`mactain container create --network-scope-isolation`	Enables scope isolation for a standalone container.	Block out-of-scope IP access when isolation matters.
`mactain network scope create <name>`	Creates a shared network scope.	Prepare a group for related containers or Blueprint components.
`mactain network scope list`	Lists network scopes.	See available scopes before reusing or deleting one.
`mactain network scope delete <name>`	Deletes a scope.	Remove an unused shared network boundary.
`mactain network membership attach`	Attaches containers or members to a scope.	Add existing containers to a shared discoverability boundary.
`mactain network membership detach`	Removes members from a scope.	Stop a container from participating in a scope.
`mactain network membership list`	Lists scope memberships.	Troubleshoot service discovery and scope membership.
`mactain system dns list`	Shows configured local domains and resolver health.	Diagnose local domain resolution.
`mactain system dns default show`	Shows the default local domain.	Confirm which domain MacTain uses by default.

Defaults And Behavior

For host access, start with --publish; network scopes are not required for one standalone web service.
Standalone containers use the default network unless you assign a scope.
Scope names are explicit user-defined boundaries. Use app-specific names such as media-stack or inventory-dev when the scope belongs to one workflow.
Reusing a scope can allow intentional cross-container or cross-Blueprint connectivity.
Unique scope names are the safer default when workloads should stay isolated.
--network-scope-isolation blocks out-of-scope IP access for that standalone container.
Scope membership can target standalone containers with --container and Blueprint components with --blueprint-member <blueprint-app-id:component-id>.
--discoverable marks a membership for service discovery; use --not-discoverable when the member should share connectivity without being advertised for name-based discovery.
Creating or deleting local DNS resolver entries can require admin privileges.

Secure Egress

Use Secure Egress when selected containers must route public traffic through a saved WireGuard VPN connection. Secure Egress works with Network Scopes: a protected container can retain approved same-scope service discovery, reverse-proxy ingress, and intentional host-port publishing without receiving a second public egress route.

Practical Use Cases

Use case: expose a container on localhost

Use this when you want to open a browser or client on your Mac and reach a service running inside a container. The host port comes first; the container port comes second.

mactain container start \
  --name web \
  --image docker.io/library/nginx:latest \
  --publish 8080:80 \
  --detach
mactain container status web

Open http://localhost:8080. If that does not work, check container logs and confirm the application listens on the container port you published.

Use case: group related containers into a private app scope

Use this when an app has multiple containers that should find each other, such as web, api, and db. Create a scope, attach containers to it, then list memberships.

mactain network scope create myapp
mactain network membership attach \
  --scope myapp \
  --container web,api,db \
  --discoverable
mactain network membership list --scope myapp

Use a unique scope name per app when isolation matters. Reusing a scope can allow cross-app connectivity.

Use case: attach a Blueprint component to a shared scope

Use this when a Blueprint component needs to communicate with an existing standalone service or another Blueprint app through an intentional shared boundary.

mactain network scope create shared-dev
mactain network membership attach \
  --scope shared-dev \
  --blueprint-member myapp:api \
  --discoverable
mactain network membership list --scope shared-dev --json

The Blueprint member target uses <blueprint-app-id:component-id>. Keep the scope unique unless cross-app connectivity is intentional.

Use case: create and start a container directly in a scope

Use this when you are defining a standalone container and already know which scope it belongs to.

mactain container start \
  --name api \
  --image ghcr.io/acme/api:latest \
  --network-scope myapp \
  --network-scope-isolation \
  --detach
mactain network membership list --container api

--network-scope-isolation blocks out-of-scope IP access for that standalone container. Use it when a service should only talk to its intended scope.

Use case: inspect local DNS configuration

Use this when service names or local domains do not resolve as expected.

mactain system dns list
mactain system dns default show

Creating or deleting resolver entries can require admin privileges.

Use case: detach a container before deleting a scope

Use this when a temporary shared scope is no longer needed.

mactain network membership detach \
  --scope myapp \
  --container web,api,db
mactain network scope delete myapp

List memberships first if you are not sure which containers or Blueprint members still participate in the scope.

When To Use Scopes

Use scopes when you need one of these outcomes:

Make a group of related containers discoverable to each other.
Keep app-specific connectivity separate from other local workloads.
Share an intentional network boundary across Blueprint components.
Inspect which containers or Blueprint members belong to a network group.

Do not start with scopes for every one-off container. For a single web service, publish the port first. Add scopes when there is a second service, a discoverability requirement, or an isolation requirement.

Troubleshooting Entry Points

Service is not reachable from the host: confirm --publish, container status, and application port.
Service is not reachable from another component: check scope membership and discoverability.
DNS change fails: confirm whether the command requires admin privileges.
Unexpected cross-workload access: check whether two workflows reuse the same scope name.

Next Steps

Continue to Secure Egress for protected container traffic, then Volumes to make application data persistent.