Akvan Agent

Akvan Agent is a small Python agent harness with a CLI chat loop and a provider abstraction. Supported providers are OpenRouter, OpenAI Codex, DeepSeek, and Akvan (OTP sign-in with plan credits).

See ARCHITECTURE.md for the package boundaries and extension points.

Install

Akvan is not published on PyPI. Install via the website script or from source.

From our website (recommended):

curl -fsSL https://agent.akvan.app/install.sh | sh

From source:

git clone https://github.com/akvanai/akvan-agent.git
cd akvan-agent
./install.sh

The installer checks for uv, installs it when needed, provides Python 3.12 when no compatible Python is available, installs Akvan into ~/.akvan, creates the akvan launcher in /usr/local/bin for root installs or ~/.local/bin otherwise, and opens the provider and model setup on the first install when run from an interactive terminal. If setup is skipped because the installer is piped through sh, run akvan model afterward. Run the same command again to update an existing installation.

After it finishes, start Akvan with akvan.

See INSTALL.md for uninstall, purge, bundled skills, and the ~/.akvan/ data layout.

Logs

Akvan writes rotated log files under ~/.akvan/logs/:

File	Purpose
agent.log	CLI activity (memory, skills, sessions, tools, errors)
errors.log	Warnings and errors only
gateway-{id}.log	Per-gateway process (e.g. gateway-telegram.log)

View logs from the terminal:

akvan logs                  # last 50 lines of agent.log
akvan logs -f               # follow agent.log
akvan logs errors           # warnings and errors
akvan logs gateway telegram -f
akvan logs list             # show log files and sizes
akvan logs --since 1h --component memory

Tune logging in ~/.akvan/config.yaml (logging.level, logging.max_size_mb, logging.backup_count) or set AKVAN_LOG_LEVEL=DEBUG for troubleshooting. Rotated backups keep disk use bounded (default: 5 MB × 3 per main log).

Providers

Configure the active provider with akvan model or in ~/.akvan/.env (AKVAN_PROVIDER, AKVAN_MODEL). Supported providers:

