# Cube-Agent Configuration Options: Complete Guide for MicroVM Tuning

> Explore cube agent configuration options for MicroVM tuning. Learn about kernel command-line, TOML, and environment variables with this complete guide.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: how-to-guide
- Published: 2026-07-05

---

**The cube-agent supports configuration via kernel command-line parameters, TOML files, and environment variables, with all options defined in [`agent/src/config.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/config.rs) and parsed through `AgentConfig::from_cmdline`.**

The cube-agent serves as the PID 1 init process inside every MicroVM within the TencentCloud CubeSandbox ecosystem. Understanding the available cube-agent configuration options is essential for tuning debug capabilities, logging behavior, and resource limits within the guest environment. All configuration logic resides in [`agent/src/config.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/config.rs), which defines the `AgentConfig` struct and its parsing methods.

## Configuration Sources and Precedence

The agent reads configuration from three sources in the following order:

1. **Kernel command-line parameters** (via `/proc/cmdline`)
2. **Environment variables** (when no explicit flags override them)
3. **TOML configuration file** (specified via `--config` or `-c`)

The `AgentConfig::from_cmdline` function (lines 21-92 in [`agent/src/config.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/config.rs)) processes tokens from `/proc/cmdline`, setting booleans directly for flags and invoking helper parsers like `get_log_level` and `get_hotplug_timeout` for options. After the command-line walk, specific environment variables are consulted, and finally, if a config file path is provided, the TOML overrides are applied via `AgentConfigBuilder`.

## Command-Line Parameters

The following parameters are read from the kernel command line during the `from_cmdline` parsing phase. Each option maps to a field in the `AgentConfig` struct.

### Debugging and Development Flags

- **`agent.debug_console`** – Enables the optional debug console attached to the VM (default: `false`, parsed at line 27).
- **`agent.devmode`** – Switches the agent into development mode with more permissive checks (default: `false`, parsed at line 28).
- **`agent.trace`** – Activates ttrpc tracing (default: `false`, parsed at lines 30-38).

### Logging and Server Settings

- **`agent.log`** – Sets the log severity level using the syntax `log=LEVEL` (default: `info`, parsed at line 40). Accepted values include `fatal`, `panic`, `critical`, `error`, `warn`, `warning`, `info`, `debug`, and `trace`.
- **`agent.server_addr`** – Specifies the address the agent listens on (default: `vsock://-1:1024`, parsed at lines 42-46). Supports both vsock and unix-socket schemes.
- **`agent.log_vport`** – Defines the virtual port for the log stream (default: `0`, parsed at lines 66-74).

### Resource and Timeout Configuration

- **`agent.hotplug_timeout`** – Sets the timeout duration for hot-plug operations (default: `3s`, parsed at lines 48-54).
- **`agent.container_pipe_size`** – Configures the size of the pipe used for container I/O (default: `0`, parsed at lines 76-84).
- **`agent.unified_cgroup_hierarchy`** – Toggles the unified cgroup v2 hierarchy inside the VM (default: `false`, parsed at lines 86-92).
- **`agent.debug_console_vport`** – Specifies the virtual port for the debug console (default: `0`, parsed at lines 56-64).

## TOML Configuration File

When the agent starts with `--config <file>` or `-c <file>`, it loads a TOML configuration via `AgentConfig::from_config_file`. The `AgentConfigBuilder` mirrors every option as an `Option<T>`, and any present field overwrites the defaults via the `config_override!` macro.

### Endpoint Whitelisting

The TOML file supports an `[endpoints]` table containing an `allowed` list of strings (lines 90-95). If provided, the list is converted into a `HashSet<String>` that whitelists specific ttrpc methods the agent will accept. If omitted, `all_allowed` defaults to `true`, permitting any method.

```rust
// Example: Loading configuration from a TOML file
let args = vec![
    "--config".to_string(),
    "agent.toml".to_string(),
];
let cfg = AgentConfig::from_cmdline("", args).expect("parse");

// Contents of agent.toml:
/*
dev_mode = true
server_addr = "unix:///tmp/agent.sock"
log = "debug"

[endpoints]
allowed = ["CreateContainer", "StartContainer"]
*/

```

## Environment Variable Overrides

The agent recognizes three environment variables that override command-line values when set (lines 34-38 in [`agent/src/config.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/config.rs)):

- **`KATA_AGENT_SERVER_ADDR`** – Overrides `agent.server_addr`.
- **`KATA_AGENT_LOG_LEVEL`** – Overrides `agent.log` (converted via `logrus_to_slog_level`).
- **`KATA_AGENT_TRACING`** – Overrides `agent.trace` (truthy values are interpreted as `true`).

```bash

# Override via environment variables for testing inside a container

export KATA_AGENT_SERVER_ADDR=vsock://-1:1234
export KATA_AGENT_LOG_LEVEL=warn
export KATA_AGENT_TRACING=1

# Start the binary normally

```

## Configuration Loading Implementation

The entry point in [`agent/src/main.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/main.rs) creates a global `AGENT_CONFIG` (an `Arc<RwLock<AgentConfig>>`) using `AgentConfig::from_cmdline`. This function walks each token from `/proc/cmdline`, applying the parsing logic defined in [`agent/src/config.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/config.rs). When using the TOML configuration approach, the [`deploy/one-click/build-vm-assets.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/deploy/one-click/build-vm-assets.sh) script demonstrates how the compiled `cube-agent` binary is injected into the guest image at `/sbin/init`.

## Summary

- **Configuration hierarchy**: Command-line parameters take precedence, followed by environment variables, then TOML file overrides.
- **Debug capabilities**: Enable `agent.debug_console` and `agent.trace` for troubleshooting, with optional virtual port configuration.
- **Logging control**: Set `agent.log` to any standard level from `fatal` to `trace`, or override via `KATA_AGENT_LOG_LEVEL`.
- **Security hardening**: Use the `[endpoints]` table in TOML to whitelist specific ttrpc methods instead of allowing all.
- **Resource tuning**: Adjust `agent.hotplug_timeout`, `agent.container_pipe_size`, and `agent.unified_cgroup_hierarchy` for specific MicroVM workloads.

## Frequently Asked Questions

### How do I change the cube-agent log level without modifying the VM image?

Set the `KATA_AGENT_LOG_LEVEL` environment variable before starting the agent. This overrides the default `info` level or any value specified in the kernel command line. Accepted values include `fatal`, `panic`, `critical`, `error`, `warn`, `info`, `debug`, and `trace`.

### What is the difference between `agent.devmode` and `agent.debug_console`?

The `agent.devmode` flag (parsed at line 28) enables development mode with more permissive security checks, while `agent.debug_console` (line 27) specifically enables an optional debug console attached to the VM. You can enable either independently, though both are typically used together during development.

### Can I restrict which ttrpc methods the cube-agent accepts?

Yes. Create a TOML configuration file with an `[endpoints]` section containing an `allowed` list of method names (e.g., `allowed = ["CreateContainer", "StartContainer"]`). When this list is present, the agent converts it to a `HashSet<String>` and rejects any method not explicitly whitelisted. If the `[endpoints]` table is omitted, `all_allowed` defaults to `true`, permitting all methods.

### Where does the cube-agent read its configuration from by default?

By default, the agent reads `/proc/cmdline` directly through the `from_cmdline` function to parse all `agent.*` parameters. It does not require a configuration file unless you explicitly pass `--config` or `-c` followed by a TOML file path.