Magicbox

dk — orchestrateur d'environnement de développement pour les services et archétypes DigitalKin.

Magicbox pilote Docker Compose à partir d'un profil YAML par scénario de dev. Une seule CLI (dk), un profil décrit ce que vous voulez faire tourner (front, services, infra, archétypes, kins) et comment (version distante, clone git, ou dépôt local), et Magicbox génère les composes, résout l'environnement, alloue les ports et démarre la stack — le tout stocké hors du repo, dans le dossier de config standard de votre OS.

Sommaire

• Installation
• Démarrage rapide
• Concepts
• Commandes
• Organisation des fichiers (config_root)
• Le profil
• Settings, globals & credentials
• Multi-profils
• Claude Code (MCP)
• Auth git
• Versioning & release
• Dépannage
• License

Installation

Magicbox est un outil en ligne de commande : installez-le dans un environnement isolé avec uv ou pipx pour exposer la commande dk globalement (sans polluer votre Python système).

uv tool install magicbox-dk      # recommandé (uv)
# ou
pipx install magicbox-dk         # équivalent pipx

La CLI expose deux entrypoints équivalents : dk (court) et digitalkin. Python ≥ 3.10 requis, et un démon Docker avec le plugin Compose v2 en état de marche (dk doctor vérifie tout ça).

Mettre à jour ou désinstaller :

uv tool upgrade magicbox-dk      # ou: pipx upgrade magicbox-dk
uv tool uninstall magicbox-dk    # ou: pipx uninstall magicbox-dk

Tester sans installer globalement : uvx --from magicbox-dk dk --help. Installer une pré-release (.devN) : uv tool install "magicbox-dk==X.Y.Z.devN" (ou pipx install --pip-args=--pre magicbox-dk).

Complétion shell

dk --install-completion zsh      # ou bash ; puis ouvrir un nouveau terminal

Les noms avec espaces s'insèrent entre quotes ('ADA & SDK - Litmus'), la casse est ignorée, les aides sont alignées, et les services / clones proposés suivent le profil visé sur la ligne (-p, --id, profil positionnel). Complétion installée avec une version antérieure : relancez dk --install-completion zsh pour que le premier TAB d'un nouveau terminal complète (sinon il ne fait rien, les suivants marchent).

Depuis les sources (dev)

Le projet est géré avec uv :

uv sync                 # résout les dépendances depuis uv.lock
uv pip install -e .     # expose l'entrypoint `dk` en mode éditable

Démarrage rapide

dk init                  # bootstrap : structure utilisateur + profil « Default »
dk edit                  # édite le profil (menus interactifs)
dk prepare               # clone les remotes, génère les composes, écrit network.yml
dk start                 # régénère les <entry>.env (live) + docker compose up -d
dk status                # état des conteneurs, section par section
dk stop                  # docker compose stop (conteneurs conservés) + supprime les .env

Sans sous-commande, dk affiche le tableau de bord (profil actif, liste des profils, commandes clés).

Commandes

Le nom de profil est toujours optionnel : sans lui, la commande cible le profil actif (dk status dev cible ponctuellement dev). Quelques alias silencieux existent (up/run → start, down → stop, rm → delete, ls → list, info → show, ps → status, exec → shell, db → data, sync → pull, env → environnement, creds → credentials).

Cycle de vie

Édition

Inspection & utilitaires

Toutes les commandes (sauf init et doctor) s'arrêtent si la structure utilisateur n'existe pas — un message invite à lancer dk init.

Ajoutez -d (ou --debug) à n'importe quelle commande pour voir les étapes internes et les commandes docker/git exécutées (secrets masqués).

Organisation des fichiers (config_root)

Tout l'état côté utilisateur vit dans le dossier de config standard de l'OS :

<config_root>/
├── profiles/<profile_id>/     ← un dossier par profil (profile_id = id court 6 hex)
│   ├── profile.yaml           ← la spec du profil (source de vérité)
│   ├── composes/              ← overrides docker-compose générés par `dk prepare` (+ état du build incrémental)
│   ├── env/                   ← env par entrée : <entry>.yml (source) + <entry>.env (aplati)
│   ├── repos/                 ← clones git du profil (un dossier par entrée git)
│   └── network.yml            ← host/port/url résolus de chaque service (généré par `dk prepare`)
├── cache/                     ← temporaire : fichiers de `dk mcp`, paquets sondés par image (`dk stats`)
├── settings.yaml              ← settings core (profil actif, ports, timeouts, docker, start)
├── globals.yaml               ← variables d'env globales, partagées entre profils
└── credentials.yaml           ← credentials infra partagés (surrealdb_logins + s3_accounts)

Points clés :

• Les clones vivent dans chaque profil (<profile>/repos/) — deux profils qui pointent le même dépôt ne se partagent pas un clone potentiellement checkout sur des refs incompatibles. Supprimer un profil emporte ses clones.
• L'env par entrée est scindé en deux fichiers :
  • <profile>/env/<entry>.yml — source de vérité, éditée via dk edit → Edit env. Catégorisée (secret / connection / other) + un bloc network: en lecture seule reflétant les adresses des autres services.
  • <profile>/env/<entry>.env — artefact transitoire régénéré par dk start (merge source + template + network.yml + globals + credentials + résolution Jinja), consommé comme env_file: par Compose, supprimé par dk stop.
