# Admin

> Local machine administration for Windows, WSL, macOS, Linux. Install tools, check if software is installed, manage packages, configure dev environments. Works with winget, scoop, brew, apt, npm, pip, uv. Profile-aware: adapts to your preferences. Use when: install 7zip, is git installed, clone repo, check if node installed, add to PATH, configure MCP servers, manage dev tools, set up environment. NOT for: VPS, cloud servers, remote infrastructure → use devops skill.

- Skill: `evolv3-ai/admin` (Agent Skill, multi-file: 107 files)
- Install (CLI): `npx skillmds@latest add evolv3-ai/admin`
- Raw SKILL.md: https://api.skillmd.com/api/skills/evolv3-ai/admin/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: evolv3-ai (https://skillmd.com/u/evolv3-ai)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/evolv3-ai/admin

---


# Admin - Local Machine Companion (Alpha)

**Script path resolution**: When Claude Code loads this file, it provides the full
path. All `scripts/` references below are relative to this file's directory.
Derive `SKILL_DIR` from this file's path and prepend it when running scripts
(e.g., if loaded from `/path/to/skills/admin/SKILL.md`, run `/path/to/skills/admin/scripts/test-admin-profile.sh`).

---

## Profile Gate — Mandatory First Step

Check for a profile before any operation. No profile means no preferences, no logging path, no state.

**Bash (WSL/Linux/macOS):**
```bash
scripts/test-admin-profile.sh
```

**PowerShell (Windows):**
```powershell
pwsh -NoProfile -File "scripts/Test-AdminProfile.ps1"
```

Returns JSON: `{"exists":true|false,"path":"...","device":"...","platform":"..."}`

If `exists: false` — stop and run the TUI setup interview before proceeding.
Full details: `references/profile-gate.md` (discovery, TUI interview, create commands, troubleshooting).

### Fallback: When Scripts Fail

If both bash and PowerShell test scripts fail (e.g., shell not available, permission denied, script missing
from plugin cache), use native Claude tools to check directly:

1. **Check satellite .env** — Read `~/.admin/.env` to get `ADMIN_ROOT` and `ADMIN_DEVICE`
2. **Check profile JSON** — Read `$ADMIN_ROOT/profiles/$ADMIN_DEVICE.json`
3. If both exist, proceed normally using the values read from these files
4. If neither exists, run the TUI setup interview (see `references/profile-gate.md`)

---

## CRITICAL: Secrets and .env

- NEVER store live `.env` files or credentials inside any skill folder.
- `.env.template` files belong only in `assets/` within a skill.
- Store live secrets in `~/.admin/.env` and reference from there.

## Secrets Management (v4.0 — 3-Project Split)

Secrets are organized across **3 Infisical projects** by trust boundary, with folder hierarchies:

| Project | Trust Boundary | Contents |
|---|---|---|
| `admin-operator` | Operator | Provider keys, LLM tokens, Cloudflare, Google creds |
| `admin-runtime` | Runtime (scoped) | Agent bot tokens, deployment passwords |
| `customer-*` | Customer (isolated) | Per-customer OpenClaw config |

**4-layer model**: age key → vault (bootstrap) → Infisical Cloud (3 projects) → generated runtime files

**URI-based access** (new in v4.0):
```bash
resolve-secret-ref.sh "infisical://admin-operator/prod/providers/hetzner/HCLOUD_TOKEN"
secrets --project admin-operator --path /providers/hetzner HCLOUD_TOKEN
```

**Legacy CLI** (still works via fallback):
```bash
secrets HCLOUD_TOKEN          # Falls back through: generated/.env → Infisical → vault → .env
```

**Runtime rendering**: `render-runtime.sh` resolves all `secretRefs`/`fileRefs` from the profile and writes `$ADMIN_ROOT/generated/.env` for scripts that don't need live Infisical access.

**Guides**: `references/secrets-architecture.md` (full model), `references/infisical.md` (setup), `references/vault-guide.md` (fallback)

## Architecture

### Ecosystem Map

```
admin (core)
  ├── 9 satellite skills: devops, oci, hetzner, contabo, digital-ocean, vultr, linode, coolify, kasm
  ├── 7 agents: profile-validator, docs-agent, verify-agent, tool-installer, ops-bot, server-provisioner, deployment-coordinator
  ├── Profile system: ~/.admin/.env (satellite) → $ADMIN_ROOT/profiles/*.json (+ GitHub sync)
  └── Secrets: 3 Infisical projects (operator/runtime/customer) → vault (fallback) → .env (legacy)
```

### Data Flow

```
Satellite .env (bootstrap)  →  profile.json (device config)  →  Agent decisions
        ↓                              ↓                              ↓
  ADMIN_ROOT, DEVICE,          tools, servers, prefs,          Session logs
  PLATFORM, SECRETS_BACKEND    secretRefs, fileRefs            (~/.admin/logs/)
        ↓                              ↓
  generated/.env (pre-rendered) → Infisical (3 projects) → vault.age → .env
```

