# DeviiService `name` `devii` - disabled by default - 60s interval (minimum 10s). Devii is the in-platform agentic assistant, exposed as a WebSocket terminal at `/devii/ws`. Source: `services/devii/`. The agent internals (tools, sessions, lessons) have their own [Devii internals](/docs/devii-internals.html) section; this page covers Devii as a background service. See also [Reading service data](/docs/services-data.html). > Audience: administrators and maintainers. This page describes limits, spend, and persistence. ## The service loop versus the real work Devii is event-driven: the work happens per WebSocket message, not in `run_once()`. The 60s service loop does housekeeping only: it prunes usage-ledger rows older than 48 hours and garbage-collects idle sessions (zero open connections), logging the counts. The terminal at `/devii/ws` drives the agent turns. ## Sessions, owners, and the worker lock `DeviiHub` keeps one `DeviiSession` per owner, keyed by `(owner_kind, owner_id)`: `user`/uid for a signed-in user, `guest`/cookie for an anonymous visitor. All of an owner's open tabs share that one session, and a per-session `asyncio.Lock` serializes turns so an owner never runs two turns at once. A signed-in user's Devii operates their own DevPlace account using their own API key; guests get a sandbox. Because the hub is in-memory, `/devii/ws` is served only by the worker that owns the services lock. Non-owner workers close new Devii sockets with code 1013, so the client reconnects until it reaches the owner, keeping every session and every cost and quota check in one place. The database (conversations, ledger, tasks, lessons) is the durable source of truth, so a new lock owner rebuilds sessions on demand after a restart. ## Spend caps The 24h rolling spend cap is checked before every turn. `effective_daily_limit(config, owner_kind, is_admin)` is the single source of truth: guests use `devii_guest_daily_usd` (default $0.05), users use `devii_user_daily_usd` (default $1.00), and administrators use `devii_admin_daily_usd` (default 0.0, where **0 means unlimited**). The gate is `if limit > 0 and spent >= limit`, so a 0 cap never blocks. Quotas are resettable per user, per guest cohort, or globally, from `/admin/users`, `/admin/ai-usage`, and the `devplace devii reset-quota` CLI. Financial figures are admin-only everywhere: members and guests see only the percentage of their 24h quota used, never dollars. ## Configuration fields **AI:** `devii_ai_url` (the chat-completions endpoint Devii reasons with, the internal gateway by default), `devii_ai_model` (the internal model), `devii_ai_key` (secret; defaults to the `DEVII_AI_KEY` env var then the gateway internal key), `devii_base_url` (the origin Devii drives via each user's key; blank uses this instance). **Reliability:** `devii_timeout` (AI read timeout, default and minimum 300s; must be at least the gateway upstream timeout), `devii_fetch_timeout` (web fetch read timeout, default and minimum 300s). **Agent:** `devii_plan_required` (force a plan step before tools, default on), `devii_verify_required` (force a verify step after mutating actions, default on), `devii_max_iterations` (tool-loop bound per turn, default 40, 1 to 200), `devii_allow_eval` (allow the `run_js` browser tool, default on; other client tools are unaffected). **Limits:** `devii_user_daily_usd` (1.0), `devii_guest_daily_usd` (0.05), `devii_admin_daily_usd` (0.0 = unlimited), `devii_guests_enabled` (default on). **Pricing (USD per 1M tokens):** `devii_price_cache_hit` (0.0028), `devii_price_cache_miss` (0.14), `devii_price_output` (0.28). **Web search:** `devii_rsearch_enabled` (the external `rsearch_*` web tools, default on), `devii_rsearch_url` (`https://rsearch.app.molodetz.nl`), `devii_rsearch_timeout` (default and minimum 300s). ## Persistence | Table | Purpose | |-------|---------| | `devii_conversations` | Message history per signed-in owner, rehydrated on reconnect and across restarts. Guests are in-memory only. | | `devii_usage_ledger` | One row per turn: owner, turn id, token counts (prompt, completion, cache hit and miss), `cost_usd`, model. The authoritative 24h-spend source. | | `devii_turns` | Audit log per turn: prompt and reply (truncated), iterations, tool calls, cost, error, start and end timestamps. | | `devii_tasks` | Scheduled and background tasks (per-user persistent; guests in-memory). | | `devii_lessons` | The self-learning lessons store, strictly owner-scoped (per-user persistent; guests ephemeral). | The in-memory `CostTracker` is display-only; the ledger is authoritative for spend. ## Data it offers Live metrics (in `describe()`, at `GET /admin/services/data`) are a labelled stats list: active sessions, open connections, 24h spend across all owners, the user/guest/admin caps, whether guests are allowed, and the model name. Per-turn token and cost detail lives in `devii_usage_ledger`; the per-turn audit trail in `devii_turns`.