Kartikeya

Skanda · Murugan — the six-faced commander of the divine armies, born to lead the devas. The engine that marshals and runs a fleet's tasks. Colloquially: Kart.

A standalone, host-agnostic task queue + sandboxed worker. Submit shell (or, optionally, LLM-workflow) tasks to a queue; a worker claims them and runs each in a bubblewrap sandbox with an explicit mount/credential/network policy.

Kartikeya is the execution engine extracted from the Willow fleet (willow-2.0/core/kart_* — historical path) and made to stand on its own — no fleet, no specific host, no required database server.

Status

Extracted and published. The sandbox/worker/execute core is fully landed (sandbox.py, worker.py, execute.py, queue.py), tested, and released on PyPI as kartikeya (0.0.9) — pip install kartikeya, or pip install willow-mcp, which floors it at >=0.0.9,<1.0.0. The cap is a real compatibility range rather than decoration: bump-minor-pre-major is false here, so a breaking change cuts 1.0.0 instead of hiding in a minor. The staged lift in docs/DESIGN.md is done through stage 4; stage 5 (legacy fleet monolith deleting its core/kart_* copy) is tracked in willow-mcp#111.

Design goals

Host-agnostic. The only coupling — "where do tasks live" — is a small TaskQueue interface a host implements. Kartikeya owns the sandbox, worker loop, lanes, and command scan; the host owns storage and file roots.
Zero-infra by default. Ships a reference SqliteTaskQueue, so pip install kartikeya can execute tasks with no Postgres and no fleet.
Backend-swappable. SQLite (bundled), Postgres, or a custom backend behind the same interface.
Sandboxed and network-gated. Tasks run network-isolated unless the stored task text carries a # allow_net directive; credentials reach only network- enabled tasks. (Who is allowed to write that directive is the host's call — see the security note in docs/DESIGN.md.)

Install

pip install kartikeya            # base: shell tasks, SQLite backend
pip install "kartikeya[postgres]"  # + Postgres backend helpers
pip install "kartikeya[llm]"       # + LLM-workflow task type

Quickstart

Resource caps (memory + PID limits) prefer a delegated cgroup parent. On a fresh install, run once:

kartikeya setup-cgroup    # installs ~/.config/systemd/user/kart.slice
kartikeya cgroup-status   # should print ready: /sys/fs/cgroup/...

systemd worker (operative): a shell profile export does not reach a user-service kart worker. After setup-cgroup succeeds, wire the parent into the worker environment and restart:

systemctl --user set-environment KART_CGROUP_PARENT=/sys/fs/cgroup/.../kart.slice
systemctl --user restart <your-kart-worker-unit>

(Or set Environment=KART_CGROUP_PARENT=... in a drop-in for the worker unit.)

The export line printed by setup-cgroup is for CLI / interactive runs only. Without a delegated parent, Kart falls back to task-scoped prlimit/ulimit inside the sandbox (PID cap by default; virtual-memory cap only with KART_RLIMIT_USE_AS=1). WILLOW_KART_NO_RLIMIT=1 disables caps entirely (escape hatch only).

Coming with stage 2 — once the worker core lands, this section documents kartikeya worker end to end (submit → worker runs → poll).

License

MIT © Sean Campbell

Metadata

Release files for kartikeya 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kartikeya 0.2.1
File	Size	Uploaded
kartikeya-0.2.1.tar.gz	98.7 kB	Sep 10, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for kartikeya 0.2.1
File	Interpreter	ABI	Platform	Reset
kartikeya-0.2.1-py3-none-any.whl 57.8 kB Sep 10, 2026	Python 3	none	any	Details

Total release size: 156.5 kB

Release files / kartikeya-0.2.1.tar.gz

Download URL	kartikeya-0.2.1.tar.gz
Size	98.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`908d292c05ee3bf6d66a5b8632a85d492198c230468583530514d6c4e30d6a8b`
BLAKE2b-256 checksum How to use checksums	`46b9013112e0980bda914e81159f0f440bc62a5f72f3d4ba3fcc0c353b0591a1`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/willow-memory/kartikeya
Publishing commit: github.com/willow-memory/kartikeya/tree/911a20f0f1be3a9311bfef342d09d00db7c69f80

Workflow

Publishing configuration: github.com/willow-memory/kartikeya/blob/911a20f0f1be3a9311bfef342d09d00db7c69f80/.github/workflows/release.yml
Publishing logs: github.com/willow-memory/kartikeya/actions/runs/34524211129/attempts/1

Artifact

Subject: kartikeya-0.2.1.tar.gz
SHA-256 checksum: 908d292c05ee3bf6d66a5b8632a85d492198c230468583530514d6c4e30d6a8b Verifying attestations

Release files / kartikeya-0.2.1-py3-none-any.whl

Download URL	kartikeya-0.2.1-py3-none-any.whl
Size	57.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4107e48c41b531c41b3641f34d0c9e428af5188f17a8b54f027bd087d9af3511`
BLAKE2b-256 checksum How to use checksums	`18ad0dbcc3467341409a28d60baef3d143314b46befca8c74323af19290d6003`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/willow-memory/kartikeya
Publishing commit: github.com/willow-memory/kartikeya/tree/911a20f0f1be3a9311bfef342d09d00db7c69f80

Workflow

Publishing configuration: github.com/willow-memory/kartikeya/blob/911a20f0f1be3a9311bfef342d09d00db7c69f80/.github/workflows/release.yml
Publishing logs: github.com/willow-memory/kartikeya/actions/runs/34524211129/attempts/1

Artifact

Subject: kartikeya-0.2.1-py3-none-any.whl
SHA-256 checksum: 4107e48c41b531c41b3641f34d0c9e428af5188f17a8b54f027bd087d9af3511 Verifying attestations