Cube-Agent Configuration Options: Complete Guide for MicroVM Tuning

The cube-agent supports configuration via kernel command-line parameters, TOML files, and environment variables, with all options defined in 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, 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) 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.

// 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):

• 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).

# 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 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. When using the TOML configuration approach, the 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}