App SDK deployment

Learn how to deploy your custom application to your organization dashboard.

To deploy your custom application, you use the same command as when deploying a studio: sanity deploy

npx sanity deploy

pnpm dlx sanity deploy

yarn dlx sanity deploy

bunx sanity deploy

Note that to deploy SDK apps you need a role of organization admin, Developer, or equivalent. Organization-level robot tokens with the "Manage SDK Apps" permission (which grants deploy, read, and delete access to SDK applications) can also be used to deploy SDK apps. Read more about roles and permissions here.

To undeploy your custom application, you can use sanity undeploy from within your custom app’s directory.

npx sanity undeploy

pnpm dlx sanity undeploy

yarn dlx sanity undeploy

bunx sanity undeploy

Note that you’ll need to have your app.id saved in your sanity.cli.ts file (as prompted during the deploy process) in order for your app’s deployment to be removed.

App SDK deployment requires an organization-level robot token with the Manage SDK Apps permission. This is different from Studio deployment, which uses project-level tokens. To create a sufficient token, you’ll need org-level developer or administrator permissions.

To create a robot token:

• Go to Manage and select your organization.
• Navigate to Settings > API > Robot tokens.
• Create a new token and select the Manage SDK Apps permission.
• Copy the token and store it as a secret in your CI/CD environment (for example, as a GitHub Actions secret).

Set the SANITY_AUTH_TOKEN environment variable to your robot token. The Sanity CLI reads this variable automatically when deploying.

For App SDK apps, the --title flag is required for fully unattended deployments. Without it, the CLI will interactively prompt for an app title on the first deploy. In CI/CD pipelines, pass --title to skip this prompt. For example: npx sanity deploy --title "My App".

name: Deploy App SDK
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx sanity deploy --title 'My App'
        env:
          SANITY_AUTH_TOKEN: ${{ secrets.SANITY_DEPLOY_TOKEN }}

The following environment variables are relevant for App SDK deployment:

• SANITY_AUTH_TOKEN: the organization-level robot token for authentication. Required for non-interactive deployment.
• SANITY_APP_*: any environment variables prefixed with SANITY_APP_ are embedded in your app's browser code at build time.

The following errors are commonly reported by developers deploying App SDK apps:

• "Unauthorized" or "Insufficient permissions": verify that your token is an organization-level robot token with the Manage SDK Apps permission enabled.
• "Session does not match project host": this can occur in CI/CD environments. Ensure SANITY_AUTH_TOKEN is set correctly and that no cached credentials are interfering.