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.
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
SetAP_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:
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.
/mcpand/mcp/platform— match them exactly. A prefix rule for/mcpalso 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
/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.
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 singleAP_POSTGRES_URL.
Redis & queue
Redis backs the BullMQ job queue. Connect with discrete fields, a singleAP_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 changingAP_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.