Skip to main content
This is the exhaustive lookup — every variable Activepieces reads, grouped by concern, with its default. For how to apply them to a production deployment, see Configure & Operate.
When you run tools/deploy.sh from the Docker installation tutorial, it generates a root .env file pre-filled with these values.
Variables marked ❗ are required for a self-hosted production deployment.

Core

URLs, encryption keys, telemetry.

Database

Postgres / PGLite connection and pooling.

Redis & queue

Standalone, Sentinel, and the queue UI.

Execution & sandboxing

Run mode, memory, concurrency, network egress.

Limits & retention

File, log, webhook, and table limits.

File storage (S3)

Object storage for files and logs.

Email (SMTP)

Outbound mail configuration.

Authentication & SSO

Google sign-in, SCIM, cloud OAuth.

Pieces & flows

Piece syncing, polling, publish behavior.

Tool search

Semantic action discovery for AI agents.

Core

Identity and connectivity for the platform: the public URL, the keys that protect connections and tokens, and telemetry.
AP_FRONTEND_URL is essential for webhooks and app triggers. It must be accessible to third parties so they can send data.
The default URL is the machine’s IP address. If that address isn’t reachable from the internet, set AP_FRONTEND_URL explicitly. For local development you can expose the frontend port (4200) with a tunneling service such as ngrok.

Serving MCP from its own hostname

Set AP_MCP_URL when you want MCP traffic separated from the main app — to apply distinct WAF rules, to observe it independently, or because your MCP clients live on the internet while Activepieces itself does not. Discovery, the WWW-Authenticate challenge and the token endpoint then advertise that hostname instead of AP_FRONTEND_URL. AP_MCP_URL must use its own hostname. Activepieces refuses to start when it shares a hostname with AP_FRONTEND_URL but is not the same URL, because requests on that hostname could not be told apart. For example:
MCP clients then connect to https://mcp.example.com/mcp for a project, or https://mcp.example.com/mcp/platform for the whole platform. The MCP settings pages show these URLs. Routes on the MCP hostname. Forward these paths to Activepieces without rewriting them. It does not need to serve the web app or /api.
  • /mcp and /mcp/platform — match them exactly. A prefix rule for /mcp also matches /mcp-authorize, which this hostname cannot serve.
  • /authorize, /token, /register, /revoke, /userinfo
  • /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource/*, /.well-known/openid-configuration, /.well-known/jwks.json
Routes on the main hostname. The consent screen opens at /mcp-authorize at the root of the AP_FRONTEND_URL hostname, even when AP_FRONTEND_URL has a path prefix. Route it the same way as the SAML sign-in return (/authenticate), /api and the web app’s assets, which the browser already loads from the root. Keep the public hostname. Activepieces recognises an MCP request by its hostname, so your proxy must pass mcp.example.com through — in X-Forwarded-Host, or in an unchanged Host header. If the proxy replaces it with an upstream name, discovery falls back to the main app’s URLs and the connection fails. Activepieces logs a warning when /authorize receives a request for a hostname that matches neither setting.
The two hostnames are reached by two different parties, and both must work. The MCP client — often a cloud service — only ever talks to AP_MCP_URL, so that hostname is the one that has to be publicly reachable. The user’s browser is sent to AP_FRONTEND_URL to sign in and approve the connection, so whoever authorizes a client must be able to reach the main host at that moment. If your main host is restricted — to a VPN, an IP allow-list, or an internal network — then only users inside that boundary can authorize an MCP client. Everything after approval is client-to-AP_MCP_URL and works from anywhere.Single sign-on keeps working unchanged: the browser signs in on the main host. Your identity provider must keep posting SAML assertions to the ACS URL shown in Activepieces (AP_FRONTEND_URL followed by /api/v1/authn/saml/acs), not to AP_MCP_URL or AP_INTERNAL_URL. You do not need a second ACS URL.
AP_MCP_URL may carry a path prefix, for example https://gateway.example.com/activepieces. Your proxy must then strip that prefix before forwarding, and clients connect to https://gateway.example.com/activepieces/mcp. Setting AP_MCP_URL also changes the mcpServerUrl returned to embedded clients by the project MCP token endpoint.

Database

Activepieces stores its data in PostgreSQL (recommended for production) or an embedded PGLite database. Set the connection with discrete fields or a single AP_POSTGRES_URL.

Redis & queue

Redis backs the BullMQ job queue. Connect with discrete fields, a single AP_REDIS_URL, or Sentinel. The queue UI is an optional dashboard for inspecting jobs.
If AP_REDIS_URL is set, all other Redis properties are ignored. The same applies to AP_REDIS_SENTINEL_HOSTS when running in Sentinel mode.

Execution & sandboxing

Controls how flows run: the sandbox mode, per-process memory and concurrency, run timeouts, and the network egress posture for user code. Read Sandboxing before changing AP_EXECUTION_MODE.

Limits & retention

Caps on file sizes, run-log size, webhook payloads, table sizes, and how long run data is kept. The Cloud values and how these interact are covered in Limits.

File storage (S3)

Files emitted by steps and triggers are stored in the database or an S3-compatible bucket.

Sign-up protection

Controls on who may create an account. Both are off with no configuration, so a self-hosted instance needs neither a Cloudflare nor a ZeroBounce account. With AP_ZEROBOUNCE_API_KEY set, a sign-up is refused when ZeroBounce reports the address as disposable, toxic, a spam trap, an abuse address or globally suppressed, or reports that its domain cannot receive mail at all: no DNS records, a send-only domain, or a mail server at an unroutable address. Role addresses such as info@ and sales@ are accepted, and so is an address whose mailbox ZeroBounce cannot confirm. A member who already holds an accepted invitation is never refused. One credit is spent per address, and only for an address that has no account yet. If ZeroBounce cannot be reached, or answers that the key is invalid or out of credits, the sign-up is allowed through and the reason is logged — a validation outage never blocks sign-up. The check covers the two public doors — password sign-up and Sign in with Google — and skips accounts a platform provisions itself through SSO (SAML) or embedding (managed authentication), since those are vouched for by the platform. A Google sign-up costs a credit only the first time an address is seen. A refused Google sign-up answers exactly like a failed Google token exchange (INVALID_CREDENTIALS) and the page shows a generic “Sign-in failed”, so the response never says why; as on the email path, the server log is the only record. ZeroBounce resolves DNS from the public internet. If your members’ mail domains are only resolvable inside your own network, leave the key unset. Both refusals are silent: the emailed-code request answers exactly as a served one does and the sign-in page moves to the code step, while password sign-up returns the same response an unverified sign-up returns. Neither reveals that the address was refused; the server log is the only record. The challenge is only served when both Turnstile variables are set. With either missing, the sign-in page renders no widget and the server verifies nothing, so a self-hosted instance needs no Cloudflare account. Signing in with an emailed code depends on that pair. It is served on Activepieces Cloud only, and there only when both variables are set — without them the endpoints are not registered and the sign-in card opens on the password form.

Email (SMTP)

Outbound mail for invitations, notifications, and password resets. SMTP can be configured from the platform admin screen or through these variables. The environment variables are used only when the admin screen has no email configuration, and only when AP_SMTP_HOST, AP_SMTP_PORT, AP_SMTP_USERNAME, and AP_SMTP_PASSWORD are all set. TLS is supported.

Authentication & SSO

Sign-in providers and SCIM provisioning.

Pieces & flows

How piece metadata is synced, how often scheduled triggers poll, and flow-authoring defaults.
Semantic discovery of piece actions and triggers for AI agents connected through the MCP server. See Tool Search for how it works.