Skip to main content
Connect BCTRL to your local machine or any computer you own. Install the BCTRL agent and control it from anywhere using the same APIs.

​
Prerequisites

1

Download the BCTRL Desktop Agent

Download the agent for your operating system:

Windows

Windows 10/11

macOS

macOS 12+

Linux

Ubuntu, Debian, Fedora
2

Install and run the agent

Run the installer and follow the setup wizard. The agent will start automatically and run in the system tray.
3

Register your device

Open the agent and enter your API key to register the device with your BCTRL account:
# Or register via command line
bctrl-agent register --api-key YOUR_API_KEY
Your device will appear in your BCTRL Dashboard.

​
Quick Start

Once the agent is installed and registered, connect to your local machine: 
import { bctrl } from '@bctrl/sdk';

// Connect to your local machine
const desktop = await bctrl.desktop.connect({
  target: 'local',
  apiKey: process.env.BCTRL_API_KEY
});

// Take a screenshot of your desktop
await desktop.screenshot({ path: 'my-desktop.png' });

// Use AI to control your computer
await desktop.cua.run('Open Slack and send a message to #general saying "Hello team!"');

// Or use direct control
await desktop.mouse.move(100, 200);
await desktop.keyboard.type('Hello from BCTRL!');

await desktop.close();

​
Connecting to Specific Devices

If you have multiple devices registered, connect by device ID or name: 
const desktop = await bctrl.desktop.connect({
  target: 'device',
  deviceId: 'dev_abc123xyz',
  apiKey: process.env.BCTRL_API_KEY
});
List your registered devices: 
import { bctrl } from '@bctrl/sdk';

const devices = await bctrl.devices.list({
  apiKey: process.env.BCTRL_API_KEY
});

console.log('Registered devices:', devices);
// [
//   { id: 'dev_abc123', name: 'work-laptop', os: 'windows', status: 'online' },
//   { id: 'dev_xyz789', name: 'home-desktop', os: 'linux', status: 'offline' }
// ]

​
Features

Use your actual computer with its installed software, files, and configurations. Perfect for:
  • Automating proprietary software you can’t install elsewhere
  • Working with local files and documents
  • Testing on your specific hardware setup
// Access local files and software
await desktop.cua.run('Open my Documents folder');
await desktop.cua.run('Open the quarterly_report.xlsx file in Excel');
await desktop.cua.run('Update the Q4 numbers and save');
When running locally, operations execute directly on your machine without round-trips to the cloud:
// Connect locally for fastest performance
const desktop = await bctrl.desktop.connect({
  target: 'local',
  mode: 'direct'  // Direct local connection (lowest latency)
});

// Operations run directly on your machine
await desktop.keyboard.type('Fast local typing!');
Use the exact same API whether you’re controlling a cloud computer or your local machine:
// This code works identically for cloud and local
async function automateDesktop(desktop) {
  await desktop.cua.run('Open the browser');
  await desktop.screenshot({ path: 'screen.png' });
  await desktop.keyboard.hotkey('ctrl', 'c');
}

// Run on cloud
const cloudDesktop = await bctrl.desktop.connect({ os: 'windows' });
await automateDesktop(cloudDesktop);

// Run on local - same code!
const localDesktop = await bctrl.desktop.connect({ target: 'local' });
await automateDesktop(localDesktop);
The agent creates a secure, encrypted tunnel to BCTRL servers. Your computer is never directly exposed to the internet:
  • End-to-end encryption for all commands
  • No open ports required on your machine
  • Works behind firewalls and NAT
  • You control when the agent is running

​
Configuration Options

const desktop = await bctrl.desktop.connect({
  // Required
  apiKey: process.env.BCTRL_API_KEY,

  // Target selection
  target: 'local',              // 'local' | 'device'
  deviceId: 'dev_abc123',       // Specific device ID
  deviceName: 'my-laptop',      // Or device name

  // Connection mode
  mode: 'direct',               // 'direct' | 'tunnel' (default: 'tunnel')

  // Session
  timeoutMinutes: 60            // Default: 30
});

​
Agent Configuration

Configure the desktop agent via the system tray icon or command line: 
# Check agent status
bctrl-agent status

# View registered API key
bctrl-agent config

# Update API key
bctrl-agent register --api-key NEW_API_KEY

# Set device name
bctrl-agent config --name "my-work-laptop"

# Start/stop agent
bctrl-agent start
bctrl-agent stop

​
When to Use Local Desktop

Automating your own computer

Run automations on your personal or work machine without needing cloud resources

Hybrid cloud/local workflows

Start a task in the cloud and finish it on your local machine, or vice versa

Testing on specific hardware

Test applications on your exact hardware configuration

Privacy-sensitive automation

Keep sensitive data on your own machine while still using BCTRL APIs

​
Full Example

import { bctrl } from '@bctrl/sdk';

async function organizeLocalDesktop() {
  const desktop = await bctrl.desktop.connect({
    target: 'local',
    apiKey: process.env.BCTRL_API_KEY
  });

  try {
    // Clean up downloads folder
    await desktop.cua.run(`
      1. Open the Downloads folder
      2. Sort files by date modified
      3. Move all files older than 30 days to a folder called "Archive"
      4. Create the Archive folder if it doesn't exist
    `);

    // Organize desktop icons
    await desktop.cua.run(`
      1. Right-click on the desktop
      2. Select "View" then "Auto arrange icons"
    `);

    // Take a screenshot of the result
    await desktop.screenshot({ path: 'organized-desktop.png' });

    console.log('Desktop organized!');
  } finally {
    await desktop.close();
  }
}

organizeLocalDesktop();

​
Hybrid Workflow Example

Combine cloud and local resources in a single workflow: 
import { bctrl, playwright } from '@bctrl/sdk';

async function hybridWorkflow() {
  // Step 1: Use cloud browser to scrape data
  const browser = await playwright.connect({
    apiKey: process.env.BCTRL_API_KEY
  });

  const data = await browser.stagehand.extract(
    'Get all product prices from the table',
    z.array(z.object({ name: z.string(), price: z.number() }))
  );

  await browser.close();

  // Step 2: Use local desktop to update Excel spreadsheet
  const desktop = await bctrl.desktop.connect({
    target: 'local',
    apiKey: process.env.BCTRL_API_KEY
  });

  await desktop.cua.run('Open my Products.xlsx spreadsheet');

  // Update each row with new prices
  for (const product of data) {
    await desktop.cua.run(
      `Find "${product.name}" in column A and update its price in column B to ${product.price}`
    );
  }

  await desktop.cua.run('Save the spreadsheet');
  await desktop.close();

  console.log('Prices updated in local spreadsheet!');
}

hybridWorkflow();

Cloud Computers

Use cloud VMs instead of your own hardware

Cloud Browsers

Remote browsers for web automation

Desktop Automation

Mouse, keyboard, and screen APIs

AI Agents

CUA and other AI agents for automation