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

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.1.0
File	Size	Uploaded
kartikeya-0.1.0.tar.gz	94.4 kB	Sep 7, 2026	Details

Built distribution (wheel)

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

Total release size: 150.2 kB

Release files / kartikeya-0.1.0.tar.gz

Download URL	kartikeya-0.1.0.tar.gz
Size	94.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`9166f8b0072d747633e91c8a6d883944baf8be5e29bcf0dda2bc99114d2f0734`
BLAKE2b-256 checksum How to use checksums	`421b17686283aafde3eb389737da43b8eb6826ed6cf48540f21a383b9a98c111`
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/d27fb2407624a94010753383ffc8ccdf5bec0c20

Workflow

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

Artifact

Subject: kartikeya-0.1.0.tar.gz
SHA-256 checksum: 9166f8b0072d747633e91c8a6d883944baf8be5e29bcf0dda2bc99114d2f0734 Verifying attestations

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

Download URL	kartikeya-0.1.0-py3-none-any.whl
Size	55.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5ca79663691c89698f501d3fe0d29fd9a5ba987435f004de3187417b22e65d23`
BLAKE2b-256 checksum How to use checksums	`713e910fdbabe07d186a7e48fe60050887ac723dd30e34e841f9a21c7e985831`
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/d27fb2407624a94010753383ffc8ccdf5bec0c20

Workflow

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

Artifact

Subject: kartikeya-0.1.0-py3-none-any.whl
SHA-256 checksum: 5ca79663691c89698f501d3fe0d29fd9a5ba987435f004de3187417b22e65d23 Verifying attestations