Connecting Your Application

After creating an instance in the admin console at app.flexivity.ai , you need to establish a connection between your helpdesk application and Flexivity AI. There are two approaches depending on your deployment:

• Agent Setup — For applications behind a firewall or on private networks
• Connecting Directly — For internet-accessible applications

Agent Setup

Use the agent when your helpdesk application is behind a firewall or not directly accessible from the internet. The Flexivity AI agent runs as a Docker container alongside your application and establishes a secure outbound WebSocket tunnel to the Flexivity AI cloud.

Prerequisites

• Docker and Docker Compose installed on the server hosting your helpdesk application
• Outbound network access on port 443 (WSS and HTTPS)
• The Instance ID and Connection Token from the admin console (shown when you create the instance)

Step 1: Download the Docker Compose Configuration

From the instance detail page in the admin console at app.flexivity.ai , open the onboarding wizard. The wizard provides a pre-configured docker-compose.yml file with your instance credentials already filled in.

Download the file and place it on the server hosting your helpdesk application.

Step 2: Start the Agent

On your server, navigate to the directory containing the docker-compose.yml file and start the agent:

docker compose up -d

The agent will start, connect to the Flexivity AI cloud via a secure WebSocket tunnel, and begin relaying events between your application and the AI processing pipeline.

Step 3: Verify Connectivity

Return to the admin console at app.flexivity.ai  and check your instance:

1. Navigate to Instances and click your instance
2. The status should change from Pending to Active
3. The Last heartbeat timestamp should update within a minute
4. The Application Information section should populate with your application’s version details

Network Requirements

The agent requires the following outbound network access from the server:

• WSS (port 443) to the Flexivity AI cloud endpoint — for the WebSocket tunnel that carries events and commands
• HTTPS (port 443) to app.flexivity.ai — for API calls and health checks

No inbound ports need to be opened. All communication is initiated outbound by the agent.

Auto-Updates

The agent container supports automatic updates. By default, new instances use the Stable update channel, which receives updates after they have been tested. You can change the update channel in the instance settings. See Instances for details on update channels.

Stopping and Restarting the Agent

To stop the agent:

docker compose down

To restart it:

docker compose up -d

The agent will automatically reconnect to the Flexivity AI cloud after a restart. Your instance status in the admin console will briefly show as Disconnected during the restart and return to Active once the connection is re-established.

Troubleshooting

If the agent does not connect or the instance stays in Pending status, see the Troubleshooting guide for common issues and resolutions.

Connecting Directly

Use a direct connection when your helpdesk application is accessible from the internet and does not require an agent. In this mode, the Flexivity AI cloud connects to your application’s plugin API directly.

Step 1: Test Connection

From the instance detail page in the admin console at app.flexivity.ai :

1. Click Test Connection
2. The admin console will attempt to reach your application’s plugin API endpoint
3. If the connection succeeds, you will see a confirmation with the detected application version

Step 2: Verify Heartbeat

After a successful connection test:

1. Check that the Last heartbeat timestamp on the instance detail page is updating regularly
2. The instance status should show as Active

Step 3: Verify Application Details

Confirm that the Application Information section on the instance detail page is populated with:

• Plugin version
• Application version
• Schema version

If any of these fields are empty or the heartbeat is not updating, verify that your application’s firewall allows inbound HTTPS connections from the Flexivity AI cloud and that the plugin is properly installed and activated.