openwork/ee/apps/den-controller/AGENT_FOCUS.md

Agent Focus: Den Service + Polar Gate

This guide explains how agents should operate, test, and troubleshoot the Den service.

What this service does

• Handles auth (/api/auth/*) and session lookup (/v1/me).
• Creates workers (/v1/workers) and provisions cloud workers on Render or Daytona.
• Optionally enforces a Polar paywall for cloud worker creation.

Core flows to test

1) Auth flow

1. POST /api/auth/sign-up/email
2. GET /v1/me using cookie session
3. GET /v1/me using Bearer token from sign-up response

Expected: all succeed with 200.

2) Cloud worker flow (no paywall)

Set POLAR_FEATURE_GATE_ENABLED=false.

1. POST /v1/workers with destination="cloud"
2. Confirm instance.provider matches the configured cloud provisioner (render or daytona)
3. Poll instance.url + "/health"

Expected: worker creation 202, worker health 200 after async provisioning finishes.

3) Cloud worker flow (paywall enabled)

Set all Polar env vars and POLAR_FEATURE_GATE_ENABLED=true.

For a user without entitlement:

1. POST /v1/workers with destination="cloud"

Expected:

• 402 payment_required
• response contains polar.checkoutUrl

For an entitled user (has the required Polar benefit):

1. POST /v1/workers with destination="cloud"

Expected: worker creation 202 with a healthy cloud-backed instance once provisioning completes.

Required env vars (summary)

• Base: DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL
• Optional social auth: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
• Render: PROVISIONER_MODE=render, RENDER_API_KEY, RENDER_OWNER_ID, and RENDER_WORKER_*
• Daytona: PROVISIONER_MODE=daytona, DAYTONA_API_KEY, and optional DAYTONA_* sizing/mount settings
• Polar gate:
  • POLAR_FEATURE_GATE_ENABLED
  • POLAR_ACCESS_TOKEN
  • POLAR_PRODUCT_ID
  • POLAR_BENEFIT_ID
  • POLAR_SUCCESS_URL
  • POLAR_RETURN_URL

Deployment behavior

dev is the production branch for this service. Workflow:

• .github/workflows/deploy-den.yml

It updates Render env vars and triggers a deploy for the configured service ID. Release snapshot publishing now calls it after a successful Daytona snapshot push so Den picks up the new DAYTONA_SNAPSHOT value.

Common failure modes

• provisioning_failed: Render deploy failed, Daytona sandbox boot failed, or worker health check timed out.
• payment_required: Polar gate is enabled and user does not have the required benefit.
• startup error: paywall enabled but missing Polar env vars.