# 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 [Services overview](/docs/services-overview.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 it 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. - `devii_browser_control` - allow the mutating browser-control tools (click, fill, set, submit, press_key, run_sequence); the read-only browser tools stay available when off. **Limits** - `devii_user_daily_usd` / `devii_guest_daily_usd` - rolling 24h spend caps for members and guests. - `devii_admin_daily_usd` - the administrator cap (default `0` = unlimited, so admins are exempt by default). - `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, they 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 it is separate from the fetch timeout. **Email** - `devii_email_enabled` - enable the `email_*` tools (configure accounts, list/read/search/flag/move/delete messages, send mail) for signed-in users; when off, they are refused. They connect to the user's own external mailbox over IMAP/SMTP, not this platform. - `devii_email_timeout` - connection/read timeout in seconds for IMAP and SMTP calls (default 30). Each field falls back to its `DEVII_*` environment variable where applicable (`DEVII_RSEARCH_ENABLED`, `DEVII_RSEARCH_URL`, `DEVII_RSEARCH_TIMEOUT`, `DEVII_EMAIL_ENABLED`, `DEVII_EMAIL_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, baseUrl}`; sets the guest cookie. | | `GET /devii/usage` | `{used_pct, turns_today, owner_kind}` for the widget, plus `spent_24h` and `limit` for administrators only (money is admin-only). | | `GET /devii/adopt` | Single-use redirect that sets the browser `session` cookie after the terminal agent logs in. | | `WS /devii/ws?channel=docs` | The docs-only Docii conversation thread (allowlisted channel). | | `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 --base-url https://your-host devii -p "List my unread notifications as a bullet list." ``` Against the same database, the CLI resolves the account behind the supplied API key and uses that owner, sharing the same per-account lesson memory and tasks as the web session. It logs at `WARNING` by default (set `DEVII_LOG_LEVEL=DEBUG` for detail); noisy HTTP libraries are always quieted.