Start
Quickstart
Create a scoped key, connect one client, then verify a read-only phone workflow before sending input.
1. Create a key
Open the Agents workspace. Grant only the phones and scopes the client needs. The token is shown once. Store it in a secret environment as FLEETDECK_API_KEY.
2. Connect
Codex MCP connection
codex mcp add fleetdeck --url https://fleetdeck.co/api/mcp --bearer-token-env-var FLEETDECK_API_KEYCLI install
npm install -g https://fleetdeck.co/downloads/fleetdeck-cli-0.1.1.tgz
fleetdeck devices3. First task
Agent prompt
List my FleetDeck phones, show the capabilities of the phone I choose, acquire a session, capture a fresh screenshot, and release the session. Do not send input.The first run should prove authentication, device grant, capability discovery, session acquisition and real capture without changing app state.
Direct REST example
bash
# FLEETDECK_API_KEY is supplied by your secret manager/environment.
# Do not paste a literal key into command history; disable shell tracing.
export FLEETDECK_BASE_URL=https://fleetdeck.co
node --input-type=module <<'JS'
const token = process.env.FLEETDECK_API_KEY;
if (!token) throw new Error("Set FLEETDECK_API_KEY securely first");
const base = process.env.FLEETDECK_BASE_URL || "https://fleetdeck.co";
async function api(path, method = "GET", body) {
const r = await fetch(base + "/api/v1" + path, {
method, headers: { Authorization: "Bearer " + token,
...(body === undefined ? {} : { "Content-Type": "application/json" }) },
...(body === undefined ? {} : { body: JSON.stringify(body) }),
});
const data = await r.json();
if (!r.ok) throw new Error(data.code + ": " + data.error);
return data;
}
const { devices } = await api("/devices");
console.log(devices.map(({ id, name, platform }) => ({ id, name, platform })));
// Set FLEETDECK_DEVICE_ID to the exact phone ID from that list.
const deviceId = process.env.FLEETDECK_DEVICE_ID;
if (!deviceId) throw new Error("Select FLEETDECK_DEVICE_ID before opening a session");
console.log(await api("/devices/" + encodeURIComponent(deviceId) + "/capabilities"));
const session = await api("/sessions", "POST", { deviceId, ttlSeconds: 120 });
const requestId = "observe-" + crypto.randomUUID();
console.log({ sessionId: session.id, requestId }); // Keep these for recovery.
try {
let action = await api("/sessions/" + session.id + "/actions", "POST", {
requestId, command: { type: "screenshot" },
});
const deadline = Date.now() + 35000;
while (["queued", "running"].includes(action.status) && Date.now() < deadline) {
await new Promise(resolve => setTimeout(resolve, 1000));
action = await api("/sessions/" + session.id + "/actions/" + requestId);
}
console.log({ status: action.status, kind: action.kind });
if (action.status !== "completed") throw new Error("Inspect original action; do not replay");
// Consume action.result.content privately; images may contain sensitive data.
} finally {
await api("/sessions/" + session.id, "DELETE");
}
JSThe example saves session and request IDs, polls the original action and releases in a finally block. Screen content can be sensitive; keep it out of ordinary logs.
