Installation

This page describes safe installation flows. The installer is conservative: planning and dry-run previews are the default workflow, and real home-directory writes require both --apply and --real-system.

Native Windows mutation is temporarily fail-closed. Planning, prechecks, and dry-runs remain available, but install/apply, uninstall, rollback, OpenClaw target writes, and Antigravity settings writes are rejected until replacement and deletion operate against the same Windows handle used for reparse-point, owner, and DACL validation. WSL/Linux mutation of a mounted Windows profile is a different substrate and must follow its own mounted-profile safety policy.

Use make precheck or ./make.ps1 precheck first when installing on a new machine. The launchers detect a usable runtime instead of requiring a specific command name. Use plan before install. Partial installs are first-class: select --skill, --skills, or --profile. Artifact installs are also partial: select --artifact, --artifacts, or --artifact-profile.

doctor is a quick required-tool check. precheck is broader: it detects required tools, optional tools, Python packages, remote-service configuration placeholders, detected agents, skipped agents, ignored dependencies, target-specific prechecks, and Windows/WSL substrate information where possible. precheck --json includes target_prechecks for every requested or detected target. Each entry reports host-inspected home, skill, instruction, optional skill, artifact-directory, install-mode, and read-policy metadata; the path_style field labels the selected platform path convention but the path values remain paths inspected from the current host/root. Target prechecks do not read target file contents; known auth-token sources are reported by presence only rather than value. external_agent_prechecks reports sanitized Claude, DeepSeek, Copilot, Antigravity, Grok, Kimi, and reference-only OpenClaw delegation readiness, including latest-model/highest-thinking probe requirements and nested-worker capability status. Copilot extends the base precheck with CLI detection, the .copilot directory shape, redacted auth-source presence, provider/model probe status, delegation authority metadata, and a separate copilot_status field for CLI/account/model readiness; command arguments and version output are redacted.

delegate-agent is the live external CLI adapter for parent-owned cross-provider runs. Use delegate-agent --dry-run first; actual external process launch requires --allow-external-cli. Research launch is fail-closed unless a provider dispatch command and resolved latest-model/highest-thinking settings are available.

OpenClaw prechecks report the current fake-root-only gate and evidence requirements without enabling real .openclaw writes.

OpenClaw real-system runtime install (advanced, evidence-gated): runtime-backed skills can be installed to a real OpenClaw host through a separate fail-closed flow, distinct from the v2 skill-file path. The sequence is openclaw-runtime-probe (mint native-loader/quiescence/neutral-root evidence on a quiescent host), openclaw-runtime-dry-run-manifest (build a content-addressed runtime manifest), openclaw-runtime-approve-manifest, then openclaw-runtime-apply-manifest --real-system with the confirmation phrase and verify-before-write. Apply writes inert support files under .openclaw/skills/<skill>/ and executable runtime files under a validated neutral runtime root outside .openclaw. Executable files are not run inside the OpenClaw sandbox; the host openclaw-broker (started with --serve, a per-agent capability token file, and a managed host firewall rule) exposes them to the sandboxed agent with per-agent tokens and verify-before-exec. This path is optional and host-gated; the default remains fake-root-only. OpenCode prechecks report the user-global ~/.config/opencode target, OpenCode-native artifact directories, copy-mode default, and native smoke expectations without reading config contents or credentials. Antigravity prechecks report the user-global ~/.gemini/antigravity-cli target, flat global skill directory, managed plugin payload, sparse settings file, plugin-scoped MCP config, plugin-scoped hooks config, agy CLI discovery status, and native smoke expectations without reading config contents or credentials. Grok prechecks report the user-global ~/.grok target, its skills/, agents/, commands/, rules/, and hooks/ children, config.toml and AGENTS.md, copy-mode default, bare grok CLI discovery status, and GROK_HOME-pinned native smoke expectations without reading config contents or credentials; ~/.grok/settings.json is not reported because Grok does not read it for hooks. Kimi prechecks report the user-global ~/.kimi-code target, its skills/ and agents/ children, AGENTS.md, copy-mode default, bare kimi CLI discovery status, and KIMI_CODE_HOME-pinned native smoke expectations without opening config.toml for secrets. Relocated KIMI_CODE_HOME installs are unsupported. audit-system is read-only and compares the selected repo profile with the current agent homes, managed state, legacy aliases, unmanaged files, dependency status, and install-plan summaries.

Before running installer commands, clone the repository and run commands from the repo root. The launchers need Python 3.10 or newer. On Linux and macOS, use make or ./installer/bootstrap.sh; on Windows, use ./make.ps1, which requires pwsh or powershell.exe. The direct Python entrypoint is useful for debugging wrapper behavior:

