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.0.13

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.0.13
File	Size	Uploaded
kartikeya-0.0.13.tar.gz	92.6 kB	Sep 7, 2026	Details

Built distribution (wheel)

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

Total release size: 147.9 kB

Release files / kartikeya-0.0.13.tar.gz

Download URL	kartikeya-0.0.13.tar.gz
Size	92.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`b9677e1061240aafcabcf85301e54cc8542c1a72bebe9a681306ceeb156f3072`
BLAKE2b-256 checksum How to use checksums	`4e50ee1b5b0643797c4e7a232a1a3534a485838748ba3ea8be71d5c25b1bc500`
Upload date	Sep 7, 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/19c38ff6adcfe51398ac2298312d7b436443ee0a

Workflow

Publishing configuration: github.com/willow-memory/kartikeya/blob/19c38ff6adcfe51398ac2298312d7b436443ee0a/.github/workflows/release.yml
Publishing logs: github.com/willow-memory/kartikeya/actions/runs/34073987745/attempts/1

Artifact

Subject: kartikeya-0.0.13.tar.gz
SHA-256 checksum: b9677e1061240aafcabcf85301e54cc8542c1a72bebe9a681306ceeb156f3072 Verifying attestations

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

Download URL	kartikeya-0.0.13-py3-none-any.whl
Size	55.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a4b2e9936cbc5c441967048d110a86e5e318c237c024e07eb803e066bab4d218`
BLAKE2b-256 checksum How to use checksums	`69b363ea44a63d8ab951f604bec6e52a05fe260ccb59a7faf7ef6f38dff79c10`
Upload date	Sep 7, 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/19c38ff6adcfe51398ac2298312d7b436443ee0a

Workflow

Publishing configuration: github.com/willow-memory/kartikeya/blob/19c38ff6adcfe51398ac2298312d7b436443ee0a/.github/workflows/release.yml
Publishing logs: github.com/willow-memory/kartikeya/actions/runs/34073987745/attempts/1

Artifact

Subject: kartikeya-0.0.13-py3-none-any.whl
SHA-256 checksum: a4b2e9936cbc5c441967048d110a86e5e318c237c024e07eb803e066bab4d218 Verifying attestations