Skip to main content
skill CX Codex

containers-internals — skill for Claude Code: namespaces, cgroups, OCI

containers-internals is a Claude Code skill for Linux container internals, activated for queries about namespaces, runc, seccomp, and escape vulnerabilities.

MIT 358 installs ★ 298 updated 2026-06-27

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add mohitmishra786/low-level-dev-skills --skill containers-internals -a claude-code
Open on GitHub

What containers-internals does

Available in Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. Covers the full container stack: system calls like clone() and unshare(), OCI spec config in config.json, cgroup resource management via /sys/fs/cgroup, and seccomp filter authoring with libseccomp. Includes C and bash examples for building minimal containers from scratch, debugging OOM and CPU throttling, and migrating between cgroups v1 and v2.

Requires basic Linux syscall knowledge and access to systems with cgroup v2 enabled. Activates on queries about namespaces, overlayfs, runc, seccomp-bpf, OCI spec, and escape vectors. Reference includes seccomp action tables (SCMP_ACT_KILL, SCMP_ACT_ERRNO, SCMP_ACT_ALLOW), complete namespace list with CLONE_* flags, and defense-in-depth: rootless containers, user namespace, AppArmor/SELinux, capability dropping, and read-only rootfs.

What it helps with

  • debug OOM and CPU throttling using cgroups v2
  • write and apply a seccomp profile to a container
  • build a minimal container with unshare and clone without Docker
  • investigate and block container escape vectors
  • configure rootless containers with UID/GID mapping

Example prompts for the agent

  • Show me how to debug container memory: read memory.events from cgroups v2 and spot a leak
  • Write C code using clone() with CLONE_NEWPID and CLONE_NEWNS to spin up a bare-bones container
  • Explain how to author and load a seccomp profile with libseccomp to block mount and pivot_root

How to install containers-internals

1Skills CLI (Vercel)

npx skills add mohitmishra786/low-level-dev-skills --skill containers-internals -a claude-code

2Manually: put the files in place

~/.claude/skills/containers-internals/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/containers-internals/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about containers-internals

How do I install containers-internals?

Run the command for your platform: on Claude Code, npx skills add mohitmishra786/low-level-dev-skills --skill containers-internals -a claude-code then ~/.claude/skills/containers-internals/SKILL.md; on GitHub Copilot, gh skill install mohitmishra786/low-level-dev-skills containers-internals; on Cursor, npx skills add mohitmishra786/low-level-dev-skills --skill containers-internals -a cursor then ~/.cursor/skills/containers-internals/SKILL.md.

What does containers-internals cover?

It explains how Linux containers work: namespaces isolate processes, network stacks, and filesystems; cgroups v2 enforce memory and CPU limits; overlayfs layers images; OCI runtime spec defines the container config; seccomp-bpf filters syscalls; Linux capabilities drop privileges; and defense layers prevent escape.

What is the difference between cgroups v1 and v2?

cgroups v2 uses a single unified hierarchy instead of separate hierarchies for memory, CPU, and I/O, with simpler syntax in /sys/fs/cgroup. The skill shows how to set limits with memory.max and cpu.weight, and read events from memory.events.

Source text

SKILL.md · MIT
---
name: containers-internals
description: Linux containers internals skill for namespaces, cgroups, and OCI. Use when understanding clone/unshare namespaces, cgroups v2 limits, overlayfs, runc, seccomp profiles, capabilities, or escape mitigations. Activates on queries about namespaces, cgroups, overlayfs, runc, seccomp-bpf, OCI spec, or container escape.
---

# Containers Internals

## Purpose

Guide agents through Linux container internals: namespaces (`clone`, `unshare`, `nsenter`), cgroups v2 resource limits, overlayfs storage, runc and the OCI runtime spec, seccomp-bpf filtering, Linux capabilities for privilege dropping, and container escape mitigations.

## When to Use

- Understanding how Docker/Podman isolate processes under the hood
- Debugging container resource limits (OOM, CPU throttling)
- Writing custom seccomp profiles for sandboxed workloads
- Building minimal containers without Docker
- Investigating container escape vulnerabilities
- Tuning cgroups v2 for Kubernetes pods

## Workflow

### 1. Namespaces

```bash
# List namespaces for a process
ls -la /proc/self/ns/
readlink /proc/self/ns/pid
readlink /proc/1234/ns/net

# Enter container namespaces
nsenter -t <pid> -m -u -i -n -p bash

# Unshare namespaces (manual container)
unshare --fork --mount-proc --pid --net --uts --ipc bash
```

