Configuration reference

This is an exhaustive reference for manually configuring Viv.

All Viv configuration files are in the $HOME/.viv directory for the current Linux user. For example, the fedora user's Viv config files on a Linux system will be under /home/fedora/.viv. This architecture allows a single Viv binary to be shared among multiple users, with each user's preferences being respected.

A working Viv installation requires three files to be in $HOME/.viv:

config.json: Model-specific configuration.
license: A Silogy-issued license for Viv.
An API key file issued by your LLM provider.

An optional file can also be placed here:

VIV.md: A user-level VIV.md that is automatically included in every Viv session. Use this for personal preferences that apply across all projects (e.g., your team, focus areas, or debugging conventions). This supplements any project-level VIV.md found in code directories and any files passed via --viv-md.

`config.json`

By default, Viv will expect this file to be located at $HOME/.viv/config.json. It should be a single JSON object with the following keys:

llm: An object with the following key-value pairs:
- provider: The model provider type. Should be one of the following values:
  - openai: OpenAI
  - claude: Claude
  - claudecode: Drive the agent via the locally installed claude CLI (the Claude Code tool) instead of calling the Anthropic API directly. Requires the claude binary on PATH; authentication and routing are handled by claude itself, so base_url, query_params, and the API key file are not used. The agent runs with Claude Code's built-in read-only tools (Read, Grep, Glob) plus Viv's MCP servers for waveforms, SystemVerilog, and the knowledge store. If the binary is not on PATH, set claudecode_path (see below).
  - vllm: A vLLM-compatible model provider. This protocol is similar to but slightly different from the OpenAI API. Note: If you are using vllm, you must supply both models and the base_url below.
- base_url: The base URL for the model provider. This is how you choose where your LLM calls should be routed. For example, if the chat completions URL is located at https://example.com/v1/chat/completions, then set "base_url": "https://example.com/v1" here. The default base URLs are:
  - openai: https://api.openai.com/v1
  - claude: https://api.anthropic.com. Note that there is no v1; the SDK appends it.
  - vllm: http://localhost:8000/v1
- query_params: Any additional query parameters that are added to the URL. This should be an object with keys and values as strings. These query parameters will be added to all API calls.
- models: (optional, except for vllm) An object with the following key-value pairs. Detailed instructions are located in the model reference.
  - agent: The model that drives the main debugging agent, as well as subagents that perform specific tasks during debugging. For example: "agent": "meta-llama/Llama-3.3-70B-Instruct".
  - chat: The model that drives the chat function and answers user questions. For example: "chat": "meta-llama/Llama-3.3-70B-Instruct".
- reasoning_effort: (optional) Controls how much reasoning the LLM performs. Valid values: fast, balanced, thorough. See Reasoning effort below.
- claudecode_path: (optional) Explicit path to the Claude Code (claude) executable. Only used when provider is claudecode. If omitted, Viv resolves claude from your PATH. Set this when the binary is in a non-standard location.
fsdb_reader_paths: A list of strings. The directory path or paths containing FSDB reader libraries for your machine, specifically the files libnffr.so and libnsys.so. Most users will just pass a single directory, which will be: [ "(your Synopsys installation directory)/verdi/(your Verdi version)/share/FsdbReader/linux64" ].
rascal_workspace: (optional) A directory path where the waveform server (Rascal) stores its data and logs. When set to a path X, Rascal will use X/data for temporary files and downloads, and X/log/ for its log files (each session creates a timestamped log file like rascal-YYYYMMDD-HHMMSS-PID.log). Directories are created automatically; Viv will report a clear error if the path is not writable. This is useful when the default directory (~/.viv/rascal) is not writable. The --wave-server-logs CLI flag, if provided, overrides the log file location.
quiet: (optional) Boolean. When true, only the latest tool call is shown in the UI instead of all tool calls. Default: false (show all). Can be overridden per-run with --quiet or --no-quiet.
exit_on_finish: (optional) Boolean. When true, Viv exits immediately after analysis completes instead of entering the chat phase. Requires --log-file (-l) or --export-markdown to be specified so results are captured. Default: false. Can be overridden per-run with --exit-on-finish or --no-exit-on-finish.
slang: (optional) Configuration for the SV language server (slang-server), which provides SystemVerilog code intelligence during analysis.
- enabled: Boolean. Set to false to disable the language server entirely. Default: true. Can also be disabled per-run with --disable-lsp.
- binary_path: (optional) Explicit path to the slang-server binary. If omitted, Viv searches PATH.
- args: (optional) Extra CLI arguments for slang-server.
- indexing_timeout_ms: (optional) Indexing timeout in milliseconds. Default: 120000.
export_template: (optional) A natural language string describing how Markdown exports should be formatted. When set, both --export-markdown and the /export slash command use an LLM call to format the output according to this template instead of the default format. See Export template below.
knowledge: (optional) Boolean. Controls the persistent project knowledge store. The agent remembers spec locations, block-to-spec mappings, and codebase facts across sessions. Default: true. Set to false to disable. See Knowledge store below.
knowledge_path: (optional) Path to the knowledge store directory. Default: $HOME/.viv/projects/. Override this for CI/CD or container environments where $HOME/.viv/ is ephemeral (e.g., "/mnt/viv-knowledge"). Can also be set via the VIV_KNOWLEDGE_PATH environment variable, which takes priority over this config field.
search_exclude: (optional) A list of glob patterns for directories to exclude from code search. When set, the agent's code_file_finder and regex_code_search tools will skip files matching these patterns. Log search tools (regex_log_search, log_fetcher) are not affected. See Search exclude below.
language: (optional) Output language for the user-facing analysis artifacts (bug description and fix steps). Valid values: en (default), ko (Korean). The agent loop itself continues to reason in English regardless of this setting — only the final summary artifacts switch language. This separation keeps reasoning quality intact, since frontier models still perform best when their chain-of-thought is in English. Can be overridden per-run with --lang en or --lang ko. This setting applies to viv submit only; viv swarm currently produces its synthesized output in English regardless of the language chosen.
mcp_servers: This key is managed by the viv mcp command. You can skip this key or leave it as the empty array []. Once this has been populated by adding MCP servers, it should not be edited manually.

