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

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. 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:

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

With these variables set, instantiate the SDK without arguments:

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:

# .env at project root

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

// 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 as https://api.composio.dev. You can override this to point to self-hosted instances or staging environments.

Override via environment variable:

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

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

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 override all other configuration sources. This is useful for multi-tenant applications or when testing against different endpoints:

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.

Example user config structure:

{
  "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.
• 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}