python3 -m installer.ai_agents_skills help
python3 -m installer.ai_agents_skills describe zotero

Restored runtime secret projection

Managed runtime skills can receive restored API credentials from a strict launcher-only env file. Set AAS_SKILL_SECRETS_FILE to an explicit absolute path before invoking run_skill.sh or run_skill.ps1. The file accepts only comments, blank lines, and unique non-empty KEY=value records for AXLE_API_KEY, LEANEXPLORE_API_KEY, OCR_SPACE_API_KEY, OCR_SPACE_KEY, OCRSPACE_API_KEY, OCRSPACE_KEY, OPENCLAW_S2_API_KEY, PATENTSVIEW_API_KEY, SEMANTIC_SCHOLAR_API_KEY, UNPAYWALL_EMAIL, and ZENODO_TOKEN.

The loader does not shell-source or evaluate the file. It rejects relative or linked paths, oversized or multiply linked files, unknown/duplicate/empty records, and unsafe permissions without printing values. On POSIX the file must be owned by the effective user with mode 0600 (or stricter). On Windows the PowerShell loader requires current-user ownership, allows access only to that user, SYSTEM, and Administrators, and rejects reparse points before and after its bounded read. The resulting values override inherited values only in the managed launcher/child process tree; they are not exported back into the calling shell.

Autonomous research-loop provider fallbacks use the separate AAS_PROVIDER_SECRETS_FILE launcher pointer documented in the force-loop operator runbook. This keeps general skill credentials distinct from provider credentials and lets strict primary and panel children receive only their selected provider’s explicit allowlist. Both the default force-loop and the advanced direct drive wrappers consume that pointer.

Broker-routed compute uses AAS_COMPUTE_SECRETS_FILE, whose protected env file accepts exactly HCLOUD_TOKEN, HCLOUD_SSH_KEYS, KAGGLE_API_TOKEN, and KAGGLE_CONFIG_DIR. The managed unified-broker and standalone Hetzner wrappers consume it directly, and ARL drive passes only host-pinned eligible lane keys to an attested primary. Keep both pointers in the launcher environment, never in agent-writable loop env files or job manifests.

Use list-skills, list-artifacts, describe, and describe-artifact to inspect manifest content without planning writes. Use make docs to regenerate generated docs and make docs-site to build the Sphinx site after installing docs/requirements.txt.

Use precheck --interactive for a guided one-by-one pass through missing dependencies. It does not install packages automatically; it shows the install hint, lets the user skip or ignore a dependency, and tells them to rerun precheck after installing software.

install --dry-run previews the same actions as a default install preview; install --apply is required before any writes occur. Applied installs, uninstalls, and rollbacks are interactive: before writing files, the installer explains the install, uninstall, and rollback process and requires the user to type the displayed confirmation phrase. Real home-directory writes additionally require --real-system.

After a successful install --apply, the installer runs post-install smoke in auto mode. That means it verifies managed installer state, checks agent-visible skill files, and runs offline runtime smoke for selected runtime-backed skills with safe smoke contracts. When OpenCode is selected and the opencode CLI is available, it also runs isolated native discovery smoke for OpenCode paths, skills, and agents. When Antigravity is selected and the agy CLI is available, it runs isolated native smoke for agy --help, agy plugin list, global skill file shape, plugin manifest, MCP config, hook config, and settings scaffolds. These checks write a bounded report under .ai-agents-skills/runs/ and use temporary scratch directories for runtime outputs. They do not configure credentials, start servers, install packages, or call live services. Antigravity MCP and hook files are no-op JSON scaffolds unless a future manifest declares live entries. Use --post-install-smoke strict in automation to make degraded smoke fail the command, --post-install-smoke verify for integrity-only checks, or --post-install-smoke off to skip post-install checks.

Safe First Install

Linux:

make doctor
make precheck ARGS="--profile research-core"
make plan ARGS="--profile research-core"
make install ARGS="--profile research-core --dry-run"
make lifecycle-test ARGS="--matrix default --platform-shape all"

Windows:

./make.ps1 doctor
./make.ps1 precheck --profile research-core
./make.ps1 plan --profile research-core
./make.ps1 install --profile research-core --dry-run
./make.ps1 lifecycle-test --matrix default --platform-shape windows

To test file writes without touching a real agent home, use a fake root:

make lifecycle-test ARGS="--matrix default --platform-shape all"
make fake-root-lifecycle ARGS="--profile research-core --platform-shape linux"
make fake-root-lifecycle ARGS="--profile research-core --platform-shape all"

