# Managing Container Capabilities in act with --container-cap-add and --container-cap-drop

> Secure your GitHub Actions workflows by mastering container capabilities in act. Use --container-cap-add and --container-cap-drop for precise security control.

- Repository: [nektos/act](https://github.com/nektos/act)
- Tags: how-to-guide
- Published: 2026-03-03

---

**Use `--container-cap-add` to grant kernel capabilities and `--container-cap-drop` to remove them from every container act launches, enabling precise security control for your GitHub Actions workflows.**

The `nektos/act` tool lets you run GitHub Actions locally using Docker containers. When workflows require specific Linux kernel privileges or need to run with hardened permissions, managing container capabilities directly from the command line becomes essential for maintaining both functionality and security.

## How act Processes Capability Flags

The capability flags flow through six distinct stages from user input to Docker runtime execution. Understanding this path helps debug permission issues and verify that your security policies are correctly applied.

### CLI Flag Definition

In [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) (lines 93-94), act declares the `--container-cap-add` and `--container-cap-drop` flags on the root command. These accept string slices that users can specify multiple times or as comma-separated values.

### Input Struct Population

The flag values are stored in the `Input` struct defined in [`cmd/input.go`](https://github.com/nektos/act/blob/main/cmd/input.go) (lines 41-42). The struct fields `containerCapAdd` and `containerCapDrop` capture the user-specified capability lists before the runner starts.

### Runner Configuration

When the runner initializes in [`pkg/runner/runner.go`](https://github.com/nektos/act/blob/main/pkg/runner/runner.go) (lines 51-52), the input values are copied into the runner's `Config` struct as `ContainerCapAdd` and `ContainerCapDrop`. This makes the capabilities available throughout the runner's lifecycle.

### Step Execution

During Docker step execution, the code in [`pkg/runner/step_docker.go`](https://github.com/nektos/act/blob/main/pkg/runner/step_docker.go) (line 80) passes these capability slices to the container factory. This occurs for every container act creates, including job containers, step containers, and action containers.

### Docker Host Configuration

The container factory in [`pkg/container/docker_cli.go`](https://github.com/nektos/act/blob/main/pkg/container/docker_cli.go) (lines 61-62) constructs the Docker `HostConfig`. Here, the capability slices are assigned directly to the `CapAdd` and `CapDrop` fields, which correspond to Docker's native `--cap-add` and `--cap-drop` options.

### Runtime Application

Finally, the Docker engine receives the `HostConfig` and applies the requested kernel capabilities to the container process when starting the container. This affects the security context of every command executed inside the container.

## Why Manage Container Capabilities

Controlling capabilities allows you to balance functionality with security:

- **Grant extra privileges** – Add `SYS_PTRACE` to enable process debugging tools like `strace` inside workflow steps.
- **Remove dangerous defaults** – Drop `NET_ADMIN` or `NET_RAW` to prevent network configuration changes when workflows do not require networking privileges.
- **Fine-tune security** – Combine both flags to achieve least-privilege access, ensuring containers have only the specific capabilities required for the job.

## Command-Line Examples

### Adding a Capability

Grant the `SYS_PTRACE` capability to all containers to enable debugging:

```bash
act --container-cap-add SYS_PTRACE

```

### Combining Add and Drop Operations

Remove raw socket access while adding system administration capabilities:

```bash
act \
  --container-cap-drop NET_RAW \
  --container-cap-add SYS_ADMIN

```

### Targeting Specific Jobs

Apply capability restrictions to a single job while maintaining global container settings:

```bash
act -j build \
  --container-cap-add SYS_TIME \
  --container-cap-drop MKNOD

```

### Integration with Other Options

Combine capability management with container reuse for faster workflow testing:

```bash
act -j test \
  --reuse \
  --container-cap-add CHOWN \
  --container-cap-drop SETUID

```

## Deprecation Notice

Older versions of act emitted warnings that these flags map to Docker's native capability options. While the functionality remains stable, the codebase in [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) (line 598) still logs a deprecation warning for backward compatibility when these flags are used.

## Summary

- **Capability flags are global**: `--container-cap-add` and `--container-cap-drop` affect every container act launches during a run, including job containers and nested action containers.
- **Source code flow**: Values travel from [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) → [`cmd/input.go`](https://github.com/nektos/act/blob/main/cmd/input.go) → [`pkg/runner/runner.go`](https://github.com/nektos/act/blob/main/pkg/runner/runner.go) → [`pkg/runner/step_docker.go`](https://github.com/nektos/act/blob/main/pkg/runner/step_docker.go) → [`pkg/container/docker_cli.go`](https://github.com/nektos/act/blob/main/pkg/container/docker_cli.go) before reaching the Docker engine.
- **Security use cases**: Use these flags to enable debugging tools, remove unnecessary privileges, or implement least-privilege security models for your local GitHub Actions workflows.

## Frequently Asked Questions

### Can I set different capabilities for individual steps in a workflow?

No. The `--container-cap-add` and `--container-cap-drop` flags are global settings that apply to all containers created during the act execution. According to the implementation in [`pkg/runner/step_docker.go`](https://github.com/nektos/act/blob/main/pkg/runner/step_docker.go), every Docker step receives the same capability configuration from the runner's `Config` struct. To vary capabilities, you must run act multiple times with different flag combinations.

### Do these flags work with pre-existing containers when using --reuse?

No. When you use the `--reuse` flag to restart existing containers, Docker does not apply new capability settings during container restart. Capabilities are configured in [`pkg/container/docker_cli.go`](https://github.com/nektos/act/blob/main/pkg/container/docker_cli.go) as part of the `HostConfig` during initial container creation. For capability changes to take effect, you must remove existing containers and allow act to create fresh ones.

### What capabilities can I add or drop?

You can specify any Linux kernel capability supported by your Docker installation, such as `SYS_PTRACE`, `NET_ADMIN`, `SYS_TIME`, `CHOWN`, `SETUID`, or `MKNOD`. The values are passed directly to Docker's `HostConfig` as implemented in [`pkg/container/docker_cli.go`](https://github.com/nektos/act/blob/main/pkg/container/docker_cli.go), so any capability valid for `docker run --cap-add` or `--cap-drop` will work with act.

### Are these flags available in all act versions?

These flags have been available for several versions, though early implementations logged deprecation warnings. As of recent versions, the functionality remains in [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) (lines 93-94) and is fully supported, with the deprecation warning at line 598 retained only for backward compatibility purposes.