First steps with arka-deck

This guide explains how to install arka-deck, launch it, configure an AI provider and open a first project — with no technical prerequisite.

To understand the terms used (profile, atom, bloc, etc.), see 03-concepts.

Prerequisites

Node.js ≥ 20.19.0 installed on your machine (nodejs.org)
An API key from at least one AI provider (Anthropic, Google, OpenAI depending on your choice)
A few hundred MB of disk space

Install

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

Open http://127.0.0.1:3117 in your browser. The React interface starts.

arka-deck runs entirely on your machine. Nothing you do is sent to an external server, except requests to the public Cortex (catalogue, read-only) and exchanges with your configured AI provider.

Configure a provider

Before any session, you must configure at least one LLM provider under Settings.

Open Settings → Providers
Choose your provider (Claude, Gemini, Codex CLI)
Paste your API key
Test the connection from the screen

Keys are encrypted locally in AES-256-GCM under ~/.arka-deck/ — they never leave your machine.

Create a project

A project is a local folder on your machine.

From the home, click New project
Select an existing folder on your machine
arka-deck creates an .arka-deck/ subfolder for its working data

Your existing files are not modified. arka-deck only writes inside .arka-deck/.

You can organize projects into workspaces (logical folders visible in the sidebar).

Recruit an agent

From Project → Catalogue, you access the agent library provided by the public Cortex — several dozen ready-to-use HYOS profiles: architect, lawyer, QA engineer, data scientist, compliance auditor, etc.

Select a profile and click Install — the agent is associated with the project. You can install several agents on the same project.

Start a chat session

From the Project view, open the Chat tab and select an installed agent.

Each session has its own conversation thread. You can:

Browse your session history in the Sessions view
Rename or delete a session
Resume an existing session

Use cortex-actions (frame a turn)

The cortex-actions addon adds a panel in the chat interface. It lets you select a Cortex artifact before sending your message.

Available artifact types:

Modes — execution frames (e.g. audit mode, review mode)
Blocs — executable rules and capabilities (skill, expertise, tool, method, scope)

When you select an artifact, it is injected into the agent’s context for the next turn only. The addon can also automatically suggest favorites relevant to your project.

Consult memory

From a project’s Memory view, you see entries captured by the memory-local addon after your sessions.

Each entry has a level (L1 to L5) that indicates its importance:

L1 — short note
L3 — session synthesis
L5 — structured decision or learning

Entries are reinjected into upcoming sessions so the agent does not start from scratch.

Track a mission with Mission Guardian

For structured missions (mission → phases → evidence → QA verdict), the mission-guardian addon shows a step-by-step tracker in the project’s Mission Guardian view. Each phase has gates to cross before moving to the next.

Consult governance

The Governance view displays active policies and the agent action journal for a project. It’s a local trace — nothing is sent outside.

Manage addons

The Addons view lists installed modules and their state (active, inactive). Some addons can be enabled or disabled per project.

Access from another device (LAN)

By default, arka-deck listens only on 127.0.0.1 (your machine).

To access from another device on your local network:

Go to Settings → Profile & UI → Network
Enable Allow access from local network (LAN)
Reboot arka-deck (npm run arka:reboot)
The interface displays available LAN URLs and the token to use

Security: LAN access requires an X-Arka-Token header (regenerated at each launch). CORS is limited to RFC1918 ranges.

Stop arka-deck

npm run arka:stop

Your data stays on your machine under .arka-deck/ (per project) and ~/.arka-deck/ (global). It persists across restarts.

What stays on your machine

Data	Storage
Projects and working files	Your disk, unchanged
Chat sessions and transcripts	`<project>/.arka-deck/`
Agentic memory	`<project>/.arka-deck/memory/`
ArkaDoc (reports, briefs, specs)	`<project>/.arka-deck/arkadoc/`
Governance logs	`<project>/.arka-deck/`
API keys and secrets	`~/.arka-deck/` (AES-256-GCM)
Preferences	`~/.arka-deck/`

What leaves your machine

Destination	Data sent
`public.arkalabs.app` (HTTPS, read-only)	Catalogue lists, profile/bloc/atom sheets — only when you load the library
Your configured AI provider	Your prompts and conversation history, per the provider’s policy

No telemetry, no analytics, no machine identifier.

To cut the public Cortex entirely, set ARKA_DECK_CORTEX_URL=http://127.0.0.1:0 — the catalogue will degrade but no call will leave for the outside.

What next?

To understand the vocabulary in detail, see 03-concepts.
If you manage several providers or want to switch, see 05-providers.md (coming).
If you frame the security and data posture for your team, see 07-securite-et-donnees.md (coming).