Configuration

Introduction

The server reads its settings from the env object you pass to PilotooModule.forRoot, usually process.env. Nothing is required except a database and a model key. This page lists the variables you will touch first; the rest are documented next to the feature they control.

PilotooModule.forRoot({ env: process.env });

Database and port

Variable	Purpose
DATABASE_URL	The PostgreSQL connection string. Required unless you supply every persistence port yourself. The server creates its tables on first boot.
API_PORT	The port the demo server in apps/api listens on (then PORT, then 4317). Your own main.ts chooses its port.
API_HOST	The interface the demo server binds to. Default 0.0.0.0.
SERVICE_NAME	The name /health reports. Default api.

Model providers

An agent runs on a profile, and a profile names a provider. A provider is either a file in .pilotoo/providers/ or one the environment configures by name.

Variable	Purpose
AI_DEEPSEEK_API_KEY	Configures the deepseek provider. AI_DEEPSEEK_BASE_URL overrides its endpoint.
OPENAI_API_KEY	Configures the openai provider. OPENAI_BASE_URL overrides its endpoint.
ANTHROPIC_API_KEY	Configures the anthropic provider. ANTHROPIC_BASE_URL overrides its endpoint.
ANTHROPIC_BEDROCK_REGION	Configures anthropic-bedrock. AWS_BEARER_TOKEN_BEDROCK supplies its key.
Your own variable	A provider file names the variable that holds its key in apiKeyEnv, for example DEEPSEEK_API_KEY.

Note

A key never goes in a YAML file. The file holds the name of the variable, and the server reads the value from its environment.

Agents and files

Variable	Purpose
AGENT_DEFAULT_ID	The agent a new conversation starts on.
PILOTOO_CONFIG_DIR	The folder with agents/, profiles/, providers/ and templates/. Default: .pilotoo/ at the repository root.
AGENT_SKILLS_DIR	The folder of system skills. Default: skills/ at the repository root.
AGENT_WORKSPACE_DIR	The folder agents use as their working area. Default: .workspace/ at the repository root.

Caution

When these variables are unset, the kit looks for the folders by walking up from its own files. That works in the repository and breaks once the packages sit under node_modules. When you install the kit into your own project, set PILOTOO_CONFIG_DIR, AGENT_SKILLS_DIR and AGENT_WORKSPACE_DIR to folders in your package.

Identity

Variable	Purpose
AUTH_IDENTITY_URL	A URL the server calls with the caller’s credentials to learn who they are. Unset, every caller is { subject: 'local', tenant: 'local', roles: ['owner'] }.
AUTH_IDENTITY_TIMEOUT_MS	How long to wait for that URL.

See Authentication for the response the URL must return and for writing your own resolver.

Roles

Several features are off until you name the roles allowed to use them. Each variable is a comma-separated list; unset or empty means nobody.

Variable	Grants
AGENT_MANAGER_ROLES	Creating, editing and deleting tenant agents.
USAGE_ADMIN_ROLES	Reading the whole tenant’s usage.
SCHEDULE_ROLES	Scheduling runs as oneself.
SCHEDULE_ADMIN_ROLES	Reading and changing every schedule of the tenant.
MODEL_GATEWAY_ROLES	Using the model gateway. Unset, the gateway answers 404.

Other

Variable	Purpose
TAVILY_API_KEY	Enables the web search tool.
USAGE_PRICES_FILE	A JSON price list; with it /usage reports costs, without it tokens only.
AGENT_GLOBAL_SKILLS_DIR, AGENT_TENANT_SKILLS_DIR	Two extra skill layers; see Skills.
ATTACHMENTS_S3_BUCKET and friends	Store attachments in S3; see Attachments.

Next steps

• Directory structure
• Deployment
• Models