Fake-root plans detect only agent homes that exist under the fake root. Create .codex, .claude, .deepseek, .copilot, .config/opencode, .gemini/antigravity-cli, or .openclaw inside the fake root for the agents you want to exercise; a fake root with no agent homes produces no install actions, no managed installer state, and later verification may report no-managed-artifacts.

Real-system writes should be a final step after reviewing plan output:

make install ARGS="--profile research-core --apply --real-system"
make install ARGS="--profile research-core --apply --real-system --post-install-smoke strict"

Closure-Complete Non-OpenClaw Restore

complete-restore expands to every skill declared by the checked-out repo revision, including skills added in future revisions. workflow-artifacts is the exhaustive portable artifact bundle, and --runtime-profile full installs all declared portable runtime files. Exact target and complete-action enforcement prevent a mistyped/missing agent home or unresolved target conflict from becoming a false-success partial restore. Explicit platform-inapplicable support files and Antigravity aliases that collide with the managed skill surface remain visible as declared neutral exclusions:

export AAS_RESTORE_AGENTS="codex,claude,deepseek,copilot,opencode,antigravity,grok,kimi"
make precheck ARGS="--agents $AAS_RESTORE_AGENTS --profile complete-restore --artifact-profile workflow-artifacts --runtime-profile full --require-all-requested-agents"
make plan ARGS="--agents $AAS_RESTORE_AGENTS --profile complete-restore --artifact-profile workflow-artifacts --runtime-profile full --require-all-requested-agents"
make install ARGS="--agents $AAS_RESTORE_AGENTS --profile complete-restore --artifact-profile workflow-artifacts --runtime-profile full --require-all-requested-agents --require-complete-install --apply --real-system --post-install-smoke verify"

The integrity-only post-install mode is appropriate when an outer restoration workflow installs the declared software/Python closure immediately afterward. Once that closure is present, run make installed-runtime-smoke ARGS="--require-complete-coverage"; it requires every declared runtime skill to be managed, executes every offline contract from a verified scratch copy, neutrally reports declared manual-native, doctor-only, and static-only exclusions, and fails on unknown coverage.

OpenClaw is deliberately absent from the command above. Real OpenClaw writes remain delegated to its separate reviewed component and manifest workflow; this complete-restore flow does not write .openclaw.

Runtime Files

--runtime-profile auto is the default. When a selected skill has declared portable runtime files, the installer copies those files into a runtime root and records them as root-scoped runtime-file artifacts. They are not installed inside each agent’s skill directory. Use --no-runtime or --runtime-profile none to skip runtime files, and use --runtime-root to choose a non-default runtime location.

Default runtime roots:

• Codex-only installs: <root>/.codex/runtime

• Windows multi-agent or non-Codex installs: <root>/AppData/Local/ai-agents-skills/runtime

• Linux/macOS multi-agent or non-Codex installs: <root>/.local/share/ai-agents-skills/runtime

Before promoting files from an existing local runtime into this repo, inspect that source with the read-only inventory command:

python3 -m installer.ai_agents_skills --json runtime-inventory --source-root <runtime-root>

The inventory denies configs, databases, caches, downloaded documents, SQLite sidecars, symlinks, personal paths, sensitive material, and persistence markers such as cron, systemd, launchd, scheduled tasks, and Docker restart: unless-stopped.

