Private Connection

Overview

A Private Connection lets your AI agent call functions that run inside your own infrastructure — on-premise servers, private VPCs, local development machines, or any environment not directly reachable from the internet. It works like a reverse tunnel: your service polls Rapidfolio for invocations and executes them locally, so you never need to open a firewall port or expose a public endpoint.

This is the recommended approach for:

• Calling internal databases or services that cannot be publicly exposed
• Running proprietary business logic that must stay on-premise
• Integrating with legacy systems behind a corporate firewall
• Local development and testing of procedure handlers

---

How It Works

1. You create a Private Connection in the Rapidfolio dashboard. Rapidfolio generates a connection token.
2. You run the Connection SDK in your infrastructure, providing the token.
3. The SDK establishes an outbound polling loop to Rapidfolio's servers. No inbound connections are required.
4. When your procedure reaches a Tool Call node that targets this connection, Rapidfolio queues the invocation.
5. The SDK picks up the invocation, runs your registered handler function locally, and returns the result to Rapidfolio.
6. The procedure continues with the handler's return value.

---

Setup

Step 1 — Create the Connection in Rapidfolio

1. Go to Dashboard → Connections and click New Connection.
2. Select Private Connection.
3. Give the connection a name (e.g., Internal Risk Engine) and select the environment (Sandbox or Live).
4. Click Create.
5. Copy the generated connection token — it is shown once at creation. Store it securely.

Tokens are prefixed to indicate environment:

Prefix	Environment
run_sandbox_	Sandbox
run_live_	Live

You can regenerate a token at any time from the connection's settings page. The old token is immediately invalidated.

Step 2 — Install the SDK

npm install @rapidfolio/connection-sdk-node

Step 3 — Register Functions and Start

import { Connection } from '@rapidfolio/connection-sdk-node'
import { z } from 'zod'

const conn = new Connection()
// Reads RAPID_TOKEN environment variable automatically

conn
  .register('getCustomerRisk', {
    description: 'Score a customer\'s risk profile from the internal risk engine',
    input: z.object({
      customerId: z.string().describe('The customer ID to score')
    }),
    handler: async ({ customerId }) => {
      const score = await internalRiskEngine.score(customerId)
      return { score, tier: score > 700 ? 'low' : 'high' }
    }
  })
  .register('lookupAccount', {
    description: 'Look up an account by account number from the core banking system',
    input: z.object({
      accountNumber: z.string().describe('The account number to look up')
    }),
    handler: async ({ accountNumber }) => {
      return legacyDb.query(
        'SELECT * FROM accounts WHERE account_number = ?',
        [accountNumber]
      )
    }
  })

await conn.start()
console.log('Private connection active')

Set the token via environment variable:

RAPID_TOKEN=run_sandbox_xxxxxxxxxxxx node server.js

Step 4 — Use in a Procedure

In the procedure editor, add a Tool Call node. Select your Private Connection and choose one of the function names you registered (e.g., getCustomerRisk). The node will pass parameters to your handler and receive the return value as its output.

---

Token Security

• Store the connection token in a secrets manager or environment variable — never hard-code it in source code.
• The token is the only credential required. Anyone who holds it can invoke your handlers, so treat it like a private API key.
• Rotate the token from the dashboard if you suspect it has been compromised. The old token is immediately invalidated and the SDK will stop receiving invocations until restarted with the new token.

---

Local Development (No Token)

Use conn.connectLocal() to run handlers in-process without connecting to Rapidfolio. No token required — useful for unit tests and local development:

import { Connection } from '@rapidfolio/connection-sdk-node'
import { z } from 'zod'

const conn = new Connection()

conn.register('getCustomerRisk', {
  description: 'Score a customer risk profile',
  input: z.object({ customerId: z.string() }),
  handler: async ({ customerId }) => ({ score: 750, tier: 'low' })
})

const local = conn.connectLocal({ environment: 'sandbox' })

const result = await local.invoke('getCustomerRisk', { customerId: 'cust_123' })
// result => { score: 750, tier: 'low' }

connectLocal() never makes any HTTP requests and does not require a token, making it safe and fast for unit tests.

---

Error Handling

Throw an error in your handler to return a failure response to the procedure. The procedure will treat it as a failed tool call and follow your procedure's error handling path.

conn.register('getCustomerRisk', {
  description: 'Score a customer risk profile',
  input: z.object({ customerId: z.string() }),
  handler: async ({ customerId }) => {
    const customer = await db.customers.findById(customerId)
    if (!customer) {
      throw new Error(`Customer ${customerId} not found`)
    }
    return { score: customer.riskScore }
  }
})

---

Notes

• Private Connections do not support triggers — they are invoked by procedure Tool Call nodes only.
• The SDK uses long-polling. There is no persistent WebSocket — the SDK makes outbound HTTP requests to Rapidfolio, so standard firewall outbound rules apply.
• See the full Connection SDK documentation for advanced configuration, error handling, and TypeScript type definitions.