Clone and run

How to clone arka-deck, install it, and run it in dev mode.

---

Prerequisites

• Node.js ≥ 20.19.0 (nvm recommended for managing multiple versions).
• Modern Git with DCO support.
• A few hundred MB of disk space.
• At least one AI provider API key (Anthropic, Google, OpenAI) to actually use the app.

---

Clone

git clone https://github.com/arka-squad/arka-deck.git
cd arka-deck

If you plan to contribute:

git remote add upstream https://github.com/arka-squad/arka-deck.git
git remote set-url origin <your-fork>

---

Install

npm install
npm --prefix adapters/inbound/web/ui install
npm --prefix addons/cortex-lite install

The project is an informal monorepo: root + UI sub-package + Cortex Lite sub-package. Three npm install cover all dependencies.

---

First run

npm run arka:start

The arka-cli.mjs script:

1. Builds the UI if needed (Vite production).
2. Spawns bin/arka-deck detached.
3. Redirects logs to .arka-web.log.
4. Writes the PID to .arka-pid.
5. Pings /api/health until ready.

Open http://127.0.0.1:3117 in your browser.

---

UI dev mode (hot reload)

To develop the UI with hot reload:

# Terminal 1 — Fastify server
npm run arka:start

# Terminal 2 — Vite dev server
npm run dev:ui

The Vite UI runs on a separate port (default 5173) and proxies API calls to 127.0.0.1:3117.

---

Enable local Git hooks

git config core.hooksPath .githooks

Enables the pre-commit hook that:

• Lints staged files.
• Verifies DCO sign-off.
• Refuses internal files (.input/, .claude/ except exceptions).

---

Verify the environment

npm run typecheck -- --pretty false
npm run lint
npm test

If everything is green, your environment is ready to contribute.

---

Stop

npm run arka:stop

Or simply Ctrl+C in the server terminal if not detached.

---

See also

• Contribution conventions: ./conventions (coming)
• CLI reference: ../reference/cli
• Env variables: ../reference/variables-env