Configuration

All configuration lives in ~/.picobot/config.json. Created by picobot init, editable at any time. Changes take effect on the next agent invocation.

Full Schema¶

{
  "providers": {
    "openai": {
      "apiKey": "",
      "apiBase": null
    },
    "local": {
      "apiKey": "",
      "apiBase": null
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/.picobot/workspace",
      "model": "openai/gpt-5.2-mini",
      "maxTokens": 8192,
      "temperature": 0.7,
      "maxToolIterations": 20,
      "maxSubagentDepth": 2,
      "tokenBudget": 128000,
      "maxHistoryMessages": 50
    }
  },
  "tools": {
    "exec": {
      "timeout": 60
    },
    "web": {
      "search": {
        "apiKey": "",
        "maxResults": 5
      },
      "firecrawl": {
        "apiKey": ""
      }
    },
    "browser": {
      "headless": true,
      "timeout": 30000,
      "viewportWidth": 1280,
      "viewportHeight": 720
    },
    "restrictToWorkspace": false,
    "allowPaths": [],
    "blockPaths": []
  },
  "knowledge": {
    "remote": null
  }
}

Providers¶

openai¶

The primary LLM provider. Works with any OpenAI-compatible API.

Field	Type	Default	Description
`apiKey`	string	`""`	API key (or set `OPENAI_API_KEY` env var)
`apiBase`	string	`null`	Custom API base URL

local¶

For local/self-hosted models (vLLM, ollama, lmstudio, etc.).

Field	Type	Default	Description
`apiKey`	string	`""`	API key (often not needed for local models)
`apiBase`	string	`null`	Local server URL (e.g., `http://localhost:11434/v1`)

Model IDs use LiteLLM's provider/model format:

"model": "openai/gpt-4o"
"model": "local/llama3"
"model": "anthropic/claude-sonnet-4-20250514"

Agent Defaults¶

Field	Type	Default	Description
`workspace`	string	`~/.picobot/workspace`	Workspace directory path
`model`	string	`openai/gpt-5.2-mini`	LLM model ID
`maxTokens`	int	8192	Max tokens per LLM response
`temperature`	float	0.7	Sampling temperature
`maxToolIterations`	int	20	Max tool calls per agent turn
`maxSubagentDepth`	int	2	Max sub-agent nesting depth
`tokenBudget`	int	128000	Token budget before history compression
`maxHistoryMessages`	int	50	Max messages retained on session save

Tuning Tips¶

Lower tokenBudget (e.g., 32000) for cheaper sessions with faster responses
Higher tokenBudget (e.g., 200000) for complex multi-step work requiring more context
Lower maxToolIterations to prevent runaway tool loops
Higher maxSubagentDepth only if you need deeply nested delegation (usually 2 is enough)
Lower temperature (e.g., 0.3) for more deterministic, focused responses
Higher temperature (e.g., 0.9) for more creative, varied output

Tools¶

exec¶

Field	Type	Default	Description
`timeout`	int	60	Shell command timeout in seconds

web.search¶

Field	Type	Default	Description
`apiKey`	string	`""`	Brave Search API key
`maxResults`	int	5	Max search results (1-10)

web.firecrawl¶

Field	Type	Default	Description
`apiKey`	string	`""`	Firecrawl API key for web scraping

browser¶

Field	Type	Default	Description
`headless`	bool	`true`	Run browser without visible window
`timeout`	int	30000	Page timeout in milliseconds
`viewportWidth`	int	1280	Browser viewport width in pixels
`viewportHeight`	int	720	Browser viewport height in pixels

Set headless: false to watch the browser work — useful for debugging browser tool actions, accessibility audits, and test automation.

Path Access Control¶

Field	Type	Default	Description
`restrictToWorkspace`	bool	`false`	Only allow access within workspace
`allowPaths`	string[]	`[]`	Additional allowed paths (when restricted)
`blockPaths`	string[]	`[]`	Always-denied paths (overrides allow)

Unrestricted mode (default): All paths accessible except those in blockPaths.

Restricted mode: Only workspace paths + allowPaths are accessible. blockPaths always wins.

Example for a sandboxed setup:

{
  "tools": {
    "restrictToWorkspace": true,
    "allowPaths": [
      "/Users/me/projects/current-project",
      "/tmp"
    ],
    "blockPaths": [
      "/Users/me/.ssh",
      "/Users/me/.aws",
      "/etc"
    ]
  }
}

Knowledge¶

Field	Type	Default	Description
`remote`	string	`null`	Git remote URL for KB sync

Example:

{
  "knowledge": {
    "remote": "git@github.com:you/picobot-kb.git"
  }
}

Environment Variables¶

Config values can be overridden with environment variables:

export OPENAI_API_KEY="sk-..."
export BRAVE_API_KEY="BSA..."
export FIRECRAWL_API_KEY="fc-..."

The API key lookup order: config file → environment variable.

Reset¶

picobot wipe          # Reset workspace, keep config
picobot clean --full  # Remove everything (~/.picobot/)
picobot init          # Re-initialize from scratch