- **Satellite `.env`** (`~/.admin/.env`): Per-device bootstrap. Points to `ADMIN_ROOT`, configures secrets backend.
- **Root `.env`** (`$ADMIN_ROOT/.env`): Bootstrap only (ADMIN_ROOT, ADMIN_DEVICE, ADMIN_PLATFORM, ADMIN_SECRETS_BACKEND).
- **Profile JSON** (`$ADMIN_ROOT/profiles/{DEVICE}.json`): Full device config with `secretRefs` (URI pointers) and `fileRefs`.
- **Projects config** (`$ADMIN_ROOT/config/infisical-projects.json`): Project slug → ID mapping.
- **Generated** (`$ADMIN_ROOT/generated/.env`, `compat.env`): Pre-resolved secrets for scripts that don't need live Infisical access.

### Agent Roster

| Agent | Model | Role | Tools |
|-------|-------|------|-------|
| profile-validator | haiku | JSON validation, read-only health check | Read, Bash, Glob |
| docs-agent | haiku | File I/O documentation updates | Read, Write, Glob, Grep |
| verify-agent | sonnet | System health checks, no Write | Read, Bash, Glob, Grep |
| tool-installer | sonnet | Install software per profile prefs | Read, Write, Bash, AskUserQuestion |
| ops-bot | sonnet | Multi-step operations (migration, import, bulk config) | Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion |
| server-provisioner | sonnet | Cloud VM provisioning across providers | Read, Write, Bash, AskUserQuestion |
| deployment-coordinator | sonnet | End-to-end app deployments (Coolify, KASM) | Read, Write, Bash, AskUserQuestion |

All agents run the profile gate as their first step. See `references/agent-teams.md` for collaboration patterns.

### Satellite Dependency Graph

```
admin (core) ─── required by all satellites
  │
  ├── devops ─── required by provider + app skills
  │     │
  │     ├── oci, hetzner, contabo, digital-ocean, vultr, linode
  │     │        (provision servers)
  │     │              │
  │     └── coolify, kasm
  │           (deploy apps TO provisioned servers)
  │
  └── Profile system provides: server inventory, SSH keys, credentials (via vault)
```

- **admin**: Core profile, logging, tool installation. Required by everything.
- **devops**: Server inventory, SSH, deployment coordination. Required by all infrastructure.
- **Provider skills** (oci, hetzner, etc.): Provision VMs. Independent of each other.
- **App skills** (coolify, kasm): Deploy TO servers. Require a provisioned server from a provider skill.

## Task Qualification (MANDATORY)
- If the task involves **remote servers/VPS/cloud**, stop and hand off to **devops**.
- If the task is **local machine administration**, continue.
- If ambiguous, ask a clarifying question before proceeding.

## Task Routing

| Task | Reference |
|------|-----------|
| Install tool/package | references/{platform}.md |
| Windows administration | references/windows.md |
| WSL administration | references/wsl.md |
| macOS/Linux admin | references/unix.md |
| MCP server management | references/mcp.md |
| Skill registry | references/skills-registry.md |
| Secrets / Infisical setup | references/infisical.md |
| Vault (age encryption) | references/vault-guide.md |
| Profile sync (GitHub) | references/remote-profile.md |
| **Remote servers/cloud** | **→ Use devops skill** |
| devadmin onboarding / migration | references/devadmin-onboarding.md (`/adopt-devadmin`) |
| Skill bug escalation | references/escalation-policy.md |

## Profile-Aware Adaptation (Always Check Preferences)

- Python: `preferences.python.manager` (uv/pip/conda/poetry)
- Node: `preferences.node.manager` (npm/pnpm/yarn/bun)
- Packages: `preferences.packages.manager` (scoop/winget/choco/brew/apt)

Never suggest install commands without checking preferences first.

## Package Installation Workflow (All Platforms)

1. Detect environment (Windows/WSL/Linux/macOS)
2. Load profile via profile gate
3. Check if tool already installed (`profile.tools`)
4. Use preferred package manager
5. Log the operation

## Logging (MANDATORY)

Log every operation with the shared helpers.

**Bash** — params: `MESSAGE` `LEVEL` (INFO|WARN|ERROR|OK):
```bash
source scripts/log-admin-event.sh
log_admin_event "Installed ripgrep" "OK"
```

**PowerShell** — params: `-Message` `-Level` (INFO|WARN|ERROR|OK):
```powershell
pwsh -NoProfile -File "scripts/Log-AdminEvent.ps1" -Message "Installed ripgrep" -Level OK
```

**Note**: There are no `-Tool`, `-Action`, `-Status`, or `-Details` parameters. Use `-Message` with a descriptive string.

## Scripts / References

- Core scripts: `scripts/` (profile, logging, issues, AGENTS.md)
- MCP scripts: `scripts/mcp-*`
- Skills registry scripts: `scripts/skills-*`
- References: `references/*.md`

---

## Quick Pointers

- Cross-platform guidance: `references/cross-platform.md`
- Shell detection: `references/shell-detection.md`
- Device profiles: `references/device-profiles.md`
- PowerShell tips: `references/powershell-commands.md`
- Infisical secrets: `references/infisical.md`
- Remote profile sync: `references/remote-profile.md`
- devadmin onboarding/migration: `references/devadmin-onboarding.md` (run `/adopt-devadmin`)