> ## Documentation Index
> Fetch the complete documentation index at: https://lightsage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.
</Warning>

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

<Steps>
  <Step title="Install the Lightsage CLI">
    ```bash theme={null}
    brew uninstall sapient
    brew install lightsagehq/tools/lightsage
    lightsage version
    ```

    Confirm the installed version is `0.6.4` or later.
  </Step>

  <Step title="Update commands and authentication">
    Replace the executable, auth flag, and environment variables in scripts:

    ```bash theme={null}
    export LIGHTSAGE_API_KEY="your_existing_api_key"
    lightsage --lightsage-api-key-auth "$LIGHTSAGE_API_KEY" status auth-status-get
    ```

    For generated CLI environment variables, use
    `CLI_LIGHTSAGE_API_KEY_AUTH`.
  </Step>

  <Step title="Verify the CLI">
    ```bash theme={null}
    lightsage version
    lightsage auth whoami --no-interactive
    lightsage status auth-status-get --no-interactive
    ```
  </Step>
</Steps>

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.

```json theme={null}
{
  "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:

```bash theme={null}
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.

```bash theme={null}
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-*`.

<Steps>
  <Step title="Replace the npm package">
    ```bash theme={null}
    npm uninstall @usesapient/agent-tracker
    npm install @lightsage/agent-tracker
    ```
  </Step>

  <Step title="Update framework imports">
    ```typescript theme={null}
    // Before
    import { withAgentTracking } from '@usesapient/agent-tracker/next';

    // After
    import { withAgentTracking } from '@lightsage/agent-tracker/next';
    ```
  </Step>

  <Step title="Redeploy and verify events">
    Rebuild and redeploy your application. Open **Agent Analytics** and confirm
    that new visits arrive from the migrated deployment.
  </Step>
</Steps>

## Migrate the Docs Agent

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

```text theme={null}
# 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.