• Conséquence pratique : tout changement dans dk settings / dk edit est pris en compte au prochain dk start, sans re-lancer dk prepare.
• dk clean purge composes/, repos/ et les .env aplatis ; il préserve les sources .yml (les secrets saisis survivent à un clean → prepare). Seuls dk clean --env ou dk delete suppriment tout le dossier env/.

Aucun secret irremplaçable ne vit ici : c'est de la config régénérable. Un rm -rf <config_root> suivi de dk init repart de zéro proprement.

Le profil

Un profil déclare un bloc méta (profile: — nom, description) puis les clés racine : frontend, back, infra, sdk, amp, archetypes, tools, kins. Voir profile.example.yaml pour un exemple complet.

Mode unifié — remote / git / dev

Chaque élément exécutable (frontend Horizon, back, archétypes, tools) porte un seul mode :

• remote — utilise une version en prod / managée ; seul endpoint est requis (référence à une variable de connexion globale).
• git — clone le dépôt et le build/run en local ; ref (branche). L'url est éditable pour les archétypes/tools ; pour les services et Horizon, le dépôt est prédéfini.
• dev — version locale ; path (chemin vers le dépôt local).

Les entrées d'infra (redis, rabbitmq, surrealdb, s3) utilisent local / remote : local lance le conteneur préfabriqué, remote résout son adresse depuis settings.env.connection.<endpoint> (ou depuis le login / compte pour SurrealDB et S3). Le back est un monorepo : une source partagée, puis une app par conteneur (api, grpc-stream-worker, node-service-provider), chacune local ou remote.

Frontend, back et infra sont toujours actifs — c'est le mode qui décide local vs externe. Archetypes, tools et kins portent un enabled (désactivé : ni cloné, ni buildé, ni lancé).

Exemple

profile:
  name: Default
  description: Profil full-local (sauf DB)

frontend:
  type: horizon           # interface web (mode remote/git/dev)
  mode: git

back:
  mode: dev
  path: ~/dev/digitalkin/back
  surrealdb_login: Back Local
  s3_account: Local
  services:
    api: { mode: local }
    grpc-stream-worker: { mode: local }
    node-service-provider: { mode: remote, endpoint: node-service-provider }

infra:
  redis:     { mode: local }
  rabbitmq:  { mode: local }
  surrealdb: { mode: local }
  s3:        { mode: remote, endpoint: s3 }

sdk: { source: auto }     # Core partagé par tous les modules : auto / git / dev
amp: { source: auto }

archetypes:
  Template:
    mode: git
    url: git@github.com:DigitalKin-ai/template-archetype.git
    ref: dev
    module_id: modules:template

tools: {}
kins: {}

La validation est stricte (extra: forbid) — toute clé inconnue fait échouer dk prepare / dk validate. La façon recommandée d'éditer un profil reste dk edit.

Settings, globals & credentials

Trois fichiers, chargés ensemble en un seul modèle Pydantic Settings, réécrits par dk settings :

• settings.yaml — settings core, éditables via dk settings :
  • Start — attach (est-ce que dk start suit les logs par défaut).
  • Logs — champs affichés par dk logs.
  • Dépôts — catalogues des dépôts git des archetypes / tools, dépôts prédéfinis du back et d'Horizon.
  • Ports — port hôte du front Horizon (frontend_host, défaut 5173) + plage d'allocation des archétypes (archetype_pool_start/_end, défaut 50050-50070).
  • Timeouts — poll/timeout des healthchecks, limite de restart, passes de résolution Jinja, timeout fetch git (les délais des commandes git / docker se règlent dans settings.yaml, section timeouts).
  • Docker — volume des certificats, fuseau des conteneurs (timezone) : auto (défaut) = celui de votre machine, UTC = comme la prod, ou un nom IANA (Europe/Paris). Pris en compte au prochain dk start pour l'infra, après dk prepare pour les modules, le back et Horizon. Les clés container_prefix / project_prefix d'un ancien settings.yaml sont ignorées (les noms Docker restent magicbox-<id du profil>).
• globals.yaml — le bloc d'env globales (settings.env) : secret / connection / id / other partagés entre profils, consommables depuis n'importe quelle entrée via {{ globals.NOM }}. Éditable via dk environnement.
• credentials.yaml — credentials infra partagés (surrealdb_logins + s3_accounts), référencés par les services par leur nom de profil. Éditable via dk credentials.

Les défauts sont codés en dur : les fichiers YAML n'ont besoin que de surcharger ce qui diffère.

Multi-profils

dk create dev            # crée un profil « dev » depuis le template
dk edit dev              # personnalise-le
dk prepare dev
dk switch dev            # en fait le profil actif

