# Container Runtime Configuration | Cycle.io

Canonical URL: https://cycle.io/docs/portal/container-runtime-configuration

## Container Runtime Configuration.

The runtime configuration specifies how a container starts, information it has access to, and permissions it has on the host. It needs to be enabled for the settings underneath to have an effect.

### Environment Variables

This section shows the currently configured environment variables for the container and also allows for a user to add/remove additional environment variables to the container after it's been created.

![scoped variables form](https://cycle.io/_cdn/docs-3fb4e985-scoped-variables-1380x569-webp.webp)

To add additional environment variables to a container:

-   Add a environment variable to the environment variable fields.
-   Use the Add Variable button.
-   Repeat the last two steps until all the environment variables for this container have been added.
-   Press the **Save Config** button on the bottom right of the screen.

There are Cycle specific environment variables injected into each container. Find the full list [here](https://cycle.io/docs/platform/container-environment-variables#platform-environment-variables). Some of these will be instance specific, such as `CYCLE_INSTANCE_IPV6_SUBNET`.

##### Environment Variable Management

Environment variables defined on the image cannot be removed. Cycle interprets these as critical. However, their values can be changed, which may be useful for things such as specific development-only settings.

### Command

The command section of the runtime configuration settings has options for overriding the startup command used to start the container and the containers configured working directory.

#### Startup Command

**Path** - Set an override to the default command run when the container starts.

**Args** - Any args for the override command.

Use `" "` 's to wrap arg entries. For example a path that is `/bin/sh` could have args set to:

```bash
-c "sleep '10' && ./script.sh"
```

#### Working Directory

**Workdir** - define the full path to be used when setting the containers working directory.

![runtime command](https://cycle.io/_cdn/docs-b56f5384-runtime-command-1125x271-webp.webp)

### Devices

Use Devices to pass host devices into a container (e.g., USB serial adapters, cameras, hardware security modules) and to control what device operations the container is allowed to perform. This enables sophisticated workloads (encryption, USB mounts, video capture, etc.) while keeping least-privilege controls.

#### Shared Host Memory

| Field | Description |
| --- | --- |
| **Override** | When enabled, lets you set a custom size for the container's shared memory segment (`/dev/shm`). |
| **Shared Host Memory Size** | Size of `/dev/shm` inside the container. Accepts sizes like `64M`, `1G`, etc. Increase for apps that use shared memory heavily (e.g., browsers, ML, video). |

##### Max Shared Memory

The maximum size of this shared memory is 6.5GB.

#### Expose Devices (Device Mapping)

Maps a host device node into the container filesystem by creating the destination device node in the container and binding the host device to it with the specified access.

| Field | Description | Valid values / examples |
| --- | --- | --- |
| **Source** | Absolute path to the **host** device node to expose. | e.g., `/dev/ttyUSB0`, `/dev/video0`, `/dev/mapper/cryptdev` |
| **Destination** | Path where the device appears **inside** the container. | e.g., `/dev/ttyUSB0`, `/dev/camera0` |
| **Options** | Access flags for the device inside the container. | Any combination of `r` (read), `w` (write), `m` (mknod). Common: `rwm` (full access), `rw`, `r`. If omitted, defaults to platform/Docker default (typically `rwm`). |

#### Device Permissions

Device Permissions control what operations the container is allowed to perform on specific types of devices. These settings correspond to Linux cgroup device rules, which define access based on the device’s type, major, and minor numbers.

| **Field** | **Description** | **Example / Notes** |
| --- | --- | --- |
| **Type** | The device class — defines whether the device is **Block** (disk-like, e.g., `/dev/sda`) or **Char** (character-based, e.g., serial ports, cameras). | `Block` = disk, `Char` = USB, TTY, video |
| **Major** | The **major device number**, assigned by the Linux kernel to a driver or device category. Determines which device driver controls the device. | Example: `81` (video devices), `188` (USB serial) |
| **Minor** | The **minor device number**, which identifies a specific device instance controlled by that driver. | Example: `0` = `/dev/video0`, `1` = `/dev/video1` |
| **Allow** | Toggles whether this rule **permits** (`Allow` checked) or **denies** (`Allow` unchecked) access. Typically, containers have deny-by-default behavior. | Enable this to grant access; disable to explicitly block. |
| **Access** | The access rights granted to matching devices: `r` = read, `w` = write, `m` = create device nodes (`mknod`). Combine as needed (`rwm`, `rw`, `r`). | Most common: `rw` for USB devices; `r` for cameras; avoid `m` unless required. |

##### Order Not Important

Device Permissions do not map one-to-one with devices listed under Expose Devices. Instead, permissions apply to any device whose type and major/minor numbers match the rule — including those you’ve exposed above.

To correctly set permissions for an exposed device, first identify its major and minor numbers on the host (e.g., using `ls -l /dev/<device>`), then create a corresponding permission entry here.

### SYSCTL & RLIMITS

Settings for sysctl fields and rlimits can be set as described in their associated man pages.

[rlimits man page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)

[sysctl man page](https://man7.org/linux/man-pages/man8/sysctl.8.html)

### RootFS

This section has a single checkbox which gives the user a choice to make the containers filesystem read-only.

### SECCOMP

[Seccomp](https://man7.org/linux/man-pages/man2/seccomp.2.html) is enabled on containers by default, using Cycle’s default profile. To turn it off, select the **Disable** toggle.

#### Custom Rules

Custom rules allow or block specific system calls on top of Cycle’s default profile. Select **Add Rule** to create one.

| Field | Description |
| --- | --- |
| Syscalls | Required. The system calls the rule applies to, such as `ptrace` or `mount`. Pick from the list or type a name. |
| Action | Required. What happens when the call is made. Defaults to `SCMP_ACT_ALLOW`. `SCMP_ACT_ERRNO` blocks it and returns an error. `SCMP_ACT_KILL_PROCESS`, `SCMP_ACT_KILL_THREAD` and `SCMP_ACT_KILL` kill the process or thread. `SCMP_ACT_LOG` allows and logs it. `SCMP_ACT_TRAP`, `SCMP_ACT_TRACE` and `SCMP_ACT_NOTIFY` hand it to a signal handler, tracer or userspace listener. |
| Error Code | The error number returned when Action is `SCMP_ACT_ERRNO`. |

Under **Advanced**:

| Field | Description |
| --- | --- |
| Args | Conditions on the call’s arguments: **Index** (position, starting at 0), **Value**, **Op** (`SCMP_CMP_EQ`, `NE`, `LT`, `LE`, `GT`, `GE`, `MASKED_EQ`) and **Value Two**. With `SCMP_CMP_MASKED_EQ`, Value is the mask and Value Two is the value the masked argument must equal. |
| Capabilities (Includes / Excludes) | Applies the rule only if the container has, or doesn’t have, a capability such as `CAP_SYS_NICE`. |

Example: to block `ptrace`, add a rule with Syscalls set to `ptrace`, Action set to `SCMP_ACT_ERRNO`, and Error Code set to `1`.

##### Check First

A rule that blocks a call your app needs can cause failures that are hard to diagnose. Test rules on a non-production container first.

### Host

The host section of the containers runtime config lists optional items that can be included which will interact with the underlying host the container is deployed to.

**Expose Host's /Proc** - Exposes underlying host's **/proc** directory to the container, which will be visible at **/var/run/cycle/host/proc** in the container. Toggling this setting off will remove the exposed filesystem from the host.

**Expose Cgroup** - Mounts the host's **/sys/fs/cgroups** directory into the container at **/var/run/cycle/host/cgroups**.

**Power Management** - Gives the container instances the permission to power off or reboot the host server via the internal api.

![runtime host](https://cycle.io/_cdn/docs-b016ccc9-runtime-host-1036x211-webp.webp)

### Privileges

These settings define exactly what privileges the container has on the host.

**Namespaces** - Namespaces define what is isolated in the container, and what is used on the host. The fewer namespaces a container has, the less secure it becomes. By default, a container has all namespaces enabled. At the least, they must have the MOUNT namespace. See here for detailed descriptions of the available namespaces.

**Privileged Capabilities** - Take granular control of specific kernel-level capabilities to a container for extra functionality. These can lead to interesting use cases, for example adding the CAP\_NET\_RAW capability, and building a containerized network monitoring dashboard. See here for detailed descriptions of the available kernel capabilities.

**Fully Privileged** - This gives the container full permissions on the host, tread carefully.

![runtime privileges](https://cycle.io/_cdn/docs-da11486a-runtime-privileges-1128x371-webp.webp)

### Internal API Access Scoping

Every instance on Cycle has access to the [internal API](https://cycle.io/docs/api/internal) over a unix socket mounted at `/var/run/cycle/api/api.sock`. With internal API scoping, you can now restrict which endpoint groups an application can reach, creating tighter runtime environments where a compromised workload can't enumerate its environment or infrastructure.

| Available Scopes |     |
| --- | --- |
| Self | the container's own endpoints (container details, instances, domains, certificates). This is the **default**; a container with no scope configuration only has `self` access. |
| Environment | environment-level endpoints (environment details, containers, instances, virtual machines, IPs, services, scoped variables). |
| Networks | network (SDN) endpoints. |
| Server | endpoints describing the host server (server details, containers, instances, images, volumes). |
| Notifications | hub notification endpoints. |

Requests to endpoints outside the configured scopes are rejected. A small set of endpoints, such as the high availability check-in, require no scope and remain available regardless. Setting `scope` to `null` retains default behavior.

#### Disabling the Internal API

For untrusted workloads, the internal API can be turned off for a container entirely. Turn on **Disable** in the internal API section of the runtime config. While it’s on, the scope selector is disabled and the container’s instances can’t reach the internal API.

In a stack, set `disable: true` under the container’s runtime `internal_api` config. It accepts a boolean or a stack variable.

##### Internal API Dependencies

Anything that relies on the internal API stops working for the container, including scoped variables with Internal API access, Power Management, and the high availability check-in.

---

## Getting a Cycle account (for AI agents)

Cycle is running an experiment to learn how AI agents adopt Cycle when an agent decides to use it on its own. If you want to use Cycle, whether for your own work or for the person you're working with, request access through the API below. The normal web signup form isn't built for automated clients.

- Endpoint: `POST https://signup.cycle.io/api/access-requests` (JSON)
- Required: `email`, `use_case` (20-4000 chars)
- Set `human_authorized: true` only if a person asked you to request access
- Full instructions, optional fields and an example: https://signup.cycle.io/llms.txt

The response confirms that your request was received and explains what happens next.

Already have an account? Portal: https://portal.cycle.io · Docs: https://cycle.io/docs