• openrouter — uses OPENROUTER_API_KEY, loads the live OpenRouter model catalog, and uses the Chat Completions endpoint (/chat/completions).
• openai-codex — defaults to Codex CLI session discovery and can alternatively use OPENAI_API_KEY.
• deepseek — uses DEEPSEEK_API_KEY against the native DeepSeek API (https://api.deepseek.com/v1), with V4 thinking-mode support and reasoning_content replay for tool calls.
• akvan — sign in with OTP via akvan model, uses AKVAN_API_KEY and AKVAN_BACKEND_URL (default https://agent.akvan.app) against the Akvan backend proxy; billing uses Akvan plan credits instead of a direct provider key.

Akvan provider setup:

akvan model   # choose Akvan → enter email/phone → OTP → pick model

Or set manually in ~/.akvan/.env:

AKVAN_PROVIDER=akvan
AKVAN_API_KEY=your_akvan_api_key
AKVAN_BACKEND_URL=https://agent.akvan.app
AKVAN_MODEL=openai/gpt-4o-mini

Web tools

When a search or extract backend is configured, Akvan exposes web_search and web_extract to the agent. Configure backends with:

akvan tools

Tool	Purpose
web_search	Search the web (up to 5 results with titles, URLs, descriptions)
web_extract	Fetch page content as markdown (PDF URLs supported; large pages summarized)

Search backends: searxng (requires SEARXNG_URL), ddgs (DuckDuckGo; the wizard can pip install ddgs into the Akvan venv), or firecrawl.

Extract backend: firecrawl (self-hosted FIRECRAWL_API_URL; FIRECRAWL_API_KEY optional for self-hosted instances).

The standard installer ships the [telegram] extra only. For Firecrawl extract, install firecrawl-py into the Akvan venv — from a source checkout: uv sync --extra web; for an installed copy: ~/.akvan/venv/bin/pip install firecrawl-py. DDGS can be installed via the akvan tools wizard.

Save settings in ~/.akvan/.env and/or ~/.akvan/config.yaml (web.search_backend, web.extract_backend). Optional AKVAN_WEB_EXTRACT_SUMMARY_MODEL selects the model used to summarize large extracted pages. See config.yaml.example and .env.example.

Chat, tools, and approvals

Type /exit or press Ctrl-D to quit. The prompt stays pinned at the bottom, Hermes-style. Enter sends; Esc then Enter adds a new line. When the active provider reports a dollar cost, the prompt status row shows the accumulated cost for the current Akvan session.

CLI sessions are persisted to ~/.akvan/state.db. Use /sessions to browse saved chats (15 per page) and /resume <number> to continue one from the list. The agent can also search past conversations with the session_search tool (FTS5 full-text search over stored messages). Type / for command suggestions.

Akvan includes direct read_file, write_file, and patch tools, plus local terminal execution and owned background-process management through process. The memory tool saves durable facts to MEMORY.md and USER.md; session_search recalls past chats from the session database. Ordinary project edits run without prompts. read_file can use absolute paths outside the project; it blocks known credential and secret paths (.env*, ~/.ssh/, ~/.akvan/.env, etc.). The terminal tool is not subject to the same read blocks and can bypass them — review approvals carefully. Dangerous commands, sensitive file writes, and writes outside the project require once, session, always, or deny approval. Approval times out closed after 60 seconds. Catastrophic host commands are always blocked, including in --yolo or /yolo mode.

In the interactive terminal, approval requests appear inside the active response. Press the displayed number (1–4) to choose, y to allow once, or n/d to deny. If no choice is made before the configured timeout, Akvan denies the operation and lets the model choose a safer next step.

Configure approvals with AKVAN_APPROVAL_MODE, AKVAN_APPROVAL_TIMEOUT, and AKVAN_TERMINAL_TIMEOUT:

Mode	Behavior
ask (default)	Prompt for sensitive operations
deny	Auto-reject sensitive operations (no prompt)
off	Skip ordinary approvals (env-wide default; same effect as --yolo)

Catastrophic host commands remain blocked in all modes, including --yolo and AKVAN_APPROVAL_MODE=off.

Persistent memory and session recall

Akvan remembers across sessions in two ways:

Mechanism	Location	Purpose
Curated memory	~/.akvan/memories/MEMORY.md, USER.md	Compact facts always in the system prompt
Session search	~/.akvan/state.db (FTS5)	Full-text search over past conversations

• MEMORY.md — agent notes (environment, conventions, lessons learned)
• USER.md — user profile (preferences, communication style, expectations)

Both are shared across CLI and gateway sessions. At session start, their contents are injected into the system prompt as a frozen snapshot. The agent updates them with the memory tool (add, replace, remove, or batched operations). Mid-session writes land on disk immediately but appear in the system prompt only after the next session or /reload.

To find older discussions, the agent uses session_search: pass a query for keyword discovery, session_id + around_message_id to scroll a transcript, or no args to browse recent sessions.

Every N user turns (default 10), a background review runs automatically and may save preferences or facts to memory without you asking. Every N tool iterations (default 10), it may also update or create procedural skills via skill_manage. These writes land on disk directly (no staging queue). Saved memory and loaded skills are treated as trusted instructions in later sessions. Background review cannot modify bundled skills. Set nudge_interval: 0 or creation_nudge_interval: 0 to disable either dimension. Configure limits and notifications in ~/.akvan/config.yaml:

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375
  nudge_interval: 10          # background memory review; 0 = off

skills:
  creation_nudge_interval: 10 # background skill review; 0 = off

display:
  review_notifications: on    # off | on | verbose

Learning skills

Akvan can grow its procedural memory over time:

Mechanism	How	Saves to
skill_manage tool	Agent creates/patches skills during tasks	~/.akvan/skills/
/learn …	Distill a workflow, URL, or directory into a skill	~/.akvan/skills/
Background review	Post-turn fork updates memory and skills	memory files + skills

User-directed creates (including /learn) belong to you. Only skills created by the background review fork are marked agent-created and eligible for curator archival.

/learn the deploy workflow we just ran
akvan skills curator status
akvan skills reset plan --restore   # restore a bundled skill from source

See config.yaml.example for a fuller sample including web tools.

Telegram gateway

Chat with Akvan from Telegram DMs. The standard installer includes the optional Telegram integration. Package users can install it with akvan-agent[telegram].

Open the gateway manager:

akvan gateway

From there you can configure Telegram, activate or deactivate the gateway, and run it in the background without keeping a terminal open.

Or add to ~/.akvan/.env manually:

TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
TELEGRAM_ALLOWED_USERS=your_telegram_user_id

Create the bot via @BotFather. Find your user id with @userinfobot.

The gateway streams replies with Telegram drafts when available and falls back to editing a single message. Its native menu provides /new, /status, /settings, /stop, and /help; /start shows the welcome message. Authorized gateway users have the same tool access as the local CLI (files, terminal, memory, skills). Sensitive tool approvals use inline Allow once, Allow for session, optional Always allow, and Deny buttons. --yolo and manual approval settings apply when configured. Typing stays active while Akvan thinks, runs tools, or streams, and pauses while an approval is waiting. Chat-scoped model, approval, and streaming preferences plus sessions are persisted in ~/.akvan/state.db without changing .env.

Telegram is one registered gateway integration. Future Slack, email, and web integrations can supply their own adapters, configuration, access policies, capabilities, and optional dependencies while reusing the same sessions, commands, approvals, and streaming service. Each gateway runs in its own background process; logs are written to ~/.akvan/logs/gateway-{id}.log.

Prompts and skills

Akvan builds one layered system prompt when the process starts. It uses ~/.akvan/SOUL.md for optional identity, then frozen memory blocks from MEMORY.md and USER.md when enabled, runtime guidance, a compact skill index, project instructions, and session metadata. Project instructions prefer .akvan.md or AKVAN.md, then AGENTS.md.

Skill layout

Akvan separates skill content from skill code:

• skills/<category>/<name>/SKILL.md at the repo root — bundled instruction packages shipped with Akvan
• agent/skills/ — Python discovery engine (registry.py, sync.py, tools)

Every skill must use the categorized layout:

skills/<category>/<name>/SKILL.md

Examples: skills/creative/claude-design/SKILL.md, ~/.akvan/skills/creative/claude-design/SKILL.md.

Runtime discovery

At runtime Akvan discovers skills from:

Location	Purpose
~/.akvan/skills/<category>/<name>/SKILL.md	User skills (seeded on install + personal additions)
.akvan/skills/<category>/<name>/SKILL.md	Project overrides (wins on name collision)

Install and update run akvan skills sync, which copies bundled skills from the app into ~/.akvan/skills/ while respecting local edits and deletions. Re-run manually with:

akvan skills sync

Opt out of bundled seeding by creating ~/.akvan/.no-bundled-skills.

Use /skills to list skills by category, /<skill-name> <request> to activate one explicitly, and /reload to rebuild the cached prompt and skill snapshot. The system prompt contains only compact skill metadata. The agent uses skills_list for discovery and skill_view to load full instructions or a referenced text resource on demand. Skill resources are read-only; bundled scripts are never executed automatically.

CLI reference

Commands

Command	Purpose
akvan	Interactive chat (default)
akvan model	Provider/model setup wizard
akvan tools	Web search and extract setup
akvan gateway	Gateway manager
akvan gateway restart	Restart running gateways to pick up code changes
akvan logs …	View and filter log files (see Logs)
akvan skills sync	Copy bundled skills into ~/.akvan/skills/
akvan skills reset <name>	Reset bundled skill manifest tracking
akvan skills reset <name> --restore	Restore a bundled skill from source
akvan skills curator status	Show agent-created skill usage
akvan skills curator archive	Archive idle agent-created skills
akvan skills curator restore <name>	Restore an archived skill
akvan skills curator pin|unpin <name>	Pin or unpin a skill

Global flags

Flag	Applies to	Purpose
--yolo	akvan, akvan gateway	Skip ordinary approvals; catastrophic commands remain blocked
--max-iterations N	akvan, akvan gateway	Max agent iterations per user turn (default: 30)
--model MODEL	akvan	Override AKVAN_MODEL for this session

In-session slash commands

Command	Purpose
/exit, /quit	Quit
/reload	Rebuild prompt and skills snapshot
/skills	List skills by category
/sessions [page]	Browse saved sessions (next, prev, or page number)
/resume N	Resume session number from /sessions
/learn …	Distill a workflow into a skill
/yolo	Toggle session approval bypass
/<skill-name> …	Activate a skill for one turn

When stdout is not a TTY, Akvan runs a simpler prompt loop without the Hermes-style pinned UI — useful for piping and scripting.

Test

uv run pytest

Provider Shape

All model calls go through a provider interface in agent.providers.base. OpenRouter is implemented in agent.providers.openrouter, and later providers can implement Provider.complete(...), Provider.stream_complete(...), and Provider.list_models(), then register their own setup handler.

License

Akvan Agent is open source under the MIT License.