Skip to main content

Beacon

Beacon handles installation bootstrap and recurring lease heartbeats for deployed agents.

note

See Beacon Architecture for protocol details.

Prerequisites​

For first bootstrap, use an install token from dashboard/CLI.

  • Dashboard: Operations → Install Tokens
  • CLI: sekuire install token --workspace <workspace_id> --agent <sekuire_id>

Install token flow details: Using Agents → Install Token Flow.

Quick Start (SekuireSDK)​

import { SekuireSDK } from '@sekuire/sdk';

const sdk = SekuireSDK.fromEnv();
await sdk.start();

console.log('Connected:', sdk.isConnected());
console.log('Beacon status:', sdk.getBeaconStatus());

await sdk.shutdown();

Using Beacon Directly​

import { Beacon } from '@sekuire/sdk';

const beacon = new Beacon({
  apiBaseUrl: 'https://api.sekuire.ai',
  agentId: process.env.SEKUIRE_AGENT_ID!,
  installToken: process.env.SEKUIRE_INSTALL_TOKEN,
  // Optional fallback path when install token is invalid/expired:
  apiKey: process.env.SEKUIRE_API_KEY,
  workspaceId: process.env.SEKUIRE_WORKSPACE_ID,
  heartbeatIntervalSeconds: 60,
  capabilities: ['summarize', 'classify'],
  onStatusChange: (status) => {
    console.log(status);
  },
});

await beacon.start();
console.log(beacon.getStatus());
beacon.stop();

Authentication Priority​

On startup, Beacon resolves auth in this order:

  1. installationId + refreshToken recovery credentials
  2. If a runtime token is present, Beacon validates it first before refreshing
  3. Install token bootstrap (installToken)
  4. If bootstrap fails permanently and apiKey + workspaceId exist, Beacon tries recovery bootstrap

If all paths fail, Beacon enters degraded mode (agent keeps running, Sekuire features disabled).

Credential Recovery for Ephemeral Compute​

After a successful bootstrap, persist credentials for restarts:

const creds = beacon.getInstallationCredentials();
if (creds) {
  console.log(`SEKUIRE_INSTALLATION_ID=${creds.installationId}`);
  console.log(`SEKUIRE_REFRESH_TOKEN=${creds.refreshToken}`);
  console.log(`SEKUIRE_RUNTIME_TOKEN=${creds.runtimeToken}`); // optional
}

On restart, set SEKUIRE_INSTALLATION_ID + SEKUIRE_REFRESH_TOKEN; Beacon recovers without consuming a new install token.

Degraded Mode and Status Fields​

beacon.getStatus() includes:

  • isRunning
  • installationId
  • runtimeToken (masked)
  • deploymentUrl
  • lastHeartbeat
  • failedHeartbeats
  • degradedMode
  • recoveredFromEnv
const status = beacon.getStatus();
if (status.degradedMode) {
  console.warn('Running without active Sekuire bootstrap credentials');
}

Sharing Credentials with TaskWorker​

When Beacon and TaskWorker run in the same process, use a shared RuntimeCredentialsStore to avoid token drift during refresh.

  • SekuireSDK.createTaskWorker() wires this automatically.
  • For manual setup, pass the same credentialsStore to both Beacon and Worker.

Next Steps​