# CocoIndex Plus installation

> **CocoIndex v1.** This page documents CocoIndex **v1** — a ground-up redesign from v0. When writing code, ignore any v0 flow-builder DSL or deprecated decorators.
>
> Source: https://cocoindex.io/docs/getting_started/installation/ · Docs index: https://cocoindex.io/docs/llms.txt · Agent skill: https://cocoindex.io/docs/skill.md
>
> v0→v1 quick map — if you reach for these v0 symbols, stop and use the v1 form: `@cocoindex.flow_def`/`FlowBuilder` → `coco.App` + a `@coco.fn` main function; `add_collector()`/`collect()`/`export()` → declare target states (`declare_row`, `declare_file`); `cocoindex.sources/functions/targets.*` → connector APIs (`localfs.walk_dir`, `coco.ops.*`, `postgres.declare_table_target`). Full mapping + API reference: https://cocoindex.io/docs/skill.md.

CocoIndex Plus is the enterprise edition of CocoIndex. It ships closed-source
binaries from a private Python package index and validates a license key at
runtime. This guide walks through both pieces.

## System requirements

CocoIndex Plus is supported on the following operating systems:

- **macOS**: 11.0+ on arm64
- **Linux**: x86_64, glibc 2.28+ (e.g., Debian 10+, Ubuntu 18.10+, Fedora 29+, CentOS/RHEL 8+)

## Install Python and pip

1. Install [Python](https://wiki.python.org/moin/BeginnersGuide(2f)Download.html). We support Python 3.11+.
2. Install [pip](https://pip.pypa.io/en/stable/installation/), a Python package installer.

## Install CocoIndex Plus

CocoIndex Plus is published to a private Python index hosted at Keygen. You
need an install token (delivered with your subscription) to fetch it. The
general index URL is:

```sh
https://token:${COCOINDEX_PLUS_INSTALL_TOKEN}@pypi.pkg.keygen.sh/cocoindex-io/simple
```

### Using pip

Export the token to an environment variable rather than hard-coding it in the
command — otherwise it ends up in your shell history.

```sh
export COCOINDEX_PLUS_INSTALL_TOKEN="<your-install-token>"
pip install -U \
  --index-url "https://token:${COCOINDEX_PLUS_INSTALL_TOKEN}@pypi.pkg.keygen.sh/cocoindex-io/simple" \
  cocoindex-plus
```

### Using uv

Add this to your `pyproject.toml`:

```toml
[tool.uv.sources]
cocoindex-plus = { index = "keygen" }

[[tool.uv.index]]
name = "keygen"
explicit = true
url = "https://pypi.pkg.keygen.sh/cocoindex-io/simple"
```

Then provide the install token through environment variables:

```sh
export UV_INDEX_KEYGEN_USERNAME=token
export UV_INDEX_KEYGEN_PASSWORD="<your-install-token>"
uv add cocoindex-plus
```

## Set your CocoIndex Plus license key

Before running anything that imports `cocoindex`, set the
`COCOINDEX_PLUS_LICENSE_KEY` environment variable. This is a separate
credential from the install token.

```sh
export COCOINDEX_PLUS_LICENSE_KEY="<your-license-key>"
```

CocoIndex Plus validates the license key during engine initialization
(triggered at `import cocoindex`). There are two kinds of license keys, and
CocoIndex automatically detects which one you have from its format — both use
the same `COCOINDEX_PLUS_LICENSE_KEY` variable:

- **Standard key** (the default). Validated against Keygen over the network on
  startup. The signed response is cached locally and stays valid for up to 1
  week, so you only need connectivity for the initial validation or once per
  week — the CLI and library keep working offline in between.
- **Offline (signed) key.** A cryptographically signed key of the form
  `key/<data>.<signature>`. It carries its own license data and is verified
  locally against a public key embedded in CocoIndex Plus, so **no network
  request is ever made**. This is the right choice for fully air-gapped
  environments.

### Offline / air-gapped validation

If your deployment has no outbound internet access, ask us for an **offline
license key**. It looks like this and is set exactly the same way:

```sh
export COCOINDEX_PLUS_LICENSE_KEY="key/eyJhY2NvdW50Ijp7…fX0=.iJVUYxR…"
```

An offline key embeds its own expiry, so when it nears expiration we'll issue a
replacement — swap the environment variable and you're done. No validation
traffic leaves your machine at any point.

**Note**
Standard keys and offline keys are issued from different Keygen policies. If you
need to switch modes, contact us for the appropriate key — you don't need to
change any code or configuration beyond the environment variable.

**Caution — Security notes**
- Don't commit the install token or license key to source control.
- The install token and license key are delivered in separate communications
  — store both somewhere your shell can read them (e.g. a secrets manager,
  `.envrc`, or your CI's secret store), not in plaintext in `~/.bashrc`.

## Install Postgres

Skip this step if you already have a Postgres database with the `pgvector`
extension installed.

If you don't have Postgres yet, the quickest path is Docker Compose:

1. Install [Docker Compose](https://docs.docker.com/compose/install/).
2. Start a Postgres instance configured for CocoIndex:

   ```sh
   docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex/refs/heads/main/dev/postgres.yaml) up -d
   ```

## Install the Claude Code skill (optional)

If you use [Claude Code](https://claude.com/claude-code), the official
CocoIndex skill adds workflow guidance directly inside the agent. Run these
inside Claude Code:

```
/plugin marketplace add cocoindex-io/cocoindex-claude
/plugin install cocoindex-skills@cocoindex
```

## All set

You're ready to start using CocoIndex Plus. Continue with the
[quickstart](/getting_started/quickstart/) to build your first index.