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

> Master pi-computer-use configuration by learning to set environment variables and use config files. Discover how settings merge with environment variables taking priority.

- Repository: [injaneity/pi-computer-use](https://github.com/injaneity/pi-computer-use)
- Tags: how-to-guide
- Published: 2026-07-16

---

**pi-computer-use reads runtime settings from environment variables prefixed with `PCU_` and an optional JSON configuration file, merging them in [`src/config.ts`](https://github.com/injaneity/pi-computer-use/blob/main/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`](https://github.com/injaneity/pi-computer-use/blob/main/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`](https://github.com/injaneity/pi-computer-use/blob/main/src/runtime.ts) to initialize the native OS bridge and by [`src/state.ts`](https://github.com/injaneity/pi-computer-use/blob/main/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`](https://github.com/injaneity/pi-computer-use/blob/main/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:

```json
{
  "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`](https://github.com/injaneity/pi-computer-use/blob/main/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`](https://github.com/injaneity/pi-computer-use/blob/main/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`](https://github.com/injaneity/pi-computer-use/blob/main/src/config.ts)** – Central loader that orchestrates environment extraction, file parsing, and deep merging.
- **[`src/runtime.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/runtime.ts)** – Consumes the configuration to conditionally instantiate the `Bridge` class based on `config.disableBridge`.
- **[`src/state.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/state.ts)** – Maintains global state that references the configuration object for runtime decisions.

## Practical Configuration Examples

**Local development with a `.env` file:**

```text

# .env

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

```

**Using a custom configuration path:**

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

```

**One-off override without touching files:**

```bash
PCU_MAX_CONCURRENCY=12 PCU_DISABLE_BRIDGE=true npm run start

```

**Sample configuration for headless deployment:**

```json
{
  "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`](https://github.com/injaneity/pi-computer-use/blob/main/src/config.ts).
- Key settings include `PCU_SERVER_URL`, `PCU_API_KEY`, `PCU_LOG_LEVEL`, and `PCU_DISABLE_BRIDGE`.
- The [`src/runtime.ts`](https://github.com/injaneity/pi-computer-use/blob/main/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`](https://github.com/injaneity/pi-computer-use/blob/main/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`](https://github.com/injaneity/pi-computer-use/blob/main/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`](https://github.com/injaneity/pi-computer-use/blob/main/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.