mait.sh1.69.2

Private beta: features and content may change. No warranty; use at your own risk.

Docs / Launcher and command-line tools

AIDC Init

Start a Linux development container with the intended user identity and access to its configured files.

For devcontainer authors and platform engineers maintaining portable workspace images.

Read from the top for the basics; the later sections go deeper.

Beta
All components

What it doesBasics

  • Host user and group mapping
  • Home-directory mount ownership preparation
  • Mode-aware privilege handling
  • Devcontainer build and run phases
  • Systemd, secure-runtime, and Docker capability coordination

First useBasics

  1. Use a prepared image and verify the running user and access to one project file.
  2. Runtime intent is resolved from the feature configuration.
  3. Identity and mounts are reconciled before the developer command runs.

Everyday tasksEveryday use

Initialize a secure development container

A workspace needs system services and an isolated inner Docker daemon without exposing the host Docker socket.

  1. Configure the devcontainer feature with the secure runtime and required service capabilities.
  2. Let the launcher resolve host-specific mounts, groups, and devices before container creation.
  3. Allow AIDC Init to reconcile identity and mount ownership, then start the selected init system and services.
  4. Enter the workspace as the intended user and verify Docker and process state inside the boundary.

What you getThe developer receives a usable non-root workspace with the requested in-container service posture.

How to check: Identity and ownership checks match the requested IDs; process state shows the selected init path; Docker reports the inner daemon rather than an unmediated host socket.

Use the image as a plain container entry point

An image consumer needs predictable user and mount preparation without the complete devcontainer lifecycle.

  1. Pass explicit identity and phase configuration to the container.
  2. Mount only the paths the workload needs and provide a concrete final command.
  3. Let AIDC Init prepare identity and eligible home-directory entries without enabling unrelated runtime services.
  4. Verify the command runs as the intended user and exits with its own status.

What you getThe container starts its requested workload after consistent identity preparation, without assuming a full interactive workspace.

How to check: The final process user and group, mounted-path ownership, environment, and exit status match the declared container contract.

Settings to decideAdvanced

Declare container identity
Choose the intended user and group IDs deliberately so created files remain usable across the workspace boundary. Resolve collisions in the image rather than accepting ambiguous ownership.
Select secured, systemd, and Docker capabilities together
Treat these options as a coordinated runtime posture. Enable only supported combinations and use an inner daemon when the secure workspace needs Docker workloads.
Choose build or runtime initialization
Keep image-build preparation distinct from container-run reconciliation. Runtime-only host identity and mounts should not be baked into a reusable image layer.
Keep host resources launcher-owned
Declare capability intent in the feature configuration and let the host launcher supply applicable devices, groups, mounts, and environment rather than hard-coding one host’s values.

CommandsAdvanced

$ aidc-init --version
$ aidc-init setup --devcontainer-build --user <name>
$ aidc-init setup --devcontainer-run
$ aidc-init entrypoint -- <command>

Problems and fixesHelp

What you seeCheckFix
Startup cannot create or remap the requested user or group, or files have unexpected ownership.Compare requested IDs with the image’s existing account and reserved group ranges, then inspect ownership of each mounted path.Choose a non-conflicting identity or correct the image account layout, then recreate the container so reconciliation starts from a known state.
Systemd, secure runtime, or inner Docker does not start in the selected combination.Confirm the three capability selections and verify that the outer container runtime supports the requested posture.Use a documented combination and ensure the host launcher provisioned the secure runtime before recreating the workspace.
GPU, display, audio, USB, KVM, or libvirt capability is declared but unavailable inside the container.Inspect launcher diagnostics for host applicability and confirm the required device, mount, group, and environment were supplied.Correct the host-side capability selection to match what the host provides.
What you see
Startup cannot create or remap the requested user or group, or files have unexpected ownership.
Check
Compare requested IDs with the image’s existing account and reserved group ranges, then inspect ownership of each mounted path.
Fix
Choose a non-conflicting identity or correct the image account layout, then recreate the container so reconciliation starts from a known state.
What you see
Systemd, secure runtime, or inner Docker does not start in the selected combination.
Check
Confirm the three capability selections and verify that the outer container runtime supports the requested posture.
Fix
Use a documented combination and ensure the host launcher provisioned the secure runtime before recreating the workspace.
What you see
GPU, display, audio, USB, KVM, or libvirt capability is declared but unavailable inside the container.
Check
Inspect launcher diagnostics for host applicability and confirm the required device, mount, group, and environment were supplied.
Fix
Correct the host-side capability selection to match what the host provides.

All AIDC Init problems and fixes →

Good to knowHelp

  • It configures container startup inside the outer boundary that the launcher and selected runtime enforce.
  • Ordinary entrypoint modes drop privilege before the user command runs; in systemd mode, systemd runs as PID 1.
  • Mount preparation sets ownership on eligible root-owned directory entries beneath the configured home.