Skip to content
Arka Platform

CLI

arka-deck exposes a single CLI to start, stop and reboot the local web server.

Source of truth: bin/arka-deck, scripts/arka-cli.mjs.

Binary command

Section titled “Binary command”
Terminal window
./bin/arka-deck [flags]

Direct launch of the web server. By default, listens on 127.0.0.1:3117 (strict loopback).

Flags

Section titled “Flags”
FlagEffect
--port <n>HTTP port (default 3117)
--host <addr>Explicit bind address
--lanAlias for --host 0.0.0.0 (enables LAN)
--no-lanForce strict loopback

npm wrappers

Section titled “npm wrappers”

scripts/arka-cli.mjs orchestrates the lifecycle in detached mode.

npm run arka:start

Section titled “npm run arka:start”
Terminal window
npm run arka:start [-- --lan|--no-lan]
  • Builds the UI if needed
  • Spawns bin/arka-deck detached
  • Redirects logs to .arka-web.log
  • Writes PID to .arka-pid
  • Pings /api/health until ready (or fails after timeout)

npm run arka:stop

Section titled “npm run arka:stop”
Terminal window
npm run arka:stop
  • Kills the process via PID (.arka-pid)
  • lsof fallback if PID is stale
  • Cleans up .arka-pid and .arka-token

npm run arka:reboot

Section titled “npm run arka:reboot”
Terminal window
npm run arka:reboot [-- --lan|--no-lan]

Equivalent to arka:stop followed by arka:start. Useful after a LAN preference change or a modification touching the bootstrap.

LAN mode priority order

Section titled “LAN mode priority order”

Four sources can enable or disable LAN mode. The first applicable wins:

  1. CLI flag (--lan or --no-lan) — maximum priority.
  2. Environment variable ARKA_DECK_WEB_LAN=1|true|yes.
  3. Persisted preference ~/.arka-deck/preferences/network.json (Settings toggle).
  4. Default: false (strict loopback).

Session token (LAN mode)

Section titled “Session token (LAN mode)”

When LAN is active:

  • A token is regenerated at each start.
  • Stored in .arka-token at the arka-deck project root (mode 0o600).
  • Displayed in logs at boot (non-sensitive in local mode).
  • Required in the X-Arka-Token header for any request from a remote device.
  • Removed on clean shutdown.

In strict loopback mode (default), the token is not required for requests from 127.0.0.1.

Signals

Section titled “Signals”

The server stops cleanly on SIGINT (Ctrl+C) and SIGTERM:

  • Cancels in-progress chat sessions
  • Closes EventBus subscriptions (each addon’s unsubscribe())
  • Closes SQLite databases
  • Stops the Cortex Lite sidecar if applicable

SIGKILL (kill -9) bypasses everything — avoid unless necessary (the project marker and SQLite remain consistent thanks to atomic writes).

Main environment variables

Section titled “Main environment variables”
VariableEffect
ARKA_DECK_WEB_PORTHTTP port
ARKA_DECK_WEB_HOSTBind address
ARKA_DECK_WEB_LANEnable LAN (priority 2)
ARKA_DECK_HOMEOverride ~/.arka-deck/
ARKA_DECK_LOGFastify log level
ARKA_DECK_RATE_LIMIT_MAXRate limit ceiling

Full list: ./variables-env.

See also

Section titled “See also”