migration guide.md

Migrate from Sapient to Lightsage

Update Sapient CLI, MCP, Public API, Agent Tracker, and Docs Agent integrations to their Lightsage names.

Sapient is now Lightsage. Update integrations that reference previous commands, package names, or hosts. Your organizations, data, and existing API key values do not change.

Warning: Use the Lightsage command, package, host, and authentication names in all new configuration.

Use Lightsage CLI 0.6.4 or later, Lightsage MCP 0.1.7 or later, and Agent Tracker 0.1.14 or later when completing this migration.

Migration summary

Surface Previous value Lightsage value
CLI executable sapient lightsage
MCP endpoint https://mcp.usesapient.com/mcp https://mcp.lightsage.com/mcp
Public API base URL https://api-public.usesapient.com https://api.lightsage.com
Agent Tracker package @usesapient/agent-tracker @lightsage/agent-tracker
Docs Agent slash command /sapient ... /lightsage ...
Docs Agent documentation path /sapient-docs-agent/* /lightsage-docs-agent/*

Public API paths remain under /v1, and the MCP path remains /mcp. The rebrand does not change resource IDs, organization IDs, request bodies, or response bodies by itself.

Use --lightsage-api-key-auth or LIGHTSAGE_API_KEY with the CLI, and X-Lightsage-Api-Key with hosted MCP and direct public API requests.

Migrate the CLI

1. Install the Lightsage CLI

brew uninstall sapient
brew install lightsagehq/tools/lightsage
lightsage version

Confirm the installed version is 0.6.4 or later.

2. Update commands and authentication

Replace the executable, auth flag, and environment variables in scripts:

export LIGHTSAGE_API_KEY="your_existing_api_key"
lightsage --lightsage-api-key-auth "$LIGHTSAGE_API_KEY" status auth-status-get

For CLI authentication through the environment, use LIGHTSAGE_API_KEY.

3. Verify the CLI

lightsage version
lightsage auth whoami --no-interactive
lightsage status auth-status-get --no-interactive

Lightsage CLI stores configuration under ~/.config/lightsage. Re-run lightsage auth login after installation to save your API key in the Lightsage keychain entry.

Migrate MCP clients

Update each MCP client configuration:

  1. Rename the local server entry from sapient to lightsage.
  2. Use https://mcp.lightsage.com/mcp for remote connections.
  3. Set the API-key header to X-Lightsage-Api-Key.
  4. Use @lightsage/mcp for local npx setups.
{
  "mcpServers": {
    "lightsage": {
      "type": "http",
      "url": "https://mcp.lightsage.com/mcp",
      "headers": {
        "X-Lightsage-Api-Key": "${LIGHTSAGE_API_KEY}"
      }
    }
  }
}

For local stdio configurations, update the package and flag together:

npx @lightsage/mcp start --lightsage-api-key-auth "$LIGHTSAGE_API_KEY"

Use @lightsage/mcp 0.1.7 or later so local and hosted clients use the canonical Lightsage authentication contract.

If your client uses OAuth, disconnect the legacy connector and add Lightsage with the new endpoint. This ensures the OAuth resource identifier matches the canonical Lightsage MCP URL.

Migrate direct Public API integrations

Use the Lightsage base URL and API-key header. Keep the existing /v1 path and API key value.

curl https://api.lightsage.com/v1/auth/status \
  -H "X-Lightsage-Api-Key: $LIGHTSAGE_API_KEY"

Migrate Agent Tracker

Install Agent Tracker 0.1.14 or later before switching declarative browser markup to data-lightsage-*.

1. Replace the npm package

npm uninstall @usesapient/agent-tracker
npm install @lightsage/agent-tracker

2. Update framework imports

// Before
import { withAgentTracking } from '@usesapient/agent-tracker/next';

// After
import { withAgentTracking } from '@lightsage/agent-tracker/next';

3. Redeploy and verify events

Rebuild and redeploy your application. Open Agent Analytics and confirm that new visits arrive from the migrated deployment.

Migrate the Docs Agent

Replace Docs Agent commands in pull request templates, saved replies, and automation:

# Before
/sapient run evals

# After
/lightsage run evals

Use /lightsage status and /lightsage help for the other commands. Legacy /sapient commands remain available as a compatibility fallback.

Update saved links from /sapient-docs-agent/* to /lightsage-docs-agent/*. The old documentation paths redirect permanently to their Lightsage equivalents.

Final verification