How to Configure pi-computer-use Using Environment Variables and Config Files

pi-computer-use reads runtime settings from environment variables prefixed with PCU_ and an optional JSON configuration file, merging them in src/config.ts with environment values taking precedence over file-based settings.

The injaneity/pi-computer-use repository implements a hierarchical configuration system that supports both container-friendly environment variables and human-readable JSON files. This architecture allows you to manage sensitive credentials via shell exports or orchestration secrets while maintaining complex multi-value settings in version-controlled configuration files.

Configuration Architecture

The configuration system centers on src/config.ts, which exports a single configuration object consumed throughout the codebase. According to the source code, the loader executes a three-step process: first calling loadEnv() to extract all PCU_* prefixed variables from process.env, then reading the JSON configuration file from disk using fs.readFileSync, and finally merging both sources using deepMerge() where environment variables override any duplicate keys from the file.

This merged configuration object is then imported by src/runtime.ts to initialize the native OS bridge and by src/state.ts to maintain global application state.

Environment Variables

The application recognizes variables prefixed with PCU_. These map directly to configuration keys using camelCase conversion.

• PCU_SERVER_URL – Backend server endpoint the agent contacts. Defaults to http://localhost:3000.
• PCU_API_KEY – Authentication token for remote deployments. Required for production servers when not specified in config file.
• PCU_LOG_LEVEL – Internal logging verbosity. Accepts debug, info, warn, or error. Defaults to info.
• PCU_CONFIG_PATH – Absolute path to a custom JSON configuration file. When unset, the system uses the default location.
• PCU_DISABLE_BRIDGE – Set to true to disable the native OS bridge, enabling headless or containerized deployments. Defaults to false.
• PCU_MAX_CONCURRENCY – Maximum parallel actions the runtime may execute. Defaults to 4.

JSON Configuration File

By default, pi-computer-use searches for config.json at ~/.config/pi-computer-use/config.json. You can override this location by setting the PCU_CONFIG_PATH environment variable.

The JSON schema mirrors the environment variable keys using camelCase:

{
  "serverUrl": "https://my-pi-server.example.com",
  "apiKey": "my-super-secret-key",
  "logLevel": "debug",
  "maxConcurrency": 8,
  "disableBridge": false
}

All keys are optional. Missing values fall back to hardcoded defaults or environment variable overrides.

Configuration Precedence

When both an environment variable and a JSON entry define the same setting, the environment variable wins. This precedence rule is implemented in src/config.ts during the deepMerge() operation, making it trivial to override file-based configurations in CI pipelines or Docker containers without modifying static JSON files.

For example, if config.json sets "maxConcurrency": 4 but you export PCU_MAX_CONCURRENCY=12, the runtime uses 12.

Key Implementation Files

Understanding the file structure helps trace how configuration values flow through the system:

• src/config.ts – Central loader that orchestrates environment extraction, file parsing, and deep merging.
• src/runtime.ts – Consumes the configuration to conditionally instantiate the Bridge class based on config.disableBridge.
• src/state.ts – Maintains global state that references the configuration object for runtime decisions.

Practical Configuration Examples

Local development with a .env file:

# .env

PCU_SERVER_URL=https://my-pc-use.example.com
PCU_API_KEY=abcd1234
PCU_LOG_LEVEL=debug

Using a custom configuration path:

export PCU_CONFIG_PATH=/etc/pi-computer-use/production-config.json
npm start

One-off override without touching files:

PCU_MAX_CONCURRENCY=12 PCU_DISABLE_BRIDGE=true npm run start

Sample configuration for headless deployment:

{
  "serverUrl": "http://backend.internal:8080",
  "apiKey": "${API_KEY_SECRET}",
  "logLevel": "warn",
  "maxConcurrency": 16,
  "disableBridge": true
}

Summary

• pi-computer-use loads settings from PCU_* environment variables and a JSON file at ~/.config/pi-computer-use/config.json.
• Change the config file location by setting PCU_CONFIG_PATH.
• Environment variables always override JSON file values during the merge process in src/config.ts.
• Key settings include PCU_SERVER_URL, PCU_API_KEY, PCU_LOG_LEVEL, and PCU_DISABLE_BRIDGE.
• The src/runtime.ts file uses these settings to conditionally initialize native OS bridges.

Frequently Asked Questions

What is the default location for the configuration file?

The system looks for config.json at ~/.config/pi-computer-use/config.json unless you specify a different path via the PCU_CONFIG_PATH environment variable.

Can I run pi-computer-use without a configuration file?

Yes. The JSON configuration file is optional. If the file is missing or unreadable, the application falls back to environment variables and hardcoded defaults defined in src/config.ts.

How do I disable the native OS bridge for containerized deployments?

Set the PCU_DISABLE_BRIDGE environment variable to true or add "disableBridge": true to your JSON configuration file. This prevents src/runtime.ts from initializing the bridge module, allowing the agent to run in headless environments.

Why are my environment variable changes not reflecting in the application?

Ensure your variables use the PCU_ prefix and are exported in the shell session that launches the Node.js process. Remember that environment variables take precedence over the JSON file, so verify you are not accidentally overriding your intended value with an existing shell export.

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