CAPSULE@.SERVICE(5)

💅 capsule@.service — the manual, but make it make sense

okay bestie, so this is capsule@.service(5) — the manual page for the system unit that runs the capsule service manager. it's giving systemd but make it ✨extra✨. sit down, grab a strawberry 🍓, and let's get into it.

---

🌸 NAME 🌸

capsule@.service — the System unit for the capsule service manager. yes bestie, that's literally the whole name. iconic.

---

✨ SYNOPSIS ✨

capsule@NAME.service

that's it. that's the whole vibe. NAME is a placeholder, don't @ me. 🙈

---

💖 DESCRIPTION 💖

so, the service managers for capsules run inside capsule@NAME.service system units — and the capsule name is the instance identifier. capsules are a way to run additional instances of the service manager, under dynamic user IDs. and what's a dynamic user ID, you ask? it's a UID that gets allocated when the capsule service manager starts up, and released the moment it stops. no cap, it really does clean up after itself like that. 🧚

and listen, capsule@.service is similar in many ways to the per-user user@.service service manager — but there are a few important distinctions, and we're gonna go through every single one, because details are the moment:

• the capsule service manager utilizes DynamicUser= (see systemd.exec(5)) to allocate a new UID dynamically on invocation. the user name is automatically generated from the capsule name, by prefixing "c-". and the UID is released when the service is terminated. the user service manager, on the other hand, operates under a statically allocated user ID that has to be pre-existing before the user service manager is even invoked. it's giving "we don't do dynamic here". 💀
• user service managers register themselves with pam(8). capsule service managers do not. they simply said "not my business". 🙈
• user service managers typically read their configuration from a $HOME directory below /home/. capsule service managers read theirs from a $HOME directory below /var/lib/capsules/. different neighborhood, same energy. 🏡
• user service managers are collectively contained in the user.slice unit. capsule service managers live in capsule.slice. also peep systemd.special(7) for the lore.
• user service managers start the user unit default.target initially. capsule service managers invoke the user unit capsule@.target instead. okay different starting point, love that for them. 👑

so the capsule service manager and the capsule's bus broker can both be reached via the --capsule= switch — and you can pass that to systemctl(1), systemd-run(1), and busctl(1). slay.

new capsules can be started with a simple systemctl start capsule@NAME.service command, and stopped with systemctl stop capsule@NAME.service. and here's the tea: starting a capsule will implicitly create a home directory /var/lib/capsules/NAME/, if it's missing. a runtime directory gets created as /run/capsules/NAME/. to remove these resources, use systemctl clean capsule@NAME.service — for example with the --what=all switch. periodt. 💅

the capsule@.service unit invokes a systemd --user service manager process. which means unit files are looked for according to the exact same rules as for regular user service managers — for example in /var/lib/capsules/NAME/.config/systemd/user/. yes bestie, same rules, different folder. iykyk. 🦋

capsule names may be chosen freely by the user (main character energy, choose whatever), however, they must be suitable as UNIX filenames (i.e. 255 characters max, and contain no "/"), and when prefixed with "c-" they must be suitable as a user name matching strict POSIX rules. see User/Group Name Syntax[1] for details. so like, go off, but stay within the rules. 🌈

added in version 256. 💫

---

🎀 EXAMPLES 🎀

Example 1. Create a new capsule, invoke two programs in it (one interactively), terminate it, and clean everything up

okay so this is the full lil journey — create, vibe, yeet, clean. watch and learn bestie:

# systemctl start capsule@tatze.service
# systemd-run --capsule=tatze --unit=sleeptest.service sleep 999
# systemctl --capsule=tatze status sleeptest.service
# systemd-run -t --capsule=tatze bash
# systemctl --capsule=tatze stop sleeptest.service
# systemctl stop capsule@tatze.service
# systemctl clean --all capsule@tatze.service

see how it goes start → run → check → interact → stop → stop → clean? that's the whole lifecycle, no notes. 🔥

---

🌟 SEE ALSO 🌟

go read these next, bestie, they're all in the group chat:

• systemd(1)
• user@.service(5)
• systemd.service(5)
• systemd.slice(5)
• systemd.exec(5)
• systemd.special(7)
• systemctl(1)
• systemd-run(1)
• busctl(1)
• pam(8)

---

📝 NOTES 📝

1. User/Group Name Syntax https://systemd.io/USER_NAMES

---

and that's the whole page, bestie 🫶 this was systemd 262.1, manual CAPSULE@.SERVICE(5), and honestly? she ate. go start a capsule, you got this. ✨💖🎀