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
   • Gemini
   • Any model running on a vLLM server

1. Install Viv

curl/npm (fastest)

1. Install CLI by running:

   curl -fsSL install.silogy.io | bash

   This will:

   • Install Node.js ≥ 22, if it doesn't exist. Node.js is a JavaScript runtime that Viv is built on.
   • Install the CLI tool from https://www.npmjs.com/package/@silogy/viv

   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.

Tarball

This is applicable if you received a viv.tar.gz installation package containing a minified version of Viv's JavaScript source code. To install:

1. Run node version to ensure that Node is installed. The version must be greater than v16.20.2. If it's not available or an older version, install an up-to-date version or let us know if this isn't possible.

2. Extract the tarball in a convenient location.

   1. Once you've done this, optionally make sure the extraction worked by cd-ing into the viv directory and running tree . -I node_modules (-I node_modules prevents the huge node_modules directory from being printed). You should see something like this:

      viv
      ├── bin
      │   └── viv
      ├── cli
      │   ├── package.json
      │   ├── rascal-binaries
      │   │   └── aarch64-apple-darwin
      │   │       └── rascal
      │   └── scripts
      │       └── install-rascal.cjs
      ├── package.json
      ├── rascal-binaries
      │   └── aarch64-apple-darwin
      │       └── rascal
      ├── src
      │   └── shared
      │       └── package.json
      └── yarn.lock

3. Inside the newly created viv directory, run: bin/viv --version and ensure that the Viv version is as expected.

Docker/Podman

This is applicable if you received a viv-container-image.tar.gz file. This file contains a gzipped container image. To load the image, simply unzip and load it by running:

gzip -d viv-container-image.tar.gz
docker image load -i viv-container-image.tar  # or 'podman ...'

The resulting image will be tagged silogy-viv:[current version number].

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.

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.

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:

   

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.