Configuration reference

Every configurable surface in visvoai-cli — API keys, permissions, MCP servers, skill libraries — follows the same two-layer pattern:

~/.visvoai/config.toml              global — applies everywhere
<project>/.visvoai/config.toml      project — extends/overrides for one repo

VISVOAI_HOME overrides the global root (defaults to ~/.visvoai) if you need an isolated home, e.g. in tests or CI.

The project file is located by walking up from your current directory looking for an existing .visvoai/ folder — the same way git finds .git — so it works from any subdirectory of the project.

A starter config

# ~/.visvoai/config.toml — the pieces most people want on day one.

# MCP servers (or use: visvoai mcp add <name> -- <command...>)
[mcp_servers.chrome]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest"]

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
headers = { Authorization = "Bearer ${LINEAR_API_KEY}" }   # ${VAR} from env — never paste tokens

# Skill libraries you already have, loaded as your own (trusted) skills:
[skills]
extra_dirs = ["~/.claude/skills"]

`[api_keys]` — provider keys

Resolution order, highest wins:

An exported environment variable ({PROVIDER}_API_KEY), including anything a local .env loaded.
<project>/.visvoai/secrets.toml [api_keys] — written 0600 and auto-added to the project's .gitignore so a key never lands in version control.
~/.visvoai/config.toml [api_keys] — the global default.

/login in the TUI writes to the project secrets file for you; editing it by hand works the same way.

`[permissions]` — approval and write confinement

[permissions]
allow_shell = ["git status", "git diff", "ls", "pytest"]   # command prefixes, pre-approved
allow_write = ["*.md", "docs/**", "notes/*.txt"]           # path globs, pre-approved
write_roots = ["../sibling-lib", "/abs/shared"]            # extra roots writes may target

Global and project [permissions] tables merge (both layers' rules apply); see Why this one for exactly how each field is matched.

`[skills]` — extra libraries

[skills]
extra_dirs = ["~/.claude/skills", "~/dotfiles/skills"]

Directories listed here load as your own trusted skills — no per-skill approval, since you configured the path yourself.

`[mcp_servers.<name>]` — tool servers

See MCP for the full stdio vs. remote-HTTP shape and the ${VAR} secret-expansion rule.

On-disk layout

~/.visvoai/
  config.toml                          global config (all sections above)
  agents/<name>.md                     global agents
  skills/<name>/SKILL.md               global skills
  tools/*.py                           plugin tools (global-only)
  cache/models.json                    cached models.dev catalog fetch
  projects/<project-id>/
    conversations/<conversation-id>/   per-conversation history + checkpoints
    checkpoints.git/                   shadow repo for time-travel
    agent_trust.toml                   project-agent approval hashes
    skill_trust.toml                   project-skill approval hashes
    mcp_trust.toml                     project-MCP-server approval hashes

<project>/.visvoai/
  config.toml         project config — mcp_servers, permissions, skills (may be checked in)
  secrets.toml         project API keys (gitignored, 0600)
  agents/<name>.md      project agents (shareable, trust-gated)
  skills/<name>/        project skills (shareable, trust-gated)

Configuration reference

A starter config

[api_keys] — provider keys

[permissions] — approval and write confinement

[skills] — extra libraries

[mcp_servers.<name>] — tool servers

On-disk layout

On this page

`[api_keys]` — provider keys

`[permissions]` — approval and write confinement

`[skills]` — extra libraries

`[mcp_servers.<name>]` — tool servers