Connect to the Viam cloud

Open a connection to the Viam cloud to access the fleet, data, ML training, billing, and provisioning APIs, and to enumerate and connect to multiple machines from one app. For connecting directly to a single known machine, use Connect to a machine instead.

When to connect to the cloud

Use the cloud connection when your app needs any of these:

• Multiple machines. Your app lets users pick from a fleet, shows status across many devices, or connects to different machines based on user input.
• Machine discovery. Your app does not know the machine address ahead of time and needs to list machines from an organization or location.
• Captured data queries. Your app queries sensor or binary data with SQL or MQL (see Query captured data).
• Fleet management. Your app creates or manages machines, API keys, locations, or fragments programmatically.
• Custom provisioning. Your app onboards new machines through the provisioning service (see Provision devices).
• Billing or ML training. Your app reads billing information or launches ML training jobs.

If your app only talks to one machine whose address you already know, skip this page and use Connect to a machine directly.

Prerequisites

• A project set up with the Viam SDK (see App scaffolding)
• An API key scoped to the organization or location your app needs to access, and its API key ID. Create an API key in Admin and access.

Open a cloud connection

import * as VIAM from "@viamrobotics/sdk";

const client = await VIAM.createViamClient({
  credentials: {
    type: "api-key",
    authEntity: "<API-KEY-ID>",
    payload: "<API-KEY>",
  },
});

import 'package:viam_sdk/viam_sdk.dart';

final viam = await Viam.withApiKey(
  'your-api-key-id',
  'your-api-key-secret',
);

from viam.app.viam_client import ViamClient
from viam.rpc.dial import DialOptions


async def connect():
    dial_options = DialOptions.with_api_key(
        api_key='your-api-key-secret',
        api_key_id='your-api-key-id'
    )
    return await ViamClient.create_from_dial_options(dial_options)


client = await connect()

import (
    "context"
    "go.viam.com/rdk/app"
    "go.viam.com/rdk/logging"
)

logger := logging.NewDebugLogger("client")
client, err := app.CreateViamClientWithAPIKey(
    context.Background(),
    app.Options{},
    "your-api-key-secret",
    "your-api-key-id",
    logger,
)
if err != nil {
    logger.Fatal(err)
}

Unlike RobotClient, the cloud client does not hold a persistent WebRTC connection. Each method call is a separate request to the Viam cloud. There is no close() or disconnect() method to call when you are done.

Enumerate machines

Common pattern: list the organizations a user can access, then list machines in a selected organization.

const orgs = await client.appClient.listOrganizations();
console.log(`Found ${orgs.length} organizations`);

const orgId = orgs[0].id;
const summaries = await client.appClient.listMachineSummaries(orgId);
for (const location of summaries) {
  console.log(`Location: ${location.locationName}`);
  for (const machine of location.machines) {
    console.log(`  ${machine.machineName} (${machine.machineId})`);
  }
}

final orgs = await viam.appClient.listOrganizations();
print('Found ${orgs.length} organizations');

final orgId = orgs.first.id;
final locations = await viam.appClient.listLocations(orgId);

for (final location in locations) {
  print('Location: ${location.name}');
  final robots = await viam.appClient.listRobots(location.id);
  for (final robot in robots) {
    print('  ${robot.name} (${robot.id})');
  }
}

See the fleet API reference for the full method list on AppClient.

Connect to a machine from the cloud client

Once you have identified a machine, open a RobotClient connection to it.

const machine = await client.connectToMachine({
  id: "abc-123-def-456",
});

final locations = await viam.appClient.listLocations(orgId);
final location = locations.first;
final robots = await viam.appClient.listRobots(location.id);
final robot = robots.first;

final robotClient = await viam.getRobotClient(robot);

Close the RobotClient when your app is done with the machine. See Connect to a machine for the close pattern and for error handling.

Handle errors

API key errors, network failures, and missing permissions all raise errors from createViamClient or Viam.withApiKey. Wrap the call in a try-catch the same way you would for a machine connection. The cloud client does not distinguish credential errors from network errors in its error messages; log the error verbatim when debugging.

If a subsequent appClient or dataClient call fails because the API key does not have permission for the target resource, the SDK throws an error from that specific call, not from the initial createViamClient. Check errors on every cloud method call that accesses resources across organizations or locations.

Next

• Query captured data for using dataClient to read sensor and binary data
• Handle disconnection and reconnection for reconnection behavior on the RobotClient instances you get from the cloud connection
• Provision devices for custom provisioning apps that use provisioningClient
• Fleet API reference for the full AppClient method list
• Data API reference for the full DataClient method list