Providers and secrets

Environment variable reference

Configure Agent Studio database, authentication, AI, integration, vault, A2A, logging, and optional service settings.

Use this reference to prepare the environment for Agent Studio and the services used by your workflows. Start from .env.example, copy it to .env.local, and replace example credentials before running the application.

⚠️Never commit .env.local, provider keys, tokens, or vault key material. The values below are examples or placeholders, not credentials for a shared environment.

Validation behavior

Agent Studio validates the core application variables at startup. In a production server process, an invalid core value is reported as a fatal configuration error and the process exits. In development and test environments, Agent Studio reports a configuration warning and uses its documented development fallbacks where available.

The optional-service variables in .env.example are fallback connection values for graph nodes. You only need the services used by your workflows, and an individual graph node can supply its own service URL instead.

Database and runtime

Variable	Type and values	Default or example	Requirement and effect
`DATABASE_URL`	URL or string beginning with `postgresql://`	Example: `postgresql://agent:secret@localhost:5432/agentstudio`; development fallback: `postgresql://postgres:postgres@localhost:5432/agent_studio?schema=public`	Required by the schema. Connects Agent Studio to PostgreSQL. Replace the example password.
`NODE_ENV`	`development`, `test`, or `production`	`development`	Selects the runtime environment. Production rejects invalid core configuration instead of continuing with development fallbacks.
`NEXT_PUBLIC_APP_URL`	URL	`http://localhost:3000`	Sets the public application URL. Use the externally reachable HTTPS URL in production.
`LOG_LEVEL`	`fatal`, `error`, `warn`, `info`, `debug`, or `trace`	`info`	Sets the logging threshold.

Authentication

Variable	Type	Default	Requirement and effect
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	String	None	Optional in the schema. Supplies the public Clerk key to the client.
`CLERK_SECRET_KEY`	String	None	Optional in the schema. Supplies the server-side Clerk credential. Keep it secret.
`NEXTAUTH_SECRET`	Non-empty string	Development fallback: `dev-only-secret-not-for-production`	Required by the schema and must be explicitly set in production. Use independently generated secret material; never use the development fallback outside local development.

AI providers

At least one active provider key is needed for AI execution. The example configuration identifies Groq and OpenRouter as the supported provider choices for this purpose.

Variable	Type	Default	Requirement and effect
`GROQ_API_KEY`	String	None	Optional configuration value. Enables Groq-backed AI operations and the OpenAI-compatible embeddings endpoint described by the example configuration.
`OPENROUTER_API_KEY`	String	None	Optional configuration value. Enables OpenRouter and acts as the documented embedding fallback when Groq is unavailable.
`OPENAI_API_KEY`	String	None	Compatibility-only. The variable remains accepted, but setting it does not enable OpenAI embeddings.

MCP and registries

Model Context Protocol (MCP) clients and public integration catalogs use these settings.

Variable	Type	Default	Requirement and effect
`MCP_ACCESS_TOKEN`	String	None	Optional bearer token for external clients connecting to `/api/mcp/sse`. When absent, only Clerk-authenticated sessions can connect.
`COMPOSIO_API_KEY`	String	None	Optional key for the Composio catalog.
`ARCADE_API_KEY`	String	None	Optional key for Arcade-managed integrations.
`SMITHERY_API_KEY`	String	None	Optional key for hosted Smithery SSE servers. This variable appears in `.env.example` but is not part of the core validation schema.
`GITHUB_TOKEN`	String	None	Optional personal access token for repository and catalog discovery. The example configuration records a higher GitHub API allowance when it is set.

See Manage MCP servers to configure individual server connections and Discover MCP services to use the catalogs.

Vault encryption

Variable	Type	Default	Requirement and effect
`VAULT_MASTER_KEY`	64-character hexadecimal string representing 32 bytes	None	Required for production according to `.env.example`. Encrypts vault entries; treat it as key material.
`VAULT_KEY_VERSIONS`	Comma-separated version identifiers	`1`	Lists active key versions. Include new versions after key rotation.

Generate vault key material with the repository-provided command shown in .env.example:

bash

npx tsx scripts/vault-rotate-keys.ts --generate-key

Keep the generated value outside source control. For day-to-day secret administration, see Manage encrypted secrets.

A2A registry

Variable	Type	Default	Requirement and effect
`A2A_REGISTRY_URL`	URL	None	Optional upstream Agent-to-Agent (A2A) registry. Discovery and auction participants request manifests from it before falling back to built-in presets. The endpoint must return JSON shaped as `{ "agents": [AgentManifest, ...] }`.
`A2A_REGISTRY_TOKEN`	String	None	Optional credential sent to the configured A2A registry. Keep it secret.

See Discover A2A agents for the discovery workflow.

Optional workflow services

These values provide default service locations for compatible graph nodes. Configure only the services you run.

Variable	Type	Example default	Effect
`SEARXNG_HOST`	URL	`http://localhost:8080`	Default SearXNG metasearch endpoint.
`CRAWL4AI_HOST`	URL	`http://localhost:11235`	Default Crawl4AI web-scraping endpoint.
`DOCLING_HOST`	URL	`http://localhost:5001`	Default Docling document-parser endpoint.
`GOTENBERG_HOST`	URL	`http://localhost:3000`	Default Gotenberg PDF endpoint.
`NOCODB_HOST`	URL	`http://localhost:8085`	Default NocoDB endpoint.
`NOCODB_API_TOKEN`	String	None	Optional NocoDB API token. Create it in NocoDB under Team & Settings → API Tokens.
`POCKETBASE_HOST`	URL	`http://localhost:8090`	Default PocketBase endpoint.
`QDRANT_HOST`	URL	`http://localhost:6333`	Default Qdrant vector-database endpoint.
`QDRANT_API_KEY`	String	None	Optional Qdrant credential, needed only when the Qdrant server enables `QDRANT__SERVICE__API_KEY`.
`WHISPER_HOST`	URL	`http://localhost:8000`	Default Faster-Whisper speech-to-text endpoint.
`PIPER_TTS_HOST`	URL	`http://localhost:5000`	Default Piper text-to-speech endpoint.

📝The default host values use local HTTP endpoints. Replace them with the correct network-reachable URLs when Agent Studio and a service do not share the same host.

Example configuration

This minimal development example connects PostgreSQL, configures Clerk, enables Groq, and keeps the default application URL and logging level:

dotenv

DATABASE_URL=postgresql://agent:replace-me@localhost:5432/agentstudio
NODE_ENV=development
NEXT_PUBLIC_APP_URL=http://localhost:3000
LOG_LEVEL=info

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_example
CLERK_SECRET_KEY=sk_test_example
NEXTAUTH_SECRET=replace-with-generated-secret

GROQ_API_KEY=gsk_example
VAULT_KEY_VERSIONS=1

After setting the environment, continue with Configure LLM providers and themes or review Run Agent Studio in production before preparing a production environment.