Skip to main content
When a policy authorizes a request, Parmana releases the action to a connector: the component that performs it in your system. With no connector configured for a capability, an authorized request returns 503 CONNECTOR_NOT_REGISTERED and nothing is executed. A self hosted deployment starts with no connector configured. You add one by giving the api service the connector’s variables.

​
Add the variables

Create a file named docker-compose.override.yml in the repository root. Docker Compose reads it together with docker-compose.yml on every command, so nothing else changes. Example for the Paytm connector, which forwards authorized refunds to your parmana-paytm-agent service:
The ${...:?...} form reads the secret from your shell or from .env, so it is not written into the file, and it stops Compose with a clear message when it is missing:
Apply it:
Keep PAYTM_CONNECTOR_SHARED_SECRET set, or in .env, for every later docker compose command. Every command reads the override file. Check: curl -s http://127.0.0.1:3000/ready returns "status":"READY", and a request the policy authorizes no longer returns CONNECTOR_NOT_REGISTERED. It returns the connector’s result instead.

​
Connector variables

What each variable accepts: Environment variable reference, Connectors. Only the Paytm connector has been run on the self hosted deployment, by the offline check. HubSpot, Slack and GitHub use the same server code as the hosted API but call services on the internet, so a deployment that uses them is not isolated from the internet.

​
Rules the server enforces

  • HTTPS only. PAYTM_CONNECTOR_URL must start with https://. Otherwise the server refuses to start with PAYTM_CONNECTOR_URL must use HTTPS in production; received "...". Refusing to start with a plaintext connection configured to the trusted Paytm connector service.
  • Both or neither. Setting only one of PAYTM_CONNECTOR_URL and PAYTM_CONNECTOR_SHARED_SECRET stops the server at start.
  • Capability on the key. A key can request paytm:refund only if it was added with --allowed-capabilities paytm:refund. See Manage API keys.

​
A connector with a certificate from your own authority

If your connector’s certificate is issued by an internal certificate authority, the server must trust that authority. Mount its certificate into the api container and point NODE_EXTRA_CA_CERTS at it:
Compose adds this mount to the ones in docker-compose.yml; it does not replace them. The certificate is added to the ones Node.js already trusts; it replaces none. The offline check uses exactly this mechanism for its stand in connector.

​
When the connector cannot be reached

The action has already been authorized, and an Execution Intent signed and stored, before the connector is called. If the call then fails:
  • the caller gets 502 with code EXECUTION_OUTCOME_UNKNOWN, and a message naming the businessTransactionId and authorizationId. The connector’s own error is never in the response;
  • the Execution Intent is stored in state ERRORED, with the cause as its failureReason;
  • the API log has a critical execution_outcome_unknown event with the cause, for example getaddrinfo ENOTFOUND paytm-agent.internal.example.com.
Whether the action happened is unknown. Do not resend it under a new businessTransactionId. Check your system, then close the intent with what you found: POST /execution-intents/{id}/resolve. The full procedure is in Troubleshooting. Before 2026-09-25 the caller got a bare 500 Internal Server Error here instead.