Migrate from Sapient to Lightsage - Lightsage

Documentation Index

Fetch the complete documentation index at: /docs/llms.txt

Use this file to discover all available pages before exploring further.

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.

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

Install the Lightsage CLI

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

Confirm the installed version is 0.6.4 or later.

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.

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:

Rename the local server entry from sapient to lightsage.
Use https://mcp.lightsage.com/mcp for remote connections.
Set the API-key header to X-Lightsage-Api-Key.
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-*.

Replace the npm package

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

Update framework imports

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

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

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

lightsage version reports 0.6.4 or later.
lightsage status auth-status-get --no-interactive authenticates successfully.
MCP clients use https://mcp.lightsage.com/mcp or @lightsage/mcp.
Direct API requests use https://api.lightsage.com and X-Lightsage-Api-Key.
Application imports use @lightsage/agent-tracker.
Docs Agent automation and saved replies use /lightsage commands.
New Agent Tracker visits appear in the Lightsage dashboard after deployment.

Documentation Index

​ Migration summary

​ Migrate the CLI

​ Migrate MCP clients

​ Migrate direct Public API integrations

​ Migrate Agent Tracker

​ Migrate the Docs Agent

​ Final verification