<!-- SPDX-License-Identifier: Apache-2.0 -->

# Security boundaries

CireilClaw executes tools and optional plugins on behalf of configured agents.

The runtime root contains configuration, session data, media, plugin state, and credentials; restrict write access to it and to the OAuth credential files below `config/`.

## Command execution

Use the configured sandbox for tool execution whenever possible.

The sandbox is the least-privilege command boundary between an agent and the host.
It is not equivalent to conditional file-access rules: a command allowed through `exec` can inspect, copy, or transform anything visible inside its sandbox.

The documented raw-container sandbox bypass (`CIREILCLAW_RUNTIME_INSECURE_DISABLE_SANDBOX_I_AM_100_PERCENT_SURE`) disables Bubblewrap filesystem isolation and is an explicit insecure opt-in; it does not make arbitrary commands safe.
The documented value is `i-am-in-a-container`.
The source also accepts `babe-i-brought-protection` and `we-are-literally-transbians-what` as intentional easter eggs retained for source parity; any other value leaves the sandbox in place.

## Diagnostic logging

The runtime intentionally records complete tool input and output payloads in its rolling JSON log files.
These payloads can contain conversation text, file contents, provider responses, plugin configuration, credentials, attachments, and other sensitive data.
The file sink persists verbose events independently of the console log level.
The host retains up to 14 files of 10 MiB each under `<root>/logs`.
Treat the log directory as sensitive runtime data and restrict access to the runtime owner.
On the supported Linux deployment, the runtime applies owner-only Unix permissions when it creates the log directory and files.

## Plugins

Plugins are trusted host extensions that run inside the runtime process.
Give plugins only the configuration and network access they need, and install plugin packages from sources you trust.

A plugin tool that replaces a built-in tool changes part of the boundary the runtime presents to the agent; grant `allowOverride` only deliberately.

## Credentials

Provider tokens, Discord tokens, and OAuth credentials are secrets.
Rotate a token if it is exposed, and never commit credentials to source control.
