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

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.2
File	Size	Uploaded
kartikeya-0.2.2.tar.gz	100.5 kB	Sep 10, 2026	Details

Built distribution (wheel)

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

Total release size: 159.4 kB

Release files / kartikeya-0.2.2.tar.gz

Download URL	kartikeya-0.2.2.tar.gz
Size	100.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`1a632f3f9953be35ad4de8b1e236b56dbfe8e243ea68c290502461d03fc89ce7`
BLAKE2b-256 checksum How to use checksums	`87953f10c98f197c2f9bcad6edff8e3c4b776e11ec6990e642b2400dcfd80a7f`
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/9f48b0521d01775758113c3212d72c95ffff5699

Workflow

Publishing configuration: github.com/willow-memory/kartikeya/blob/9f48b0521d01775758113c3212d72c95ffff5699/.github/workflows/release.yml
Publishing logs: github.com/willow-memory/kartikeya/actions/runs/34532593103/attempts/1

Artifact

Subject: kartikeya-0.2.2.tar.gz
SHA-256 checksum: 1a632f3f9953be35ad4de8b1e236b56dbfe8e243ea68c290502461d03fc89ce7 Verifying attestations

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

Download URL	kartikeya-0.2.2-py3-none-any.whl
Size	58.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`57eee04fbe1d618d3650d2d60b71006a90234480f8a3c27bc7791273263ea6b3`
BLAKE2b-256 checksum How to use checksums	`4009fc4acc2fb3d17162d9bfa81269f47ee14d6286bbf23be90254f8ab8bac65`
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/9f48b0521d01775758113c3212d72c95ffff5699

Workflow

Publishing configuration: github.com/willow-memory/kartikeya/blob/9f48b0521d01775758113c3212d72c95ffff5699/.github/workflows/release.yml
Publishing logs: github.com/willow-memory/kartikeya/actions/runs/34532593103/attempts/1

Artifact

Subject: kartikeya-0.2.2-py3-none-any.whl
SHA-256 checksum: 57eee04fbe1d618d3650d2d60b71006a90234480f8a3c27bc7791273263ea6b3 Verifying attestations