| Namespace | Isolates |
|-----------|----------|
| `CLONE_NEWNS` (mount) | Mount points, filesystem roots |
| `CLONE_NEWPID` | Process IDs |
| `CLONE_NEWNET` | Network stack |
| `CLONE_NEWUTS` | Hostname |
| `CLONE_NEWIPC` | SysV IPC, POSIX message queues |
| `CLONE_NEWUSER` | UID/GID mappings |
| `CLONE_NEWCGROUP` | cgroup root view |

```c
// clone() with namespaces
#define _GNU_SOURCE
#include <sched.h>

int container_init(void *arg) {
    sethostname("container", 9);
    mount("proc", "/proc", "proc", 0, NULL);
    execv("/bin/sh", (char *[]){"/bin/sh", NULL});
    return 1;
}

int stack[1024 * 1024];
clone(container_init, stack + sizeof(stack)/sizeof(int),
      CLONE_NEWPID | CLONE_NEWNS | CLONE_NEWNET | SIGCHLD, NULL);
```

### 2. cgroups v2

```bash
# Unified hierarchy (cgroup v2)
mount -t cgroup2 none /sys/fs/cgroup

# Create cgroup and set limits
mkdir /sys/fs/cgroup/mycontainer
echo $$ > /sys/fs/cgroup/mycontainer/cgroup.procs

# Memory limit 256MB
echo 256M > /sys/fs/cgroup/mycontainer/memory.max

# CPU weight (relative to siblings, default 100)
echo 50 > /sys/fs/cgroup/mycontainer/cpu.weight

# IO weight
echo default 100 > /sys/fs/cgroup/mycontainer/io.weight
```

```bash
# Check current cgroup
cat /proc/self/cgroup

# OOM events
cat /sys/fs/cgroup/mycontainer/memory.events
```

### 3. overlayfs

```
overlayfs layers
├── lowerdir (read-only image layers)
├── upperdir (container writes)
├── workdir (internal bookkeeping)
└── merged (mount point seen by container)
```

```bash
mount -t overlay overlay \
  -o lowerdir=lower1:lower2,upperdir=upper,workdir=work \
  merged

# Docker stores layers in /var/lib/docker/overlay2/
```

Copy-on-write: reads from lower, writes go to upper.

### 4. runc and OCI spec

```bash
# Generate default OCI config
mkdir -p mycontainer/rootfs
runc spec

# Edit config.json — namespaces, mounts, process args
# Run container
sudo runc run mycontainer

# List
runc list
```

`config.json` key sections:

```json
{
  "ociVersion": "1.0.2",
  "process": {
    "args": ["/bin/sh"],
    "capabilities": { "bounding": ["CAP_NET_BIND_SERVICE"] }
  },
  "linux": {
    "namespaces": [
      {"type": "pid"}, {"type": "network"}, {"type": "mount"}
    ],
    "seccomp": { ... },
    "resources": {
      "memory": { "limit": 268435456 }
    }
  },
  "root": { "path": "rootfs", "readonly": false }
}
```

### 5. seccomp-bpf

```c
// libseccomp example — block mount
#include <seccomp.h>

scmp_filter_ctx ctx = seccomp_init(SCMP_ACT_ALLOW);
seccomp_rule_add(ctx, SCMP_ACT_ERRNO(EPERM), SCMP_SYS(mount), 0);
seccomp_rule_add(ctx, SCMP_ACT_ERRNO(EPERM), SCMP_SYS(pivot_root), 0);
seccomp_load(ctx);
```

```bash
# Docker default seccomp profile (JSON)
# https://github.com/moby/moby/blob/master/profiles/seccomp/default.json

# Audit blocked syscalls
# kernel: seccomp log via auditd
ausearch -m SECCOMP
```

| Action | Effect |
|--------|--------|
| `SCMP_ACT_KILL` | Kill process |
| `SCMP_ACT_ERRNO(n)` | Return error |
| `SCMP_ACT_TRACE` | Notify tracer |
| `SCMP_ACT_ALLOW` | Permit syscall |

### 6. Linux capabilities

```bash
# Drop all caps except needed
capsh --drop=all --add=net_bind_service -- -c '/app/server'

# File capabilities
setcap cap_net_bind_service+ep /usr/bin/myserver
getcap /usr/bin/myserver
```

In containers: default Docker drops `CAP_SYS_ADMIN`, `CAP_NET_RAW`, etc. Run as non-root with minimal bounding set.

### 7. User namespace rootless

```bash
# Rootless podman/docker maps root in container to unprivileged UID on host
cat /proc/self/uid_map
#          0       1000          1
# container UID 0 → host UID 1000
```

Rootless limits: cannot mount most filesystems, no `CAP_SYS_ADMIN`.

### 8. Escape mitigations

