# How to Configure the Composio SDK with Environment Variables and Custom Base URLs

> Learn to configure the Composio SDK using environment variables and custom base URLs for flexible API access. Master your integration settings effectively.

- Repository: [Composio/composio](https://github.com/composiohq/composio)
- Tags: how-to-guide
- Published: 2026-02-19

---

**The Composio SDK resolves configuration through a strict hierarchy where explicit constructor arguments override environment variables (`COMPOSIO_API_KEY`, `COMPOSIO_BASE_URL`), which override the user config file at `~/.composio/user-config.json`, with `https://api.composio.dev` as the final default.**

The Composio SDK provides flexible configuration options for connecting to the Composio API, whether you're using the managed cloud service or a self-hosted instance. Understanding how to configure the SDK with environment variables and custom base URLs ensures your applications can seamlessly switch between development, staging, and production environments without code changes. This guide examines the configuration resolution logic implemented in the `ComposioHQ/composio` repository.

## Configuration Hierarchy in the Composio SDK

The configuration resolution follows a deterministic priority order implemented in [`ts/packages/core/src/utils/sdk.ts`](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/utils/sdk.ts). The `getSDKConfig` function merges values from multiple sources:

1. **Explicit constructor arguments** passed to `new Composio({ apiKey, baseURL })`
2. **Environment variables** – `COMPOSIO_API_KEY` and `COMPOSIO_BASE_URL`
3. **User configuration file** at `~/.composio/user-config.json`
4. **Default values** – `https://api.composio.dev` for the base URL

If no API key is resolved after checking all sources, the SDK throws a `ComposioNoAPIKeyError`.

## Using Environment Variables

### Setting COMPOSIO_API_KEY and COMPOSIO_BASE_URL

The SDK automatically detects environment variables at runtime. Set these in your shell or deployment environment:

```bash
export COMPOSIO_API_KEY=sk_live_1234567890abcdef
export COMPOSIO_BASE_URL=https://backend.mycompany.com

```

With these variables set, instantiate the SDK without arguments:

```typescript
import { Composio } from '@composio/core';

// Automatically uses COMPOSIO_API_KEY and COMPOSIO_BASE_URL from env
const composio = new Composio();

await composio.tools.list(); // Requests go to custom base URL

```

### Loading from .env Files

For local development, use the `dotenv` package to load variables from a `.env` file:

```bash

# .env at project root

COMPOSIO_API_KEY=sk_live_abcdef1234567890
COMPOSIO_BASE_URL=https://api.composio.dev

```

```typescript
// index.ts
import 'dotenv/config'; // Automatically loads .env into process.env
import { Composio } from '@composio/core';

const composio = new Composio(); // env vars are now in process.env
await composio.whoami();

```

## Configuring Custom Base URLs

The default base URL is defined in [`ts/packages/core/src/utils/constants.ts`](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/utils/constants.ts) as `https://api.composio.dev`. You can override this to point to self-hosted instances or staging environments.

Override via environment variable:

```bash
export COMPOSIO_BASE_URL=https://staging-api.composio.dev

```

Or pass explicitly to the constructor (which takes precedence):

```typescript
const composio = new Composio({
  baseURL: 'https://private-gateway.myenterprise.com',
  apiKey: process.env.COMPOSIO_API_KEY // Can mix env vars and explicit args
});

```

## Constructor-Level Configuration

Explicit arguments passed to the `Composio` constructor in [`ts/packages/core/src/composio.ts`](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/composio.ts) override all other configuration sources. This is useful for multi-tenant applications or when testing against different endpoints:

```typescript
import { Composio } from '@composio/core';

// Explicit configuration ignores env vars and user config
const composio = new Composio({
  apiKey: 'sk_test_abcdef123456',
  baseURL: 'https://staging.api.composio.dev',
});

await composio.tools.execute('GITHUB_CREATE_REPO', {
  userId: 'user_123',
  arguments: { name: 'my-repo', private: true },
});

```

## Advanced: User-Level Configuration

The SDK supports persistent user-level configuration stored in `~/.composio/user-config.json`. This file is managed by the CLI and read by `getUserDataJson` in [`ts/packages/core/src/utils/sdk.ts`](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/utils/sdk.ts).

Example user config structure:

```json
{
  "api_key": "sk_live_user_config_key",
  "base_url": "https://api.composio.dev"
}

```

This configuration acts as a fallback when neither constructor arguments nor environment variables are present. It is particularly useful for CLI authentication that persists across SDK sessions.

## Summary

- The Composio SDK resolves configuration through a strict hierarchy: **constructor arguments > environment variables > user config file > defaults**.
- Set `COMPOSIO_API_KEY` and `COMPOSIO_BASE_URL` environment variables to configure the SDK without code changes.
- The default base URL is `https://api.composio.dev`, defined in [`ts/packages/core/src/utils/constants.ts`](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/utils/constants.ts).
- Pass explicit `apiKey` and `baseURL` to the `Composio` constructor to override all other sources.
- User-level configuration at `~/.composio/user-config.json` provides persistent fallback settings managed by the CLI.

## Frequently Asked Questions

### What is the priority order for Composio SDK configuration sources?

The SDK checks configuration sources in this exact order: first, explicit arguments passed to the `new Composio()` constructor; second, environment variables `COMPOSIO_API_KEY` and `COMPOSIO_BASE_URL`; third, the user configuration file at `~/.composio/user-config.json`; and finally, the default base URL of `https://api.composio.dev`. If no API key is found after checking all sources, the SDK throws a `ComposioNoAPIKeyError`.

### Can I use the Composio SDK with a self-hosted or private instance?

Yes, you can point the SDK to any custom base URL by setting the `COMPOSIO_BASE_URL` environment variable or passing the `baseURL` parameter directly to the `Composio` constructor. This allows you to connect to self-hosted instances, staging environments, or enterprise gateways while using the same SDK interface.

### How do I manage multiple API keys or environments in the same application?

For multi-tenant applications or scenarios requiring different credentials, instantiate separate `Composio` clients with explicit constructor arguments. Each instance maintains its own configuration, allowing you to interact with different endpoints or use different API keys within the same process without environment variable conflicts.

### What happens if I don't provide an API key?

If the SDK cannot resolve an API key from constructor arguments, the `COMPOSIO_API_KEY` environment variable, or the user configuration file, it will throw a `ComposioNoAPIKeyError` during instantiation. This synchronous validation ensures that API calls fail fast rather than attempting unauthenticated requests.