Device Bucket Storage

Utils

Device-scoped persistent storage shared across all jobs and automations

Access device bucket storage through agent.utils.deviceBucket. Device bucket data is scoped to a specific device and persists across all jobs and automations running on that device. Use it to store account credentials, app configurations, or any data that should be shared across all automations on the same device.

Note: Unlike agent.utils.bucket, device bucket does not require a job context. It is available in all automation contexts, including direct-run automations.

DeviceBucketUtils Interface

TypeScript

interface DeviceBucketUtils {
  get(): Promise<
    { success: false; error: string } |
    { success: true; deviceBucket: Record<string, any> }
  >;

  set(data: Record<string, any>): Promise<
    { success: false; error: string } |
    { success: true; deviceBucket: Record<string, any> }
  >;
}

`get()`

TypeScript

get(): Promise<{ success: false; error: string } | { success: true; deviceBucket: Record<string, any> }>

Retrieves the current device bucket data. Returns the stored data object, or an empty object if no device bucket exists yet.

Returns

{ success: true; deviceBucket: Record<string, any> } | { success: false; error: string }The stored device bucket data on success, or an error message

Examples

Read device bucket data

TypeScript

const result = await agent.utils.deviceBucket.get();

if (result.success) {
  console.log("Device bucket:", result.deviceBucket);

  // Access stored values
  const token = result.deviceBucket.accountToken;
  const username = result.deviceBucket.username;
} else {
  console.error("Failed to get device bucket:", result.error);
}

Check if account credentials exist before logging in

TypeScript

const result = await agent.utils.deviceBucket.get();

if (result.success && result.deviceBucket.accountToken) {
  console.log("Reusing stored credentials");
  // Skip login, use stored credentials
} else {
  console.log("No credentials found, performing login...");
  // Perform login flow
}

`set()`

TypeScript

set(data: Record<string, any>): Promise<{ success: false; error: string } | { success: true; deviceBucket: Record<string, any> }>

Merges the provided data into the existing device bucket. New keys are added and existing keys are overwritten. Keys not included in the provided data are preserved.

Parameters

Name	Type	Description
`data`	`Record<string, any>`	Object containing the key-value pairs to merge into the device bucket. Existing keys not present in this object are preserved.

Returns

{ success: true; deviceBucket: Record<string, any> } | { success: false; error: string }The full merged device bucket data on success, or an error message

Examples

Store account credentials after login

TypeScript

// After successful login, persist credentials for all automations
const result = await agent.utils.deviceBucket.set({
  accountToken: "abc123xyz",
  username: "user@example.com",
  loginTimestamp: Date.now(),
});

if (result.success) {
  console.log("Credentials saved:", result.deviceBucket);
}

Merge additional data (existing keys are preserved)

TypeScript

// First call: store credentials
await agent.utils.deviceBucket.set({
  accountToken: "abc123",
  username: "user1",
});

// Second call: add more data without losing credentials
await agent.utils.deviceBucket.set({
  appVersion: "2.1.0",
  lastChecked: Date.now(),
});

// Device bucket now contains all four keys:
// { accountToken, username, appVersion, lastChecked }

Comparison with Job Bucket

Feature	`agent.utils.bucket`	`agent.utils.deviceBucket`
Scope	Device + Job	Device only
Requires job context	Yes	No
Schema validation	Optional (via bucket_schema)	None
Shared between jobs	No (separate per job)	Yes (all jobs share it)
Use case	Job-specific session state	Device-wide credentials, config

Typical Usage Pattern

TypeScript

// At the start of any automation: check for device-level credentials
const db = await agent.utils.deviceBucket.get();

if (db.success && db.deviceBucket.accountToken) {
  // Reuse credentials from any previous automation
  console.log("Using stored credentials for:", db.deviceBucket.username);
} else {
  // First time on this device - perform account setup
  const { token, username } = await performAccountSetup();

  // Save for all future automations on this device
  await agent.utils.deviceBucket.set({
    accountToken: token,
    username: username,
    setupDate: Date.now(),
  });
}