What is a pad_id and why does it matter?

A pad_id is the stable identifier for one physical device in your fleet. Every run, schedule, and content upload targets devices by pad_id. It is the handle you pass to start_run, start_content_run, and create_schedule, so it is the first thing to collect before any job.

Why is a device busy and how do I free it?

A device is busy while it is locked by an active run. Locks release automatically when the run ends, completes, fails, or is stopped. Filter on the busy flag from list_devices and target free devices, or stop the holding run with stop_run if you need it back immediately.

What is a prompt profile?

The prompt profile is the saved engagement behavior attached to a device — for example full, lurk, recovery, or recovery_exploration. When you start a run with an engagement argument, each device auto-applies its own profile's prompt and persona instead of one shared template.

Device Fleet & pad IDs

How Conbersa devices work: pad IDs, platforms, prompt profiles, busy locks, and managed-for access. What to check before you start a run.

Every account lives on a device, and every device answers to a pad_id. Collect the ones you want, check which are free, then start. That one habit prevents most failed runs.

What a device exposes

list_devices returns, for each device:

Field	Meaning
`pad_id`	Stable identifier you target in every run
`device_name`	Human-readable label
`device_group`	Logical grouping
`platform`	Primary platform for the account
`platforms`	All platforms this device can run
`username`	The account handle
`status`	Provisioning/health status
`prompt_profile`	The engagement behavior it applies by default
`busy`	Whether a run currently holds a lock
`locked_by`	Who holds the lock, when busy

Prompt profiles

A device's prompt profile tells an agent how that account should behave when you use engagement:

full — full engagement behavior.
lurk — light, passive activity.
recovery — rebuilding an account's health.
recovery_exploration — recovery with discovery.

Pass engagement to start_run and each device applies its own profile — its own prompt and persona — instead of one shared template. Run preview_run to see exactly what each device will do before you commit.

Busy locks

Starting a run locks every device it touches. That's how two jobs avoid acting on the same account at once.

A busy device makes the run fail with Device busy — <pad_id> (held by <owner>).
Locks release when the run ends, completes, fails, or is stopped.
To free a device now, stop the holding run with stop_run.

Filter before you start. Ask for free devices and pass only those pad_ids. Don't let the lock error be how you find out.

Managed-for access

Some accounts run on behalf of another user. For those, managed_for_user_ids records who the run is for, and that user can see and stop the relevant sessions. Admins see the whole organization's fleet and sessions; non-admin keys see only their own and their managed-for devices.

Local development

Run the Conbersa backend locally and the MCP server is at http://localhost:8080/mcp. The same API-key rules apply — there's no unauthenticated mode. See MCP quickstart.

Checklist before a run

list_devices — collect target pad_ids.
Filter on busy — keep only the free ones.
Confirm prompt_profile — or decide to override with a prompt_id.
Optionally preview_run — confirm per-device behavior.
start_run — execute and open the session link.