Run it. Configure it. Stop it.

The daemon, kamajid, is the single source of truth. It owns the SQLite database, the ticket lifecycle, and background session starts; it serves the browser board and the HTTP/SSE API that both front-ends use. The kamaji terminal UI is a thin client. State changes stream to both over Server-Sent Events, so the board stays in sync no matter where you make a change.

A running daemon listens on three ports:

The board address is configurable via daemon.bind; the terminal proxy always binds the board port + 1.

You don't start the daemon by hand. Both the kamaji TUI and kamaji ticket create auto-spawn a detached kamajid if one isn't already healthy (pidfile + /healthz probe, race-safe), then connect to it.

# the terminal UI — spawns a daemon if none is running
$ kamajicopy
# the browser board — same daemon, same data, live terminals
$ xdg-open http://127.0.0.1:8755copy
# seed a Todo ticket without opening the TUI (project inferred from cwd)
$ kamaji ticket create --prompt "Fix GitHub issue #123"copy
# …or create it and start its agent immediately, detached
$ kamaji ticket create --background --prompt "Fix GitHub issue #123"copy

Running the daemon standalone

If you only want the browser board (no terminal UI), run the daemon yourself. In a source checkout, a Makefile wraps the lifecycle:

$ make start     # build kamajid and launch it in the backgroundcopy
$ make status    # is the daemon responding? (probes :8755/healthz)copy
$ make logs      # follow the daemon log (/tmp/kamajid.log)copy
$ make restart   # rebuild + relaunch (after pulling new code)copy
$ make stop      # stop the running daemoncopy

Equivalently, run the binary directly — the terminal proxy binds the board port + 1:

$ kamajid serve                          # default bind 127.0.0.1:8755copy
$ kamajid serve --bind 127.0.0.1:9000    # proxy lands on :9001copy

Autostart on login (systemd)

Want the board up after every login or reboot? From a source checkout, install kamajid as a systemd user service. It builds a release binary into ~/.local/bin, installs a user unit, and enables lingering so the daemon also starts at boot, before login:

$ make install-service     # install + enable + start kamajid.servicecopy
$ make uninstall-service   # stop + remove the unit (binary left in place)copy

There are two ways to run kamaji: native — the default, daemon and agents on your host — and sandboxed, where the daemon, zellij, and every agent run inside one container so an agent can have root inside the box without risking your host. Container mode is opt-in via kamaji up. Rootless Podman is recommended (container-root maps to your unprivileged user); Docker also works.

$ kamaji up         # run daemon + zellij + agents inside the sandboxcopy
$ kamaji status     # which mode am I in? + board URLcopy
$ kamaji logs       # follow container logscopy
$ kamaji down       # stop the sandbox — next `kamaji` runs nativecopy
# tune the sandbox:
$ kamaji up --runtime docker --memory 4g --cpus 2 --pids-limit 512copy

kamaji up reads your registered projects and bind-mounts each project root (and its worktree dir) at identical paths, mounts your agent credentials, sets resource limits, and binds the board to the published port. To add a new project, register it in the browser or TUI, then re-run kamaji up — it recreates the container to pick up the new bind-mount; running agent sessions persist via the worktrees and zellij-cache volume, and resume.

In container mode the browser board is the terminal surface — open a ticket's inline terminal there. (The TUI's Enter-to-attach opens a local zellij session, so it isn't used for attaching to in-container agents in v1.) v1 targets Linux hosts; raw podman/docker equivalents live in the repo's deploy/ directory.

kamaji reads a single TOML file at ~/.config/kamaji/config.toml (honoring $XDG_CONFIG_HOME). It's written with sane defaults the first time kamaji runs, so there's nothing to set up — edit only what you want to change:

Every key, with defaults and gotchas, is documented on the configuration reference page.

Both kamaji and kamajid read config.toml once, at startup. The one exception is theme, which you can switch live from the board with t. Everything else — [daemon] settings, [auto_review], agent command templates, worktree_base — takes effect the next time the daemon starts. So after editing the file, restart the daemon however you run it:

# auto-spawned daemon: stop it, then relaunch the TUI (it spawns a fresh one)
$ pkill -x kamajid && kamajicopy
# source checkout, daemon standalone:
$ make restartcopy
# systemd user service:
$ systemctl --user restart kamajidcopy
# container mode:
$ kamaji down && kamaji upcopy

Restarting the daemon is safe for running work: agent sessions live in zellij, not in the daemon, so they keep running and re-appear on the board when it comes back. One subtlety: daemon.web_theme only applies to zellij sessions created after the restart — already-running sessions keep their old colors.

First, know what stops what. Quitting the TUI with q only closes the client — the daemon and every agent session keep running, by design. Detaching from a session with Ctrl+o d leaves the agent working in the background. To actually stop the daemon:

$ make stop                       # source checkout (pidfile, falls back to pkill)copy
$ pkill -x kamajid                # anywherecopy
$ systemctl --user stop kamajid   # if installed as a servicecopy
$ kamaji down                     # container mode — data preservedcopy

Stopping the daemon does not kill agent sessions — they are zellij sessions and outlive it. The tidy way to end a ticket's session is to move the ticket to Done and accept the cleanup prompt (kills the session, removes the worktree, deletes the branch). Outside the board, zellij list-sessions and zellij kill-session <name> work as usual.

Uninstalling

The uninstall script stops a running daemon, removes the kamaji + kamajid binaries, and removes the systemd user service if you installed one. Your data — the board database, config, and cache — is kept by default; add --purge to delete it too.

# Linux / macOS
$ curl -fsSL https://raw.githubusercontent.com/alveflo/kamaji/main/uninstall.sh | shcopy
# …including your data
$ curl -fsSL https://raw.githubusercontent.com/alveflo/kamaji/main/uninstall.sh | sh -s -- --purgecopy
# Windows (PowerShell) — download first so you can pass -Purge
> irm https://raw.githubusercontent.com/alveflo/kamaji/main/uninstall.ps1 | iexcopy

If you installed to a custom location, set the same KAMAJI_INSTALL_DIR when uninstalling.