Skip to main content

Setup

This page is intended to help you get Viv installed and set up with the necessary prerequisites. It does NOT cover the debug process itself; for that, go back to the main instructions: Viv CLI Instructions

0. Prerequisites​

Have the following ready before you start:

  1. An x64 Linux machine with glibc version 2.28 or higher.

    To ensure that your version of glibc is new enough, run ldd --version. If it is older than 2.28, it's generally possible to run a container with a newer version.

  2. A way of getting a language model API key for one of the following model families. Either direct access from the model creator's API (e.g. api.openai.com) or a third-party cloud provider (e.g. Azure) are supported.

    • Claude
    • OpenAI GPT family
    • Any model running on an OpenAI-compatible server using chat completions endpoint (e.g. OpenRouter)
    • Any model running on a vLLM server

    Alternatively, if you have a Claude Code subscription, you can use the local claude CLI instead of a separate API key. See Using Claude Code as your provider below.

1. Install Viv​

  1. Install CLI by running:

    curl -fsSL install.silogy.io | bash

    This will:

    If you don't want to run this script, you can also run these steps manually.

  2. Run viv version to verify installation. Ensure that the Viv version is as expected.

2. License and LLM provider credentials setup​

Viv requires a Viv license and LLM provider credentials in order to use. The easiest way to get started is to type:

viv
# or path/to/viv if it's not in your $PATH

The first time you run this command, you'll be prompted to set up a Viv license and LLM configuration. Follow the prompts to get started. Here's what it'll look like:

As you can see in the video, the quickstart process sets up a license key and a model provider API key. You'll also be asked to pick a language for user-facing output (English or Korean) — the agent still reasons in English internally, so this only affects the final bug description and fix steps.

Manual setup

For more details on how to set up Viv, or to modify your setup after initially setting it up, see the configuration reference.

Model choice

For information on default models by provider, as well as instructions on how to set which model is used, see the model configuration reference.

Alternative: use the Claude Code CLI instead of an API key​

If you already use Claude Code, you can have Viv drive the agent through your local claude installation instead of managing an API key. Install claude and run claude login once. You can then select Claude Code in the first-run setup picker, or manually set "llm": { "provider": "claudecode" } in ~/.viv/config.json. Either way, no claude-key.txt is required.

During the setup picker, Viv:

  • Auto-detects claude on PATH and verifies the install is signed in via a minimal claude -p call.
  • Prompts for an explicit path if claude is not on PATH, and saves it as llm.claudecode_path in config.json.
  • Surfaces the claude CLI's own error (e.g. Not logged in · Please run /login) if the sign-in check fails, and lets you retry after running /login in another terminal.

Trade-off: the agent runs with Claude Code's built-in read-only tools (Read, Grep, Glob) rather than Viv's native tool set. For most failing-test workflows this is equivalent; for heavily customized setups the claude provider gives you more control over tools and model selection.

Appendix: How to create an API key​

Just to make things easier, here's how you create an API key:

Create an OpenAI API key​

If you are using OpenAI:

  1. Go to https://auth.openai.com/log-in and sign up.

  2. In the upper right of the screen, click on the gear icon to go to Settings.

    1. If you see "Start building" in the upper right, click on it and fill in your information to create an organization on the OpenAI platform, pressing "I'll do it later" for everything. If you're prompted to create an API key, skip it for now.

  3. Ensure you have sufficient credit: in the left panel, under the Organization heading, click Billing. If you don't have at least a few dollars in your account, add some.

  4. Also in the left panel under Organization, click on "API keys."

  5. Click on "+ Create new secret key."

  6. If you are setting up Viv to use interactively, then under "Owned by," select "You." If you intend for Viv to be called by automation such as CI, choose "Service account" instead.

  7. Give the key a meaningful name and under "Project" select "Default project."

  8. If you chose "Owned by: You" above, set the Permissions to Restricted. Under "Model capabilities," set "Responses (/v1/responses)" to "Write." You do not need to set any other permissions. It should look like this:

    OpenAI API key permissions

  9. Press "Create secret key" to view the secret key. Save this key somewhere secure.

Create a Claude API key​

If you are using Claude:

  1. Go to https://platform.claude.com/login and sign up.
  2. Expand the left hand side panel. Under Manage, click Settings.
  3. Go the Billing section, add your payment information, and purchase a few dollars' worth of credits.
  4. Go to the API keys section and click "+ Create key."
  5. Select the Default workspace and give your key a name.
  6. Press "Add" to view the secret key. Save this key somewhere secure.