```
Defense layers
├── User namespace (rootless)
├── seccomp (block dangerous syscalls)
├── AppArmor/SELinux (MAC)
├── Capabilities drop (--cap-drop=ALL)
├── Read-only rootfs
├── no-new-privileges
└── Seccomp + Landlock for filesystem
```

```bash
docker run --read-only --cap-drop=ALL --security-opt=no-new-privileges \
  --security-opt seccomp=default.json myimage
```

Known escape vectors: mounted docker.sock, privileged mode, kernel CVEs, `/proc` leaks.

## Common Problems

| Symptom | Cause | Fix |
|---------|-------|-----|
| Container OOMKilled | memory.max exceeded | Raise limit or fix leak |
| CPU throttled | cpu.max quota low | Adjust `cpu.max` or weight |
| Permission denied in container | Capability dropped | Add specific cap or fix app |
| seccomp kill on start | Missing syscall in profile | `strace` to find; allow syscall |
| overlay mount fail | workdir not empty | Clean workdir; check permissions |
| Rootless mount fail | User namespace limits | Use volume mounts from host |

## Related Skills

- `skills/virtualization/qemu-kvm` — VM isolation vs containers
- `skills/security/kernel-security` — SELinux, AppArmor, seccomp depth
- `skills/observability/ebpf` — trace container syscalls
- `skills/runtimes/binary-hardening` — seccomp and capabilities in production
- `skills/kernel/kernel-internals` — cgroups and namespaces in kernel
- `skills/profilers/strace-ltrace` — syscall tracing for seccomp tuning

© mohitmishra786 · MIT · mohitmishra786/low-level-dev-skills

Similar skills

All skills for DevOps and infrastructure →
systemd-services devops-skills systemd-services — a skill for Claude Code, Codex, Cursor and other platforms that authors and manages systemd units, timers and sockets. Runs whenever the agent touches background Linux services. CX Codex +1 600installs hardening-docker-containers-for-production mahipal hardening-docker-containers-for-production is a Claude Code skill that hardens Dockerfiles, images, and container runtime settings against CIS Docker Benchmark v1.8.0. It validates them with docker-bench-security, Hadolint, and Dockle. CX Codex +1 373installs 706-technologies-containers-docker Juan Antonio Breña Moral 706-technologies-containers-docker is a Claude Code skill for reviewing Java Dockerfiles, Maven image builds, jlink runtimes, and container security. CX Codex +1 225installs setup-docker-containers davila7 setup-docker-containers sets up Docker for development and production projects, covering multi-stage builds, Compose environments, and container workflows. CX Codex +1 740installs aws-containers aws aws-containers deploys containers on AWS: EKS, ECS, Fargate, ECR, Elastic Beanstalk. Use it when deploying, debugging, or optimizing containerized workloads. CX Codex +1 10,800installs deploying-containers-to-amazon-lightsail aws deploying-containers-to-amazon-lightsail — a Claude Code skill that deploys containers to Amazon Lightsail Container Service and diagnoses failed deployments. It handles images from a local Docker build, a public registry, or GitHub. CX Codex +1 900installs

From the same set140

The whole set →
io-uring Skill for working with io_uring, the new asynchronous I/O interface in Linux. Use it when building high-performance servers and you need to reduce syscall overhead and enable zero-copy data transfer. CX Codex +1 361installs arm-sve arm-sve — a skill for Scalable Vector Extension programming on ARM servers. Teaches vector-length agnostic SIMD code that adapts to hardware vector width on Graviton, Apple M4, and other AArch64 platforms. CX Codex +1 361installs af-xdp Configures AF_XDP sockets and shared UMEM buffers for low-latency packet processing. Helps implement fast network filtering directly in userspace. CX Codex +1 359installs triton-lang triton-lang is a Claude Code skill that teaches agents to write Triton GPU kernels with @triton.jit, masked block operations, atomics, autotuning, and PyTorch integration. CX Codex +1 358installs rdma-verbs rdma-verbs guides coding agents through RDMA programming using libibverbs for InfiniBand and RoCE fabrics. Useful when setting up queue pairs or perftest benchmarks. CX Codex +1 356installs riscv-privileged The riscv-privileged skill supports RISC-V kernel and firmware development, covering privileged modes, CSRs, traps, interrupt controllers, OpenSBI, page tables, and QEMU testing. CX Codex +1 355installs mpi Guides agents through distributed-memory programming with MPI, collective communications, hybrid OpenMP patterns, and mpirun execution. CX Codex +1 354installs verilog-basics-for-lowlevel verilog-basics-for-lowlevel — a skill that teaches firmware and kernel engineers to read Verilog RTL: modules, clocking, reset logic, bus protocols. Use it when docs are unclear and hardware behavior explains driver bugs. CX Codex +1 345installs

Project sponsors

Companies that keep this analytics open