{"slug":"containers-internals","title":"containers-internals","summary":"Use when explaining or building on Linux container primitives: namespaces, cgroups v2, overlayfs, runc and the OCI spec, seccomp-bpf, capabilities, or escapes. Not for VM isolation: use qemu-kvm.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-30T19:50:07.293341Z","repo":{"url":"https://github.com/OutlineDriven/outline-driven-development","stars":54,"forks":10,"license":"Apache-2.0","updatedAt":"2026-09-28T03:16:21Z"},"bodyHtml":"
\n

name: containers-internals\ndescription: 'Use when explaining or building on Linux container primitives: namespaces, cgroups v2, overlayfs, runc and the OCI spec, seccomp-bpf, capabilities, or escapes. Not for VM isolation: use qemu-kvm.'

\n

Containers internals

\n

Contract

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldBound contract
TriggerA container's isolation or resource limit needs explaining or debugging, a seccomp profile needs writing, a minimal container is being built without a daemon, or an escape vector needs assessing.
AuthorityReversible local. The write set is namespaces and cgroups created for the session under /sys/fs/cgroup, overlay mounts on user-named directories, an OCI bundle directory, and seccomp filters applied to processes the skill starts. Rollback is stopping those processes, unmounting, and removing the cgroup directory. Most steps need root or a user namespace. No remote mutation.
Side effectKernel namespaces, cgroups, and mounts exist while the experiment runs.
DoneThe isolation or limit in question is reproduced with the raw primitive, the observed behavior matches the explanation, and every created object has its teardown recorded.
\n

Inputs

\n\n

Procedure

\n
    \n
  1. Read and enter namespaces. Each namespace type isolates one resource. Done when: the target process's namespace inodes are listed and, when needed, a shell runs inside them.
    2. \n
\n
ls -la /proc/self/ns/            # one link per namespace type\nreadlink /proc/1234/ns/net       # compare inodes to see who shares a namespace\nnsenter -t <pid> -m -u -i -n -p bash\nunshare --fork --mount-proc --pid --net --uts --ipc bash   # a manual container shell\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FlagIsolates
CLONE_NEWNSMount table
CLONE_NEWPIDProcess ids
CLONE_NEWNETNetwork stack
CLONE_NEWUTSHostname and domain name
CLONE_NEWIPCSystem V IPC and POSIX message queues
CLONE_NEWUSERUid and gid mappings
CLONE_NEWCGROUPThe cgroup root the process sees
CLONE_NEWTIMEBoot-time and monotonic clock offsets
\n
#define _GNU_SOURCE\n#include <sched.h>\n#include <sys/mount.h>\n#include <unistd.h>\n\nstatic int container_init(void *arg)\n{\n    sethostname(\"container\", 9);\n    mount(\"proc\", \"/proc\", \"proc\", 0, NULL);\n    execv(\"/bin/sh\", (char *[]){\"/bin/sh\", NULL});\n    return 1;\n}\n\nstatic char stack[1024 * 1024];\n/* The child stack grows down, so pass the top of the buffer. */\nclone(container_init, stack + sizeof stack,\n      CLONE_NEWPID | CLONE_NEWNS | CLONE_NEWNET | SIGCHLD, NULL);\n
\n
    \n
  1. Apply a cgroups v2 limit. The unified hierarchy at /sys/fs/cgroup exposes one directory per group; a process joins by writing its pid to cgroup.procs. Done when: the limit file holds the value and memory.events or cpu.stat shows the effect under load.
    2. \n
\n
mkdir /sys/fs/cgroup/mycontainer\necho $$ > /sys/fs/cgroup/mycontainer/cgroup.procs\necho 256M > /sys/fs/cgroup/mycontainer/memory.max     # hard memory limit\necho 50 > /sys/fs/cgroup/mycontainer/cpu.weight        # share relative to siblings; default 100\necho \"50000 100000\" > /sys/fs/cgroup/mycontainer/cpu.max   # quota and period in microseconds\necho \"default 100\" > /sys/fs/cgroup/mycontainer/io.weight\ncat /proc/self/cgroup\ncat /sys/fs/cgroup/mycontainer/memory.events           # oom and oom_kill counters\n
\n
    \n
  1. Build the filesystem with overlayfs. Reads fall through to the lower layers; writes land in the upper directory; workdir is overlayfs bookkeeping and must be empty and on the same filesystem as upperdir. Done when: the merged mount shows the union and a write appears only in upperdir.
    2. \n
\n
mount -t overlay overlay -o lowerdir=lower1:lower2,upperdir=upper,workdir=work merged\n
\n

Docker's overlay2 driver keeps its layers under /var/lib/docker/overlay2.

\n
    \n
  1. Run the bundle with runc. runc spec writes a config.json whose ociVersion matches the installed runtime (runc 1.5.1 writes 1.3.0); do not hand-edit that field. Edit process.args, linux.namespaces, linux.resources, process.capabilities, and linux.seccomp. Done when: runc run starts the container and runc list shows it.
    2. \n
\n
mkdir -p mycontainer/rootfs        # populate rootfs first\nrunc spec -b mycontainer           # add --rootless when not root\nrunc run -b mycontainer mycontainer\nrunc list\n
\n
    \n
  1. Filter syscalls with seccomp-bpf. Done when: the filter loads and the blocked syscall returns the chosen action.
    2. \n
\n
#include <seccomp.h>\n#include <errno.h>\n\nscmp_filter_ctx ctx = seccomp_init(SCMP_ACT_ALLOW);\nseccomp_rule_add(ctx, SCMP_ACT_ERRNO(EPERM), SCMP_SYS(mount), 0);\nseccomp_rule_add(ctx, SCMP_ACT_ERRNO(EPERM), SCMP_SYS(pivot_root), 0);\nseccomp_load(ctx);\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ActionEffect
SCMP_ACT_KILL_PROCESSKill the whole process (SCMP_ACT_KILL kills only the calling thread)
SCMP_ACT_ERRNO(n)Fail the call with errno n
SCMP_ACT_TRAPDeliver SIGSYS
SCMP_ACT_TRACENotify a ptrace tracer
SCMP_ACT_LOGAllow and write an audit record
SCMP_ACT_NOTIFYHand the call to a user-space supervisor
SCMP_ACT_ALLOWPermit
\n

Docker's default profile ships in the moby repository under profiles/seccomp/default.json. To find the syscall a profile is missing, run the workload under strace -f first.

\n
    \n
  1. Drop capabilities. A container process should run as non-root with the smallest bounding set that still works. Done when: capsh --print or getcap shows only the intended capabilities.
    2. \n
\n
capsh --drop=all --caps=\"cap_net_bind_service+eip\" -- -c '/app/server'\nsetcap cap_net_bind_service+ep /usr/bin/myserver\ngetcap /usr/bin/myserver\n
\n
    \n
  1. Explain rootless mode. A user namespace maps container uid 0 to an unprivileged host uid, so root inside is an ordinary user outside. Rootless containers cannot mount most filesystems and hold no CAP_SYS_ADMIN on the host. Done when: /proc/<pid>/uid_map for the container shows the mapping.
    2. \n
\n
cat /proc/self/uid_map      # \"0 1000 1\" maps container uid 0 to host uid 1000\n
\n
    \n
  1. Stack the escape mitigations: user namespace, seccomp, a mandatory access control profile (AppArmor or SELinux), a dropped capability set, a read-only root, no-new-privileges, and Landlock for filesystem scope. Known escape vectors are a mounted container-engine socket, privileged mode, kernel CVEs, and /proc leaks. Done when: each layer in use is named and the missing ones are listed.
    2. \n
\n
docker run --read-only --cap-drop=ALL --security-opt=no-new-privileges \\\n  --security-opt seccomp=default.json myimage\n
\n

For policy depth (SELinux, AppArmor, seccomp) use kernel-security. To trace what a container does at the syscall level, use ebpf. For the kernel side of cgroups and namespaces, use kernel-internals.

\n

Failure and recovery

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Failure classBehavior
Container OOM-killedmemory.max was exceeded; memory.events shows oom_kill. Raise the limit or fix the leak.
CPU throttledcpu.max quota is low; cpu.stat shows nr_throttled. Raise the quota or use cpu.weight for a soft share.
Permission denied inside the containerA needed capability was dropped. Add that one capability, not CAP_SYS_ADMIN.
Killed by seccomp at startThe profile lacks a syscall the runtime needs. Find it with strace -f and allow that syscall only.
Overlay mount failsworkdir is not empty or sits on a different filesystem than upperdir. Clean it and retry.
Rootless mount failsThe user namespace forbids it. Bind-mount from the host instead.
\n

Output

\n

The primitive used for each isolation or limit, the commands run, the observed effect, and the teardown list: cgroup directories to remove, mounts to unmount, and processes to stop.

\n","files":[{"path":"agents/openai.yaml","sizeBytes":233,"isText":true},{"path":"SKILL.md","sizeBytes":8132,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-30T19:52:15.199984Z","sha256":"69B274E15A4A15CC0B1E943A165FCA82786FFD0FD081EC418EFFD7CAD5872918","sizeBytes":3931},"review":null,"source":{"repositoryUrl":"https://github.com/OutlineDriven/outline-driven-development","path":".devin/skills/containers-internals","license":"Apache-2.0","commit":"b0e8ce89a19fac880251dc3ea1babfeb4503a4fe","subtreeSha":"9145805D20CA4A12446BAC81FBBFBCA3A4683A6E0CEA8C0533F50ED223B573F6","lastSyncedAt":"2026-09-30T19:49:48.917811Z"},"reviewedAt":"2026-09-30T19:56:37.906485Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/OutlineDriven/outline-driven-development/tree/main/.devin/skills/containers-internals"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install outlinedriven-outline-driven-development@llmmart"},{"target":"git","command":"git clone https://github.com/OutlineDriven/outline-driven-development.git"}]}