Configure PI WEB where your agents work.

Config files

PI WEB uses a global config file for machine-local settings and a project-local file for repository settings.

• Global config: $PI_WEB_CONFIG, or $XDG_CONFIG_HOME/pi-web/config.json, or ~/.config/pi-web/config.json.
• Project config: <project>/.pi-web/config.json for commit-able project settings.

Each PI WEB machine has its own config. When using Fleet/machine federation, edit a remote machine's config by opening that machine directly or changing files on that machine.

If you installed services with a custom config path, rerun pi-web install --config /path/to/config.json after changing that path or after upgrading from a version that only applied the custom path to the web service. This regenerates service files so the web/API and session daemon use the same PI_WEB_CONFIG.

Precedence and reloads

Runtime values are resolved in this order:

defaults → config file → environment overrides

Environment overrides include PI_WEB_HOST, PI_WEB_PORT / PORT, PI_WEB_ALLOWED_HOSTS, PI_WEB_MAX_UPLOAD_BYTES, PI_WEB_AGENT_COMMAND, PI_WEB_AGENT_DIR, PI_WEB_AGENT_SESSION_DIR, PI_CODING_AGENT_DIR / PI_CODING_AGENT_SESSION_DIR for Pi compatibility, PI_WEB_SPAWN_SESSIONS, and PI_WEB_SUBSESSIONS.

• host / port: restart the web/API service or process.
• maxUploadBytes: restart both the web/API process and the session daemon.
• agent.command / agent.dir / spawnSessions / subsessions: restart the session daemon.
• pathAccess: applies on the next request; existing file views may need a browser refresh.
• plugins: reload the browser tab after changing plugin enablement.
• shortcuts: saved settings apply in the browser after config refresh/save.

Global config example

pi-web install creates the initial file. You can also save settings from Settings → General, Settings → Plugins, Settings → Keyboard, and Settings → Session daemon.

{
  "host": "127.0.0.1",
  "port": 8504,
  "pathAccess": {
    "allowedPaths": ["~/SDKs", "/opt/reference"]
  },
  "maxUploadBytes": 67108864,
  "agent": {
    "command": "pi",
    "dir": "~/agent-profiles/research"
  },
  "spawnSessions": true,
  "subsessions": false,
  "plugins": {
    "workspace-tasks": { "enabled": true },
    "updates": { "enabled": true },
    "info": { "enabled": false }
  },
  "shortcuts": {
    "core:view.chat": "mod+1",
    "core:session.stop": null
  }
}

Project-local config

Project-local config lives at <project>/.pi-web/config.json. Use it for settings that should follow a repository. When a project config defines pathAccess, PI WEB merges it after the global path list.

{
  "version": 1,
  "pathAccess": {
    "allowedPaths": ["~/SDKs", "/opt/reference"]
  }
}

Project-local pathAccess.allowedPaths entries must still be host-absolute or ~-prefixed; relative roots are not supported. Plugins may own separate project files, such as .pi-web/tasks.json for the built-in Workspace Tasks plugin.

Config matrix

Use this table as the quick reference for where a setting can live, which environment variable overrides it, and whether project-local config overrides or merges with global config. Rows with JSON key — are runtime-only environment variables, not config-file keys.

External path access

pathAccess.allowedPaths grants PI WEB's file explorer and absolute @ path completions access to specific filesystem roots outside the current workspace. By default, workspace-relative file reads stay inside the workspace and absolute paths are denied.

Accepted root forms:

• Unix absolute paths, for example /opt/reference.
• Home-relative paths, for example ~/SDKs.
• Windows absolute paths on Windows hosts, for example C:\Users\dev\SDKs.

When an absolute request is served, PI WEB expands ~, canonicalizes configured roots with realpath, requires roots to be existing directories, and rejects symlink escapes outside the allowed roots.

Agent runtime

agent.command controls which Pi-compatible CLI PI WEB checks in doctor/status/update flows. It defaults to pi. Set it only when diagnostics and package-managed update checks should target another compatible command; the embedded session runtime still uses PI WEB's SDK integration.

agent.dir controls which compatible agent state directory PI WEB reads for auth providers, model settings, settings, and session metadata. It defaults to ~/.pi/agent only for the default pi command. Set it explicitly when you want an isolated Pi profile or when agent.command points at another compatible CLI.

{
  "agent": {
    "command": "my-pi-fork",
    "dir": "/opt/my-pi-fork/agent"
  }
}

For example, a fork profile can set agent.command to my-pi-fork and agent.dir to /opt/my-pi-fork/agent.

Environment variables take precedence over the config file. PI_WEB_AGENT_COMMAND selects the command, PI_WEB_AGENT_DIR sets the state directory, and PI_WEB_AGENT_SESSION_DIR overrides session storage separately from agent.dir. Existing Pi Coding Agent env names (PI_CODING_AGENT_DIR and PI_CODING_AGENT_SESSION_DIR) remain supported only for Pi compatibility; alternate commands should use the explicit PI WEB variables or config keys.

Session directory overrides are environment-only; use PI_WEB_AGENT_SESSION_DIR unless you are intentionally using the legacy Pi-compatible PI_CODING_AGENT_SESSION_DIR name.

Session daemon tools

spawnSessions

Boolean. Controls whether agents receive the spawn_session tool. Defaults to true. Set it to false if you do not want an agent to start independent PI WEB sessions.

Environment override: PI_WEB_SPAWN_SESSIONS=0|1|true|false.

subsessions

Boolean. Beta. Controls whether agents receive the tracked-subsession tools: spawn_subsession, list_subsessions, check_subsession, and read_subsession. Defaults to false and also requires spawnSessions to be enabled.

Tracked subsessions let an agent delegate work to child sessions, get notified when children stop working, and inspect their transcripts. Restart the session daemon after changing this setting.

Environment override: PI_WEB_SUBSESSIONS=0|1|true|false.

Optional completion tools

File and path @ completions work without extra tools. If fzf is available on the PI WEB server's PATH, PI WEB uses it to improve completion filtering and ranking; otherwise it falls back to built-in ranking.