A typical config.json looks like this:

{
  "mcp_servers": [],
  "fsdb_reader_paths": [
    "/opt/synopsys/verdi/X-2025.06-SP1/share/FsdbReader/linux64"
  ],
  "rascal_workspace": "/my/special/rascal/workspace",
  "quiet": false,
  "exit_on_finish": false,
  "llm": {
    "provider": "vllm",
    "base_url": "https://my-internal-model-server/api/v1",
    "models": {
      "agent": "meta-llama/llama-4-maverick",
      "chat": "meta-llama/llama-4-maverick"
    }
  },
  "export_template": "Format as a JIRA ticket with Summary, Root Cause, and Suggested Fix sections. Use bullet points and keep it under 500 words.",
  "search_exclude": ["**/3PS*", "**/GEN*"]
}

note

You can pass an alternate location for config.json, as well as all other configuration files, using the command-line configuration override options.

License file

Depending on your setup, Viv will either use a fixed license (also called a node-locked license) or a floating license. If you're not sure which you're using, it's probably a fixed license.

Fixed license

If you're using a per-machine license, the default expected location for the file is $HOME/.viv/license. The file must contain just the license, with no quotation marks or other formatting except optional whitespace. Set it like so:

# Set a variable with the license key data. The license will be a long string
# that always starts with the characters "eyJh".
VIV_LICENSE_KEY=eyJh...

# Write to the license file
echo $VIV_LICENSE_KEY > $HOME/.viv/license

To ensure the license is valid, run:

path/to/viv license info

This will print something like:

$ viv license info

✓ Valid License

License Information:
  Licensee: Example Corporation
  Email: [email protected]
  Expires: 12/3/2026 (in 322 days)

You can pass a different location for the license using the --license <path to license file> command.

Floating license

If you're using a floating license, please reach out to your Silogy point of contact for one-on-one help.

API key file

A file containing the API key for your language model server. By default, the file name must be one of openai-key.txt, claude-key.txt, or vllm-key.txt corresponding to your chosen provider. The file must contain just the API key, with no quotation marks or other formatting, for example, sk-proj-....

As with other configuration, you can override the location of this API key file using the --api-key-file <path to key file> command, or pass an API key directly as a string using --api-key <key>.

note

The claudecode provider does not use an API key file. Authentication is delegated to the local claude CLI — sign in once with claude login and Viv will route requests through it.

Command-line configuration overrides

Instead of using the default $HOME/.viv/ directory, you can specify alternate paths for configuration files using command-line flags. These flags apply to all Viv commands.

Flag	Description
`--config <path>`	Path to a config.json file (replaces `$HOME/.viv/config.json`)
`--license <path>`	Path to a license file (replaces `$HOME/.viv/license`)
`--api-key <key>`	API key value passed directly on the command line
`--api-key-file <path>`	Path to a file containing the API key

note

--api-key and --api-key-file are mutually exclusive. Use one or the other, not both.

When to use command-line overrides

These flags are useful when:

Running in CI/CD pipelines: Pass secrets and configuration without writing to the filesystem.
Managing multiple projects: Use different configurations for different projects without modifying ~/.viv.
Testing configuration changes: Try a new config without overwriting your current setup.

Example usage

# Use a project-specific configuration
viv submit --artifact-path ./logs \
  --config ./project-config.json \
  --license ./team-license.txt \
  --api-key-file ./secrets/openai-key.txt

