devplacepy/devplacepy/templates/docs/devii-config.html

<div class="docs-content" data-render>
# Configuration and CLI

How to configure and operate Devii. See also [Devii internals](/docs/devii-internals.html) and [Security and limits](/docs/devii-security.html).

## Service configuration

Devii runs as `DeviiService` (a background service) and is configured on
[Background Services](/docs/services.html) at `/admin/services`. The fields, grouped:

**AI**
- `devii_ai_url` - the OpenAI-compatible chat endpoint Devii reasons with.
- `devii_ai_model` - the model name.
- `devii_ai_key` - the AI key (falls back to the `DEVII_AI_KEY` environment variable).
- `devii_base_url` - the platform origin Devii drives via each user's API key (blank uses this instance).

**Reliability**
- `devii_timeout` - read timeout in seconds for each AI chat-completions call (and the platform API client). Default 300, minimum five minutes. Set this at least as high as the gateway's upstream timeout, or large prompts abort early with a model error.
- `devii_fetch_timeout` - read timeout in seconds for the fetch tool when Devii retrieves a URL. Default 300, minimum five minutes.

**Agent**
- `devii_plan_required` / `devii_verify_required` - enforce the plan-first and verify-after-mutation gates.
- `devii_max_iterations` - upper bound on tool-loop iterations per turn.
- `devii_allow_eval` - allow `run_js` in the user's browser.

**Limits**
- `devii_user_daily_usd` / `devii_guest_daily_usd` - rolling 24h spend caps.
- `devii_guests_enabled` - allow anonymous guests.

**Pricing**
- `devii_price_cache_hit` / `devii_price_cache_miss` / `devii_price_output` - USD per 1M tokens; these drive the spend cap.

**Web search**
- `devii_rsearch_enabled` - enable the external `rsearch_*` web tools (web/image search, web-grounded AI answer, chat, image description). When off, those tools are refused. They reach an external public service, not this platform, and Devii uses them only when the user explicitly asks to search the web.
- `devii_rsearch_url` - base URL of the rsearch-compatible service those tools call.
- `devii_rsearch_timeout` - read timeout in seconds for the `rsearch_*` tools (default 300, minimum five minutes). Web-grounded answers can take several minutes, so this is deliberately generous and separate from the fetch timeout.

Each field falls back to its `DEVII_*` environment variable where applicable
(`DEVII_RSEARCH_ENABLED`, `DEVII_RSEARCH_URL`, `DEVII_RSEARCH_TIMEOUT`). The service exposes
live metrics (active sessions, connections, 24h spend, caps, model) via `collect_metrics`, shown on
its services card.

## Routes

| Route | Purpose |
|---|---|
| `WS /devii/ws` | The terminal session (served only by the service-lock-owning worker). |
| `GET /devii/` | The standalone Devii page. |
| `GET /devii/session` | Bootstrap: `{loggedIn, username, enabled, guestsEnabled}`; sets the guest cookie. |
| `GET /devii/usage` | `{spent_24h, limit, turns_today, owner_kind}` for the widget. |
| `POST /devii/clippy/ai/chat` | Same-origin AI proxy for the avatar. |
| `GET /admin/analytics` | Admin-only aggregate analytics (JSON) that `site_analytics` calls; see the [Admin API](/docs/admin.html). |

## The `devii` console script

`pyproject.toml` publishes a `devii` command (`devplacepy.services.devii.cli:main`). Install with
`pip install -e .` and run `devii` for an interactive terminal, or `devii -p "..."` for a one-shot.

```bash
devii --api-key <your DevPlace api_key> --base-url https://your-host
devii -p "List my unread notifications as a bullet list."
```

When the CLI runs against the same database, it resolves the account behind the supplied API key and
uses that owner, so it shares the same per-account lesson memory and tasks as the web session. The
CLI logs at `WARNING` by default (set `DEVII_LOG_LEVEL=DEBUG` for detail); noisy HTTP libraries are
always quieted.
</div>