Premier pas avec arka-deck

Ce guide explique comment installer arka-deck, le lancer, configurer un provider IA et ouvrir un premier projet — sans prérequis technique.

Pour comprendre les termes employés (profil, atome, bloc, etc.), consultez 03-concepts.

Prérequis

Node.js ≥ 20.19.0 installé sur votre machine (nodejs.org)
Une clé API auprès d’au moins un provider IA (Anthropic, Google, OpenAI selon votre choix)
Quelques centaines de Mo d’espace disque

Installation

git clone https://github.com/arka-squad/arka-deck.git
cd arka-deck
npm install
npm run arka:start

Ouvrez http://127.0.0.1:3117 dans votre navigateur. L’interface React démarre.

arka-deck tourne entièrement sur votre machine. Rien de ce que vous faites n’est envoyé vers un serveur externe, à l’exception des requêtes vers le Cortex public (catalogue, lecture seule) et des échanges avec votre provider IA configuré.

Configurer un provider

Avant toute session, vous devez configurer au moins un provider LLM dans Paramètres.

Ouvrez Paramètres → Providers
Choisissez votre provider (Claude, Gemini, Codex CLI)
Collez votre clé API
Testez la connexion depuis l’écran

Les clés sont chiffrées localement en AES-256-GCM dans ~/.arka-deck/ — elles ne quittent jamais votre machine.

Créer un projet

Un projet est un dossier local sur votre machine.

Depuis l’accueil, cliquez sur Nouveau projet
Sélectionnez un dossier existant sur votre machine
arka-deck crée un sous-dossier .arka-deck/ dans ce dossier pour ses données de travail

Vos fichiers existants ne sont pas modifiés. arka-deck écrit uniquement dans .arka-deck/.

Vous pouvez organiser vos projets dans des workspaces (dossiers logiques visibles dans la barre latérale).

Recruter un agent

Depuis la vue Projet → Catalogue, vous accédez à la bibliothèque d’agents fournie par le Cortex public — plusieurs dizaines de profils HYOS prêts à l’emploi : architecte, juriste, QA engineer, data scientist, auditeur conformité, etc.

Sélectionnez un profil et cliquez Installer — l’agent est associé au projet. Vous pouvez installer plusieurs agents sur le même projet.

Démarrer une session de chat

Depuis la vue Projet, ouvrez l’onglet Chat et sélectionnez un agent installé.

Chaque session a son propre fil de conversation. Vous pouvez :

Parcourir l’historique de vos sessions dans la vue Sessions
Renommer ou supprimer une session
Reprendre une session existante

Utiliser cortex-actions (cadrer un tour)

L’addon cortex-actions ajoute un panneau dans l’interface de chat. Il vous permet de sélectionner un artefact Cortex avant d’envoyer votre message.

Types d’artefacts disponibles :

Modes — cadres d’exécution (par exemple mode audit, mode revue)
Blocs — règles et capacités exécutables (skill, expertise, tool, méthode, scope)

Quand vous sélectionnez un artefact, il est injecté dans le contexte de l’agent pour le prochain tour uniquement. L’addon peut aussi suggérer automatiquement des favoris pertinents pour votre projet.

Consulter la mémoire

Depuis la vue Mémoire d’un projet, vous voyez les entrées capturées par l’addon memory-local après vos sessions.

Chaque entrée a un niveau (L1 à L5) qui indique son importance :

L1 — note courte
L3 — synthèse d’une session
L5 — décision ou apprentissage structuré

Les entrées sont réinjectées dans les prochaines sessions pour que l’agent ne reparte pas de zéro.

Suivre une mission avec Mission Guardian

Pour les missions structurées (mission → phases → preuves → verdict QA), l’addon mission-guardian affiche un suivi pas-à-pas dans la vue Mission Guardian du projet. Chaque phase a des gates à franchir avant de passer à la suivante.

Consulter la gouvernance

La vue Gouvernance affiche les policies actives et le journal des actions agent pour un projet. C’est un suivi local — rien n’est envoyé vers l’extérieur.

Gérer les addons

La vue Addons liste les modules installés et leur état (actif, inactif). Certains addons peuvent être activés ou désactivés par projet.

Accès depuis un autre appareil (LAN)

Par défaut, arka-deck écoute uniquement sur 127.0.0.1 (votre machine).

Pour accéder depuis un autre appareil sur votre réseau local :

Allez dans Paramètres → Profil & UI → Réseau
Activez Permettre l’accès depuis le réseau local (LAN)
Redémarrez arka-deck (npm run arka:reboot)
L’interface affiche les URLs LAN disponibles et le token à utiliser

Sécurité : l’accès LAN exige un header X-Arka-Token (régénéré à chaque démarrage). Le CORS est limité aux plages RFC1918.

Arrêter arka-deck

npm run arka:stop

Vos données restent sur votre machine dans .arka-deck/ (par projet) et ~/.arka-deck/ (global). Elles persistent entre les démarrages.

Ce qui reste sur votre machine

Donnée	Stockage
Projets et fichiers de travail	Votre disque, inchangé
Sessions de chat et transcripts	`<projet>/.arka-deck/`
Mémoire agentique	`<projet>/.arka-deck/memory/`
ArkaDoc (CR, briefs, specs)	`<projet>/.arka-deck/arkadoc/`
Logs de gouvernance	`<projet>/.arka-deck/`
Clés API et secrets	`~/.arka-deck/` (AES-256-GCM)
Préférences	`~/.arka-deck/`

Ce qui sort de votre machine

Destination	Données envoyées
`public.arkalabs.app` (HTTPS, lecture seule)	Listes catalogue, fiches profil/bloc/atome — uniquement quand vous chargez la bibliothèque
Votre provider IA configuré	Vos prompts et historiques de conversation, selon la politique du provider

Aucune télémétrie, aucun analytics, aucun identifiant machine.

Pour couper entièrement le Cortex public, définissez ARKA_DECK_CORTEX_URL=http://127.0.0.1:0 — le catalogue tombera en dégradé mais aucun appel ne partira vers l’extérieur.

Et après ?

Si vous voulez comprendre le vocabulaire en détail, voir 03-concepts.
Si vous gérez plusieurs providers ou voulez basculer, voir 05-providers.md (à venir).
Si vous cadrez la posture sécurité et données pour votre équipe, voir 07-securite-et-donnees.md (à venir).