# Pass API key directly (useful in CI where secrets are environment variables)
viv submit --artifact-path ./logs \
  --config ./config.json \
  --api-key "$OPENAI_API_KEY"

Resolution order

When determining which configuration to use, Viv checks in this order:

Command-line flags (--config, --license, --api-key, --api-key-file)
Environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, LLAMA_API_KEY, VLLM_API_KEY)
Default files in $HOME/.viv/

Reasoning effort

The reasoning_effort field inside llm controls how much reasoning the LLM performs at each step. This is the config-file equivalent of the --effort CLI flag. Valid values are fast, balanced, and thorough.

{
  "llm": {
    "provider": "openai",
    "reasoning_effort": "fast"
  }
}

When no reasoning_effort config or --effort flag is set, Viv uses its built-in defaults tuned for each stage of the analysis (equivalent to balanced). The --effort CLI flag takes priority over the config file setting.

Export template

The export_template field lets you customize the Markdown format produced by --export-markdown and the /export slash command. Set it to a natural language description of the format you want, and Viv will use an LLM call to transform the analysis results accordingly.

{
  "export_template": "Format as a JIRA ticket with Summary, Root Cause, and Suggested Fix sections. Use bullet points and keep it under 500 words."
}

When export_template is not set, Viv uses its built-in default format which includes metadata, a bug description, and investigation steps.

If the LLM formatting call fails, the export will fail with an error message indicating that the template was not applied.

Knowledge store

The knowledge store gives Viv persistent memory across debug sessions. The agent automatically remembers specification file locations, block-to-spec associations, and codebase observations. On subsequent runs against the same project, the agent starts with this context instead of a blank slate.

The knowledge store is enabled by default. To disable it, set "knowledge": false in your config.json.

How it works

Project detection. Viv automatically identifies the project using the git remote URL. If no git remote is available, the --project <name> flag provides an explicit override.
Bootstrap. On the first run against a new project, Viv scans the code directories for specification files (PDFs, docs in spec/ directories, etc.) and stores their locations.
Session learning. During analysis, the agent can store new knowledge it discovers (spec locations, block-to-spec mappings, codebase facts) using built-in tools.
Consolidation. At the end of each session, high-confidence knowledge is promoted to the core prompt so it's immediately available on the next run.

Storage

Knowledge is stored locally at $HOME/.viv/projects/<project-id>/. No data leaves the customer's machine.

For CI/CD or container environments, override the storage path:

# Via environment variable (highest priority)
export VIV_KNOWLEDGE_PATH=/mnt/viv-knowledge

# Or via config.json
{
  "knowledge_path": "/mnt/viv-knowledge"
}

Management

Use viv knowledge to inspect and manage the store. See viv knowledge in the CLI reference for the full list of subcommands.

Search exclude

The search_exclude field lets you exclude directories from the agent's code search tools. This is useful when your code root contains large directories (e.g., build output, regression results) that slow down searches, especially on NFS-mounted filesystems.

{
  "search_exclude": ["**/3PS*", "**/GEN*"]
}

Each entry is a glob pattern. The patterns are applied to the code_file_finder and regex_code_search tools. Log search tools (regex_log_search and log_fetcher) are not affected, since the log/artifact path is passed separately via --artifact-path and often resides inside a directory that would otherwise be excluded.

When search_exclude is set, the excluded patterns are automatically appended to the agent's tool descriptions so the agent knows which areas are off-limits for code search.

An empty array ([]) or omitting the field entirely means no directories are excluded.

Special note for Docker/Podman setups

If you are running Viv inside our container image, the configuration files must be inside the /home/viv-user/.viv directory. We recommend starting the container with a no-op command, copying all necessary files into it, and running Viv using exec. For example:

# Create local configuration directory on the host machine:
mkdir my-viv-config

# Make changes to config.json:
vim my-viv-config/config.json

# Set up Viv license
cat 'eyJ...' > my-viv-config/license

# Set up provider key, for example if you're using OpenAI:
cat 'sk-proj-...' > my-viv-config/openai-key.txt

# Start the container
CONTAINER_ID=$(podman run -d silogy-viv:0.1.0 bash -c 'while true; do sleep 1; done')

# Copy configuration
podman cp ./my-viv-config $CONTAINER_ID:/home/viv-user/.viv

# Test that Viv runs correctly
podman exec -it $CONTAINER_ID viv version

config.json​

License file​

Fixed license​

Floating license​

API key file​

Command-line configuration overrides​

When to use command-line overrides​

Example usage​

Resolution order​

Reasoning effort​

Export template​

Knowledge store​

How it works​

Storage​

Management​

Search exclude​

Special note for Docker/Podman setups​

`config.json`

License file

Fixed license

Floating license

API key file

Command-line configuration overrides

When to use command-line overrides

Example usage

Resolution order

Reasoning effort

Export template

Knowledge store

How it works

Storage

Management

Search exclude

Special note for Docker/Podman setups