Environment Variables

This page lists only the settings meaningful to external developers — the ones you can set in your own service that actually change behaviour. Platform-internal service configuration (database connections, object storage credentials, model keys) is not listed; Profy operates those and you neither see nor need them.

SDK configuration

Auth and address

Variable	Purpose	Default
`PROFY_API_KEY`	Platform API key, shaped `sk-pro-...`	none (required)
`PROFY_BASE_URL`	API base URL	`https://api.profy.cn`

Resolution order puts constructor arguments ahead of environment variables:

Profy(api_key="sk-pro-xxx")        # explicit wins
Profy()                            # falls back to PROFY_API_KEY

A missing PROFY_API_KEY raises at construction rather than degrading to anonymous:

Profy: api_key is required. Pass it directly or set the PROFY_API_KEY
environment variable.

A trailing slash on PROFY_BASE_URL is stripped automatically, so https://api.profy.cn/ and https://api.profy.cn behave identically. For private deployments or local development this is the only setting you change; nothing else in the SDK differs.

OAuth applications

Third-party apps acting on behalf of many Profy users use application credentials rather than an API key:

Variable	Purpose	Default
`PROFY_APP_ID`	OAuth application client_id	none (required)
`PROFY_APP_SECRET`	OAuth application client_secret	none (required)
`PROFY_BASE_URL`	as above, shared	`https://api.profy.cn`

Missing either one raises:

ProfyApp: client_id and client_secret are required. Pass them directly or
set PROFY_APP_ID / PROFY_APP_SECRET environment variables.

The default scope on authorization requests is events:write.

PROFY_APP_SECRET is a server-side credential. The moment it appears in a browser bundle, a mobile app, or any client code it is effectively public — the authorization-code exchange must happen on your server.

Deliberately not environment variables

A few settings are intentionally excluded, and the reasons matter:

Setting	How it is passed	Why
End-user identity	`X-End-User-Id` header, or the client’s `end_user_id` argument	One process usually serves many end users; a process-level variable guarantees cross-user bleed
Timeouts	`timeout` constructor argument	Defaults are 300s total, 10s connect; sane timeouts vary enormously per call
Model selection	Request body parameter	It is a per-call decision, not deployment configuration

End-user identity is the one most often misread. It looks “fixed per deployment,” but one API key fronting many users is the normal case — so it has to vary per request, and an environment variable would freeze it. A single-user script can set end_user_id once on the client; a server-side integration passes it per call.

Proxies and networking

The SDK’s internal HTTP client sets trust_env=False explicitly, which means:

HTTP_PROXY / HTTPS_PROXY / ALL_PROXY are not read
NO_PROXY likewise has no effect
System CA bundles and .netrc do not participate

This is the easiest trap to fall into: you have a proxy configured, curl works, requests works, and the SDK still connects directly.It is not a defect. Honouring the environment would break direct file uploads (presigned URLs), where two competing Authorization mechanisms collide — the SDK’s Bearer header makes object storage ignore the query-string signature and return 400. To avoid that near-unattributable failure, the SDK uniformly ignores environment proxies.If you need a proxy, pass a custom HTTP client through the constructor rather than relying on environment variables.

MCP integration

The remote MCP server needs no environment variables at all — only a config file:

.mcp.json

{
  "mcpServers": {
    "profy": {
      "type": "streamable-http",
      "url": "https://mcp.profy.cn/mcp"
    }
  }
}

Authentication reuses your IDE’s existing login session (Bearer token or cookie); no secret travels through the environment. The tool list is in MCP Tools.

Full example

PROFY_API_KEY=sk-pro-xxxxxxxxxxxxxxxx
# Only needed for private deployments or local development
# PROFY_BASE_URL=https://api.example.internal

import os
from profy import Profy

# Three forms, in decreasing order of "leave it to the environment":
# 1) Environment only (simplest, but end-user identity must go per call)
async with Profy() as client:
    await client.agents.run("my-expert", "Hello", end_user_id="user-123")

# 2) Explicit key plus a client-level end user (single-user script)
async with Profy(api_key=os.environ["PROFY_API_KEY"], end_user_id="user-123") as client:
    await client.agents.run("my-expert", "Hello")

# 3) Fully explicit (multi-tenant service, base_url to a private deployment)
async with Profy(
    api_key=os.environ["PROFY_API_KEY"],
    base_url=os.environ.get("PROFY_BASE_URL", "https://api.profy.cn"),
) as client:
    await client.agents.run("my-expert", "Hello", end_user_id=request.user_id)

import os
from profy import ProfyApp

app = ProfyApp()   # reads PROFY_APP_ID / PROFY_APP_SECRET

url = app.authorization_url(
    redirect_uri="https://your.app/callback",
    scope="events:write",
    state=csrf_token,
)

Boundaries and failure modes

Symptom	Cause	Fix
`api_key is required` at construction	`PROFY_API_KEY` unset or misspelled	Check the name and whether the process loaded `.env`
Every request 400 complaining about a header	End-user identity not sent	Set `end_user_id` on the client or pass it per call
Proxy configured but SDK connects directly	SDK sets `trust_env=False`	Pass a custom HTTP client; do not rely on the environment
Private deployment traffic hits the public API	`PROFY_BASE_URL` never applied	Ensure the environment loads before the client is constructed
`ProfyApp` complains about client_id	Only `PROFY_API_KEY` was set	App credentials and API keys are separate; neither substitutes for the other

The fourth row is especially common: many .env loaders inject variables at import time, after a module-level client has already been constructed. Create clients inside a function rather than at module top level.

Verify your configuration

import os
from profy import Profy

print("key set:", bool(os.environ.get("PROFY_API_KEY")))
print("base url:", os.environ.get("PROFY_BASE_URL", "https://api.profy.cn (default)"))

async with Profy(end_user_id="verify-1") as client:
    resp = await client.agents.run("your-expert", "Reply with one word")
    print(resp)

If this runs, your key, base URL, and end-user identity are all correct. Any one of them being wrong surfaces here rather than in production.

Authentication

API keys versus OAuth

Endpoint Reference

Every /v1/* endpoint

Error Codes

Codes returned by configuration errors

MCP Tools

IDE integration

Verified 2026-08-11. Sources: sdk/python/profy/client.py (DEFAULT_BASE_URL, _DEFAULT_TIMEOUT, trust_env=False, _end_user_headers), sdk/python/profy/app.py (PROFY_APP_ID / PROFY_APP_SECRET / DEFAULT_SCOPE), services/core/src/routes/platform-api/caller.ts (end-user header gate).

Get Started

Authentication & Keys

API Guides

SDK

Integrations

Cookbook

Reference

Environment Variables

Environment Variables

SDK configuration

Auth and address

OAuth applications

Deliberately not environment variables

Proxies and networking

MCP integration

Full example

Boundaries and failure modes

Verify your configuration

Authentication

Endpoint Reference

Error Codes

MCP Tools

​Environment Variables

​SDK configuration

​Auth and address

​OAuth applications

​Deliberately not environment variables

​Proxies and networking

​MCP integration

​Full example

​Boundaries and failure modes

​Verify your configuration

​Related pages

Authentication

Endpoint Reference

Error Codes

MCP Tools

Environment Variables

SDK configuration

Auth and address

OAuth applications

Deliberately not environment variables

Proxies and networking

MCP integration

Full example

Boundaries and failure modes

Verify your configuration

Related pages