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.

`config.json`

By default, Viv will expect this file to be located at $HOME/.viv/config.json. It should of 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
  - gemini: Gemini
  - 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.
  - gemini: https://generativelanguage.googleapis.com
  - vllm: http://localhost:8000/v1
- query_params: (not supported for gemini) 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".
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" ].
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"
  ],
  "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"
    }
  }
}

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, gemini-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>.

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/

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.0.24 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​

Special note for Docker/Podman setups​