Run project commands and aidcx doctor in a Linux terminal. On macOS or Windows, prepare the runtime with native aidcx install, then open aidcx terminal and use a project cloned in that Linux environment. Native installation, update and uninstall remain host commands; macOS aidcx bridge also runs on the Mac.
Scaffold once, review, then start.
aidcx scaffold writes the project's devcontainer configuration from a template and the options you pass. The result always requests the secure runtime. On a host that cannot run it, scaffold stops and writes nothing. An existing file that is not a MAIT project, or that turns the secure runtime off, is refused.
On a terminal, review the feature checklist before writing the file. A fresh scaffold enables systemd and an inner Docker daemon; audio, USB and mesh start off. Explicit flags override those choices, including with --force or without a terminal. An existing file retains its saved choices. Review runtime, host access and shared tool state before the first start; see the complete defaults. Ordinary configuration patches keep a .bak backup, but an image-version-only update does not guarantee one. Commit or copy the existing file before changing it.
The same options work on aidcx start, where they apply to that run only. On scaffold they are saved into the file.
What each flag decides.
| Flag | Values | Fresh scaffold choice | Use it to |
|---|---|---|---|
--systemd | on, off | a fresh scaffold writes on | Run systemd inside the container. Audio and libvirt turn it on |
--dockerd | off, on, host | on | on runs a Docker daemon inside the container. host gives the container access to the host Docker daemon and its authority. Review that exposure whether or not a warning appears; prefer on |
--x11 | on, off | on | Forward graphical applications to your display |
--gpu | on, off, auto, dri, dxg, nvidia, rocm, software | auto | Choose GPU access. A positive choice does not prove acceleration works |
--audio | off, on, host, bridge | off | host relays your microphone and speakers, on gives virtual devices only |
--usb | off, on, dynamic | off | dynamic attaches devices at run time with aidcx feature usb attach; unavailable on macOS and Windows |
--aidev | on, off | on | Share the state of the supported agent CLIs from your computer |
--sso | on, off, dev or a list of git, docker, kube | on | Choose which sign-ins are shared: dev is Git, Docker and Kubernetes. Agent tools are shared with --aidev, not --sso |
--kvm, --libvirt | see the reference | a fresh scaffold writes on where supported | Enable virtualization; --libvirt on requires KVM |
--distro | auto, ubuntu-26.04, ubuntu-24.04 | auto | Pick the Ubuntu base. On start it is advisory; re-scaffold to change it |
These choices apply when scaffold creates a new configuration. Existing files retain their saved values; an omitted option can have a different fallback, listed in the feature reference.
The runtime layers nest: the secure runtime, then systemd, then a Docker daemon, and a higher layer includes the lower ones. Contradictions, such as --systemd off with --audio on, stop before any work and name both flags.
Settings you keep outside the project.
Settings come from an environment variable, then the file ~/.mait/aidcx.yaml, then a built-in default. In the file, write the variable name without the AIDCX_ prefix.
| Variable | Default | Effect |
|---|---|---|
MAIT_CHANNEL | the channel recorded at install, else stable | stable, edge or beta: selects the MAIT services and the versions you see |
AIDCX_DEBUG, AIDCX_VERBOSE | off | More output, like --debug and --verbose |
AIDCX_LIMA_CPUS, AIDCX_LIMA_MEMORY, AIDCX_LIMA_DISK | 4, sized from host memory, 60 GB | Size of the managed Mac virtual machine, applied when it is created |
AIDCX_WSL_DISTRO | Mait | Name of the managed WSL2 distribution on Windows |
AIDCX_AUDIT_LOG_PATH | ~/.aidcx/audit.log | Where the append-only audit log is written |
Changing the virtual machine settings later does not resize an existing machine. Review diagnostic output before sharing it, and remove credentials, private project details and other sensitive values. Avoid commands that print secrets. The feature flags and settings reference lists every variable, including the Kubernetes target.