Surcharger le profil actif pour une seule commande : dk status dev, dk start dev, etc.

Claude Code (MCP)

dk mcp est un serveur MCP (stdio) : Claude Code pilote la magicbox comme un développeur, et parle aux kins comme un utilisateur du front. À brancher une fois :

claude mcp add magicbox --scope user -- dk mcp

(dk mcp lancé à la main dans un terminal affiche cette commande avec le chemin absolu de dk, utile si Claude Code ne voit pas le PATH du shell.)

• Durée : un appel rend la main en moins de 50 s (l'app desktop coupe vers 60 s) ; une opération plus longue continue en fond (job, kin_read).
• Une magicbox en cours n'est jamais arrêtée d'office : prepare / start / reboot refusent tant qu'une stack tourne, sauf stop_running: true — que Claude ne doit passer qu'avec votre accord.
• Chat avec un kin : il faut la stack démarrée, l'app api en local et le /me/context collé au dk prepare. Magicbox crée alors une session Clerk de test pour cet utilisateur avec la CLERK_SECRET_KEY de l'api — possible uniquement sur une instance Clerk de développement (sk_test_…) ; l'id de session est gardé dans <profil>/.mcp-clerk-session.json, les tokens restent en mémoire.
• Secrets : aucune sortie ne montre un secret de la magicbox. Toute réponse passe par un filtre qui remplace les valeurs connues (globales, credentials, variables sensibles des env/ et .env de tous les profils) et tout ce qui a l'allure d'un secret (CLE=… sensible, "apiKey": "…", Bearer …, JWT, sk_…, mot de passe d'URL) par ***. Limite : un secret transformé par une commande (exec … | base64) n'est pas reconnu. Le filtre ne couvre que le MCP : les outils de fichiers de Claude Code lisent toujours <config_root> si vous les y autorisez.
• Fichiers des kins : kin_files télécharge dans un dossier temporaire (<config_root>/cache/mcp-files/), supprimé à la fin de la session dk mcp (et nettoyé au démarrage suivant si elle a été tuée).
• config_set modifie votre profil : Claude doit vous annoncer ce qu'il change. Il refuse d'écrire pendant qu'un dk edit est ouvert sur ce profil (sa sauvegarde écraserait les changements).
• Restent à vous, dans votre terminal : dk delete / clean / prune, et les réglages partagés entre profils (dk settings : globales, credentials). Les sorties rendues à Claude sont bornées ; le journal complet de chaque tâche est dans <config_root>/logs/mcp/.

Auth git

Magicbox délègue l'authentification au système : configurez votre credential helper (osxkeychain, gh, clé SSH dans ~/.ssh/config, …) avant de lancer dk prepare. Les URLs des profils ne contiennent jamais de secret.

Versioning & release

Le versionnage suit PEP 440 : major.minor.patch avec un pré-release .devN optionnel, piloté par bump-my-version (config dans .bumpversion.toml). Chaque bump met à jour pyproject.toml et uv.lock, puis commit + tag automatiquement (commit = true, tag = true).

Le binaire Homebrew de bump-my-version peut être cassé (interpréteur Python obsolète) — préfixe les commandes par uv run pour utiliser celui du venv.

Règle d'or : un .devN est toujours un pré-release de la prochaine version pas encore sortie (0.0.2.dev1 < 0.0.2). La base major.minor.patch ne fait que monter — on ne colle jamais un .dev sur une version déjà publiée.

Les cas

bump dev depuis une finale échoue (value 0 is lower than the first value 1) : c'est voulu (first_value = 1). Depuis une finale, on ouvre le cycle avec patch/minor/major, jamais dev. Et « finaliser » (retirer le .dev) se fait avec --new-version, car un compteur .dev ne peut pas redescendre à 0 tout seul.

Procédure complète (pour chaque version)

# 1. bump : édite pyproject.toml + uv.lock, commit + tag automatiques
uv run bump-my-version bump patch          # 0.0.1 → 0.0.2.dev1

# 2. pousse le commit ET son tag
git push --follow-tags origin main

# 3. crée la GitHub Release → déclenche la publication (.github/workflows/release.yml)
gh release create v0.0.2.dev1 --prerelease --generate-notes   # --prerelease pour un .dev

Exemple d'un cycle complet 0.0.1 → 0.0.2 :

uv run bump-my-version bump patch            # 0.0.1 → 0.0.2.dev1
git push --follow-tags origin main
gh release create v0.0.2.dev1 --prerelease --generate-notes

uv run bump-my-version bump dev              # 0.0.2.dev1 → 0.0.2.dev2
git push --follow-tags origin main
gh release create v0.0.2.dev2 --prerelease --generate-notes

uv run bump-my-version bump --new-version 0.0.2   # finalise : 0.0.2.dev2 → 0.0.2
git push --follow-tags origin main
gh release create v0.0.2 --generate-notes    # release finale (sans --prerelease)

bump-my-version show-bump affiche à tout moment les transitions possibles depuis la version courante.

Dépannage

License

MIT — © DigitalKin.