# Agent: Config

**Page:** api/agent/config

[Download Raw Markdown](./api/agent/config.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Agent: Config

Manage the Hoody Agent configuration for a workspace. These endpoints let you read and update the full config object, list configured providers, reviewers, verifiers, and CLI sub-agents, and inspect workspace-level tool overrides.

## Get configuration

### `GET /api/v1/workspaces/{workspaceID}/config`

Retrieve the current Hoody Agent configuration settings and preferences.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

### Response



```json
{
  "$schema": "https://hoody.com/config.json",
  "theme": "dark",
  "logLevel": "INFO",
  "model": "anthropic/claude-sonnet-4.5",
  "small_model": "anthropic/claude-haiku-4.5",
  "default_agent": "build",
  "username": "alex",
  "snapshot": false,
  "yolo": false,
  "disabled_providers": [],
  "disabled_tools": [],
  "enabled_providers": ["anthropic", "openai"],
  "instructions": [],
  "plugin": [],
  "agent": {
    "build": { "model": "anthropic/claude-sonnet-4.5", "temperature": 0.2 },
    "plan": { "model": "anthropic/claude-sonnet-4.5", "temperature": 0.1 },
    "explore": { "model": "anthropic/claude-haiku-4.5" }
  },
  "provider": {},
  "mcp": {},
  "tool_overrides": {},
  "command": {},
  "skills": { "paths": [], "urls": [] },
  "watcher": { "ignore": [] },
  "permission": "ask",
  "formatter": false,
  "lsp": false,
  "layout": "stretch",
  "enterprise": { "url": "" },
  "compaction": { "auto": true, "prune": true, "reserved": 10000 },
  "tool_wake_policy": {},
  "limits": {
    "max_read_file_size_mb": 10,
    "bash_timeout_ms": 120000,
    "webfetch_max_size_mb": 5,
    "sdk_data_timeout_ms": 300000,
    "prune_protect_tokens": 40000
  },
  "experimental": {
    "disable_paste_summary": false,
    "batch_tool": false,
    "openTelemetry": false,
    "primary_tools": [],
    "continue_loop_on_deny": false,
    "mcp_timeout": 15000
  },
  "memory": {
    "enabled": true,
    "journal": {
      "enabled": true,
      "tags": [
        { "name": "preference", "description": "User preferences and style" }
      ]
    }
  },
  "mitm": { "tags": [], "rules": [] },
  "web_search": {
    "enabled": true,
    "model": "hoody/x-ai/grok-4.1-fast",
    "fallbacks": [],
    "deep_enabled": true,
    "deep_model": "hoody/alibaba/tongyi-deepresearch-30b-a3b",
    "deep_fallbacks": [],
    "timeout": 60000,
    "deep_timeout": 600000
  },
  "image_generation": {
    "enabled": true,
    "model": "hoody/google/gemini-3.1-flash-image-preview",
    "fallbacks": [],
    "output_path": "/hoody/storage/hoody-workspaces/generated-images",
    "default_aspect_ratio": "1:1",
    "default_image_size": "1K",
    "default_count": 1,
    "timeout": 120000,
    "max_per_session": 20
  },
  "rsi": {
    "enabled": true,
    "reviewers": [
      {
        "name": "gpt-reviewer",
        "model": "openai/gpt-5.3-codex-spark",
        "fallbacks": [],
        "prompt": "Review for correctness and security."
      }
    ],
    "timeout": 600000,
    "max_reviewers": 5,
    "max_reviews_per_session": 0
  },
  "self_tuning": {
    "enabled": true,
    "max_invocations_per_session": 0,
    "verifier_entrypoint_allowlist": [],
    "verifiers": {}
  },
  "cli_agents": {
    "enabled": true,
    "timeout": 300000,
    "agents": [
      {
        "name": "Gemini Flash",
        "cli": "gemini",
        "model": "gemini-3-flash-preview",
        "readonly": true,
        "allow_git": false,
        "tools": [],
        "max_budget_usd": 1.5,
        "timeout": 300000
      }
    ]
  }
}
```



### SDK

```ts
const config = await client.agent.config.get({ workspaceID: "ws_abc123" });
```

## Update configuration

### `PATCH /api/v1/workspaces/{workspaceID}/config`

Update Hoody Agent configuration settings and preferences. Authorisation is the verified container claim — the caller owns this container.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

### Request Body

All fields are optional. Pass only the keys you want to change; omitted keys are left unchanged. To clear a key, send `null`.

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `permission` | object \| null | No | Permission rules keyed by tool name |
| `tool_overrides` | object \| null | No | Map of tool name to boolean override (true = force on, false = force off) |
| `tool_wake_policy` | object \| null | No | Per-tool wake policy. Map of tool name to `auto`, `next_turn`, `manual`, or `sync` |
| `yolo` | boolean \| null | No | When true, skip all permission prompts |
| `provider` | object \| null | No | Custom provider configurations and model overrides |
| `disabled_providers` | array \| null | No | Provider IDs to disable |
| `enabled_providers` | array \| null | No | When set, only these provider IDs remain enabled |
| `model` | string \| null | No | Default model in `provider/model` format |
| `small_model` | string \| null | No | Small model for lightweight tasks (e.g. title generation) |
| `default_agent` | string \| null | No | Name of the default primary agent (falls back to `build`) |
| `instructions` | array \| null | No | Additional instruction files or glob patterns |

```json
{
  "model": "anthropic/claude-sonnet-4.5",
  "small_model": "anthropic/claude-haiku-4.5",
  "default_agent": "build",
  "yolo": false,
  "enabled_providers": ["anthropic", "openai"],
  "tool_overrides": {
    "bash": true,
    "webfetch": false
  },
  "tool_wake_policy": {
    "long_task": "manual"
  },
  "instructions": ["**/AGENTS.md", "docs/style.md"]
}
```

### Response



```json
{
  "model": "anthropic/claude-sonnet-4.5",
  "small_model": "anthropic/claude-haiku-4.5",
  "default_agent": "build",
  "yolo": false,
  "enabled_providers": ["anthropic", "openai"],
  "tool_overrides": { "bash": true, "webfetch": false },
  "tool_wake_policy": { "long_task": "manual" },
  "instructions": ["**/AGENTS.md", "docs/style.md"]
}
```


```json
{
  "data": null,
  "errors": [
    { "field": "model", "message": "must be in provider/model format" }
  ],
  "success": false
}
```



### SDK

```ts
await client.agent.config.update({
  workspaceID: "ws_abc123",
  data: {
    model: "anthropic/claude-sonnet-4.5",
    yolo: false,
    tool_overrides: { bash: true, webfetch: false }
  }
});
```

## List config providers

### `GET /api/v1/workspaces/{workspaceID}/config/providers`

Get a list of all configured AI providers and their default models.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

### Response



```json
{
  "providers": [
    {
      "id": "anthropic",
      "name": "Anthropic",
      "source": "env",
      "env": ["ANTHROPIC_API_KEY"],
      "options": {},
      "models": {}
    },
    {
      "id": "openai",
      "name": "OpenAI",
      "source": "env",
      "env": ["OPENAI_API_KEY"],
      "options": {},
      "models": {}
    }
  ],
  "default": {
    "model": "anthropic/claude-sonnet-4.5",
    "small_model": "anthropic/claude-haiku-4.5"
  }
}
```



### SDK

```ts
const result = await client.agent.providers.listConfigs({ workspaceID: "ws_abc123" });
```

## Get workspace tool overrides

### `GET /api/v1/workspaces/{workspaceID}/config/tool-overrides`

Get `tool_overrides` from the workspace config only (not merged with global).

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

### Response



```json
{
  "tool_overrides": {
    "bash": true,
    "webfetch": false,
    "todowrite": true
  }
}
```



### SDK

```ts
const result = await client.agent.config.getToolOverrides({ workspaceID: "ws_abc123" });
```

## List configured RSI reviewers

### `GET /api/v1/workspaces/{workspaceID}/config/reviewers`

Return the configured RSI reviewer set. The `enabled` flag mirrors `config.rsi.enabled` (defaults to `true` if absent). An empty `reviewers` array with `enabled: true` means no reviewers are pre-configured, but callers can still invoke RSI ad-hoc by passing an inline `reviewers` list on `POST /rsi/review`. An empty `reviewers` array with `enabled: false` means RSI is administratively disabled and inline overrides will also be rejected.

### Parameters



| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | workspaceID path parameter |


### Response



```json
{
  "enabled": true,
  "reviewers": [
    {
      "name": "gpt-reviewer",
      "model": "openai/gpt-5.3-codex-spark",
      "fallbacks": ["openai/gpt-5.1-mini"],
      "prompt": "Review the diff for correctness and security."
    },
    {
      "name": "deepseek-reviewer",
      "model": "deepseek/deepseek-chat",
      "fallbacks": [],
      "prompt": "Look for logic bugs and unsafe inputs."
    }
  ]
}
```



### SDK

```ts
const result = await client.agent.reviewers.configListReviewers({ workspaceID: "ws_abc123" });
```

## List configured self-tuning verifiers

### `GET /api/v1/workspaces/{workspaceID}/config/verifiers`

Return the configured verifier set as an array. The source config keys verifiers by name; this endpoint projects them to an array for SDK ergonomics. The `enabled` flag mirrors `config.self_tuning.enabled` (defaults to `true` if absent).

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

### Response



```json
{
  "enabled": true,
  "verifiers": [
    {
      "name": "unit-tests",
      "cmd": "npm test --silent",
      "timeout_ms": 120000,
      "parallel_safe": false
    },
    {
      "name": "typecheck",
      "cmd": "tsc --noEmit",
      "timeout_ms": 60000,
      "parallel_safe": true
    }
  ]
}
```



### SDK

```ts
const result = await client.agent.verifiers.configListVerifiers({ workspaceID: "ws_abc123" });
```

## List configured CLI agents

### `GET /api/v1/workspaces/{workspaceID}/config/cli-agents`

Return the configured `cli_agents` set. When `is_default: true`, `config.cli_agents.agents` is undefined and the response lists the built-in `DEFAULT_CLI_AGENTS`. When `is_default: false` with an empty `agents` array, the user has explicitly cleared the list (configured `agents: []`) — distinct from the defaults case.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

### Response



```json
{
  "enabled": true,
  "is_default": false,
  "agents": [
    {
      "name": "Gemini Flash",
      "cli": "gemini",
      "model": "gemini-3-flash-preview",
      "readonly": true,
      "allow_git": false,
      "tools": [],
      "max_budget_usd": 1.5,
      "timeout": 300000
    },
    {
      "name": "Claude Reviewer",
      "cli": "claude",
      "model": "claude-sonnet-4.5",
      "readonly": true,
      "allow_git": false,
      "tools": ["Read", "Grep", "Glob"],
      "max_budget_usd": 2.0,
      "timeout": 600000
    }
  ]
}
```



### SDK

```ts
const result = await client.agent.cliAgents.configListCliAgents({ workspaceID: "ws_abc123" });
```