Skip to main content
AgentMark Connect is a WebSocket-based bidirectional connection between your local development server and the AgentMark platform. When you run a prompt or experiment in the platform, Connect routes the request to your local machine, executes it using your adapter and models, and streams results back.

​
Quick start

agentmark dev --remote
The CLI handles authentication, app linking, and the WebSocket connection automatically. See the CLI reference for all agentmark dev options.

​
How it works

AgentMark Connect uses a persistent WebSocket connection between your CLI and the platform gateway:
  1. CLI connects — agentmark dev --remote opens a WebSocket to the gateway (wss://api.agentmark.co/v1/connect), authenticated with your dev API key.
  2. Gateway registers — A Durable Object is created for your app, maintaining heartbeat and connection state.
  3. Platform dispatches — When you click Run on a prompt or experiment, the platform sends a job to the gateway.
  4. Local execution — The gateway forwards the job over WebSocket to your CLI. Your local dev server executes it using your adapter (AI SDK, Claude Agent SDK, Mastra, etc.).
  5. Results stream back — Execution results stream back through the WebSocket to the platform in real time.
The connection includes automatic heartbeat monitoring and reconnection with exponential backoff. If the connection drops, the CLI reconnects without manual intervention.

​
Connection status

The AgentMark dashboard shows live connection status on your app’s Settings page:
  • Connected — Your local dev server is connected and ready to receive jobs.
  • Disconnected — No active connection. Start agentmark dev --remote to connect.
  • Error — Connection issue detected. Check CLI output for details.
The status updates in real time as your CLI connects and disconnects.

​
Using the Connect SDK

For custom integrations outside the CLI, use the @agentmark-ai/connect npm package. This is useful if you want to build your own server that connects to the platform.

​
Installation

npm install @agentmark-ai/connect

​
Basic usage

import { createConnectServer } from "@agentmark-ai/connect";

const server = createConnectServer({
  apiKey: process.env.AGENTMARK_API_KEY!,
  appId: process.env.AGENTMARK_APP_ID!,
  handler: async (job) => {
    // job.type is "prompt-run" or "dataset-run"
    // job.data contains the prompt AST and options
    // Return a JobResult or JobStreamResult
    return {
      type: "text",
      result: "Hello from my custom server!",
      traceId: crypto.randomUUID(),
    };
  },
  onConnected: () => {
    console.log("Connected to AgentMark platform");
  },
  onDisconnected: (reason) => {
    console.log("Disconnected:", reason);
  },
  onError: (error) => {
    console.error("Connection error:", error);
  },
});

// Start the WebSocket connection
server.start();

// Check connection status at any time
console.log(server.getStatus());

// Gracefully disconnect
// server.stop();

​
createConnectServer options

  • apiKey (string, required): Your AgentMark API key for authentication.
  • appId (string, required): The app ID to connect to.
  • handler (function, required): Async function called for each incoming job. Receives the job payload and returns the result.
  • url (string, optional): WebSocket gateway URL. Default: wss://api.agentmark.co/v1/connect.
  • onConnected (function, optional): Callback when the WebSocket connection is established.
  • onDisconnected (function, optional): Callback when the connection is lost. Receives an optional reason string.
  • onError (function, optional): Callback when a connection error occurs.
  • heartbeatIntervalMs (number, optional): Interval for heartbeat pings in milliseconds.
  • reconnectMaxDelayMs (number, optional): Maximum delay between reconnection attempts.
  • language (string, optional): Language identifier sent to the platform (e.g., "typescript" or "python").

​
Troubleshooting

​
”Authentication failed”

The CLI could not authenticate with the platform. Run agentmark login to re-authenticate, or pass --api-key directly.

​
”WebSocket connection refused”

The gateway could not be reached. Check your network connection and ensure wss://api.agentmark.co is not blocked by a firewall or proxy.

​
”App not linked”

Your project is not linked to a platform app. Run agentmark link to select an app, or pass --app-id directly.

​
Connection keeps dropping

Intermittent disconnections are normal and handled automatically via reconnection with exponential backoff. If the connection drops frequently, check your network stability. The CLI logs reconnection attempts to your terminal.

​
Platform shows “Disconnected” but CLI is running

Ensure --remote is passed to agentmark dev. Without it, the dev server runs in local-only mode without a platform connection. Also verify that no other CLI instance is connected to the same app — only one connection per app is supported.

​
Have Questions?

We’re here to help! Choose the best way to reach us: