# Install and connect

Get in touch with the Canopy team to install the LiteLLM plugin and obtain the Canopy integration
URL. The adapter supports LiteLLM `1.101.x` and must be installed in the same Python environment
as your proxy.

You need LiteLLM proxy administrator access and owner or administrator access to a Canopy
organization.

## Configure the LiteLLM host

Keep your existing LiteLLM database, master key, and salt key. Set these variables in the proxy's
runtime environment:

```sh
CANOPY_INTEGRATION_URL=https://YOUR-CANOPY-INTEGRATION-HOST
LITELLM_WORKER_STARTUP_HOOKS=canopy_litellm.integration:startup
STORE_MODEL_IN_DB=True
CANOPY_CONNECTION_FILE=/var/lib/canopy-litellm/connection.json
```

`CANOPY_INTEGRATION_URL` is the origin supplied by the Canopy team, without a path. The proxy
also requires `DATABASE_URL`, `LITELLM_MASTER_KEY`, and `LITELLM_SALT_KEY`. Do not replace existing
keys or share them with Canopy.

The connection file contains machine credentials. Mount its directory on persistent storage,
keep it private, and do not commit it or include it in a container image. All workers and replicas
for one installation must share the same directory at the same path. The filesystem must support
file locks and atomic rename.

Add the following entries to your LiteLLM YAML configuration. Merge them with existing settings
rather than replacing your model list, callbacks, or plugins.

```yaml
litellm_settings:
  callbacks:
    - canopy_litellm.plugin.canopy_routing_plugin
  custom_provider_map:
    - provider: canopy
      custom_handler: canopy_litellm.provider.canopy_provider

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  plugins:
    - name: canopy
      display_name: Canopy
      url: https://YOUR-LITELLM-HOST/canopy/
```

The plugin URL must use your browser-facing **LiteLLM** origin followed by `/canopy/`, not the
Canopy integration origin. Use HTTPS for hosted instances. Behind a reverse proxy, configure
trusted forwarding headers so LiteLLM sees the external scheme and host.

Restart LiteLLM after this initial setup. You do not need to add Canopy model entries or API keys
to YAML. Later model changes apply through the panel without a worker restart.

## Connect your organization

1. Open **Canopy** in the LiteLLM dashboard as a proxy administrator.
2. Select **Connect to Canopy** and open the approval link in its new tab.
3. Sign in to Canopy and choose an organization you own or administer.
4. Check the LiteLLM origin shown, then approve the connection.
5. Return to LiteLLM and select **I've approved**.

Approval lets this instance's proxy administrators manage the integration and view its reports.
It also creates an inference key that can spend the organization's Canopy credits. Only approve
a connection you started. Approval links expire after ten minutes; start again if one expires.

To revoke a connection, open **LiteLLM** in the Canopy web app. Revocation disables installation
access and its inference key. The adapter removes its managed routes when it confirms revocation.

[Configure your first model](/litellm/usage)