Runtime-backed skill config should be a local live file under the installed runtime workspace or passed explicitly, not a canonical runtime source file. For Docling, start from the tracked docling.example.toml, then place the live config at $AAS_RUNTIME_WORKSPACE/config/docling.toml or pass it with --config. The inventory allows example config templates but denies live config.toml, workspace/config/*.toml, caches, bytecode, and downloaded documents so credentials and local state are not accidentally promoted.

self-improving-agent also uses the shared runtime for its portable helpers. Use those runtime commands instead of paths inside an agent skill directory: reference install mode deliberately points back to the canonical repo and does not copy support files. The helper smoke contract is offline and checks the learning review, command-safety, error-detection, and integration-plan command surface without reading credentials or live config.

Install Modes

--install-mode auto is the default. The installer resolves that request per agent based on recorded agent-loader policy and source availability, and it records the reason in plan --json. Symlink creation itself is verified during apply; if a symlink cannot be created, skill files fall back to reference adapters and support files fall back to copied files.

Codex, DeepSeek, Copilot, OpenCode, and Antigravity are compatibility exceptions. Current Codex skill discovery loads regular user SKILL.md files but ignores file-symlinked user SKILL.md files, so auto mode copies complete Codex skill trees rather than retaining a source-checkout dependency. DeepSeek native symlinked SKILL.md loading has not been verified. Copilot agent skills are regular SKILL.md files in ~/.copilot/skills or .github/skills; symlinked skill loading is not assumed. OpenCode native skills are regular files under ~/.config/opencode/skills, and auto mode copies canonical skill files plus support files for cross-platform parity. Antigravity global skills are flat Markdown files under ~/.gemini/antigravity-cli/skills/<skill>.md, so auto mode copies the full canonical skill body into that native global skill directory and creates the managed Antigravity plugin/config scaffolds. In default auto mode, Codex, OpenCode, and Antigravity resolve to copy mode, while DeepSeek and Copilot resolve skill files to reference adapters that point at the canonical repo skill. plan --json shows the effective install_mode, mode_reason, capability_evidence, and fallback mode for each target before anything is written.

Use --install-mode symlink to force symlinked skill files for every agent. This is useful for testing future loader behavior, but it can produce Codex skill targets that current Codex will not discover.

Use --install-mode reference for agents or environments that should not load symlinked skills. This mode writes a thin adapter into every agent settings directory, using SKILL.md for directory-shaped targets and <skill>.md for Antigravity. The adapter tells the agent where the canonical repo skill file is and does not copy support files. If a previously managed skill is switched to reference mode, obsolete managed support files may be planned for removal because the adapter now points back to the repo copy.

When targeting a mounted Windows profile from Linux or WSL, verify that the reference path written into the adapter is readable by the target agent runtime. If the agent actually runs on native Windows and cannot read the POSIX repo path, use a native Windows checkout or --install-mode copy.

Use --install-mode copy only when the agent must have regular files inside its settings directory. Copy mode materializes skill files and support files with managed metadata, so it uses more space and needs reinstalling after repo skill changes.

Optional artifacts outside skill directories are always copied because agents do not load them as canonical skill source.

Selection Model

• --profile research-core selects a workflow bundle.

• --skill zotero selects one skill.

• --skills zotero,docling selects a comma-separated skill set.

• --no-skills --artifact-profile workflow-templates installs only optional artifacts.

• --with-deps lets dependency-bound artifacts bring in their backing skills.

See Profiles, Skills, and Optional Artifacts for the available selectors.

Conflict Modes

• default: create missing managed files and skip unmanaged or legacy files

• --adopt: record an existing target file as user-owned managed state; verify tracks its recorded hash instead of requiring managed marker text

• --backup-replace: back up and replace an unmanaged target file

• --migrate: install a detected legacy skill under the canonical name using the selected install mode, then back up and remove the legacy alias directory

Instruction blocks are installed only when the corresponding skill artifact is actually installed, adopted, updated, already managed, or migrated. A skipped skill does not receive an AGENTS.md or CLAUDE.md block.

Optional artifacts are not installed by default. Use --no-skills when you want an artifact-only install. Use --with-deps when selected dependency-bound artifacts should bring in their required backing skills.

For an existing personal system, prefer staged migration:

1. Run precheck --profile full-research.

2. Run audit-system --profile full-research.

3. Review plan --profile full-research --migrate for legacy aliases.

4. Review plan --profile full-research --adopt for canonical files that already exist but are not managed.

5. Apply one small selected scope at a time, then run verify.

Use --artifact-profile repo-management when you want a top-level managed notice in AGENTS.md or CLAUDE.md without installing every skill.

Scenario summary:

Scenario	Result
Agent home absent	Agent is skipped; its dependencies are not required.
Skill absent	Managed skill files and support files are created.
Skill already managed	Files are updated or left unchanged according to hashes.
Skill exists unmanaged	Default plan skips it; use --adopt or --backup-replace explicitly.
Legacy alias exists	Default plan skips; --migrate installs the canonical target, backs up the legacy alias directory, and removes the legacy alias directory.
Agent rejects symlinked skills	Auto mode already resolves Codex, OpenCode, and Antigravity skill files to copied regular files, while DeepSeek and Copilot use reference adapters. Use --install-mode reference to force adapters for every agent or copy for a self-contained install.
Top-level management notice selected	Adds a removable managed block explaining repo/source ownership boundaries.
Dependency-bound artifact selected without dependency	Artifact is blocked and skipped until the backing skill is managed or selected with --with-deps.
Persona selected	Codex gets TOML, Claude and OpenCode get Markdown frontmatter, Antigravity gets plugin-scoped Markdown frontmatter, Copilot gets .agent.md, and DeepSeek gets a reference prompt.
Windows SageMath	Prefer WSL-backed detection when native SageMath is absent.

Related pages: Dependencies, Audit And Migration, Verification, Troubleshooting.