feat: auto-create Gitea releases on tag push and fix PyPI publish venv

docs: update all documentation for subscription auth, billing tiers, and API key management
feat: add CI/CD workflows for npm and PyPI auto-publish on tag
2026-02-11 00:43:36 +00:00 · 2026-02-11 00:35:51 +00:00 · 2026-02-11 00:33:24 +00:00 · 2026-02-11 00:02:00 +00:00 · 2026-02-10 23:57:47 +00:00 · 2026-02-10 23:56:09 +00:00
14 changed files with 550 additions and 11 deletions
--- a/.gitea/workflows/deploy.yml
+++ b/.gitea/workflows/deploy.yml
@@ -0,0 +1,77 @@
+name: Deploy AgentLens
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+env:
+  COMPOSE_PROJECT_NAME: agentlens
+  DOCKER_HOST: tcp://192.168.1.133:2375
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Verify Docker access
+        run: |
+          docker version
+          docker compose version
+
+      - name: Write environment file
+        run: |
+          cat > .env <<'ENVEOF'
+          AUTH_SECRET=${{ secrets.AUTH_SECRET }}
+          STRIPE_SECRET_KEY=${{ secrets.STRIPE_SECRET_KEY }}
+          STRIPE_WEBHOOK_SECRET=${{ secrets.STRIPE_WEBHOOK_SECRET }}
+          POSTGRES_PASSWORD=${{ secrets.POSTGRES_PASSWORD }}
+          REDIS_PASSWORD=${{ secrets.REDIS_PASSWORD }}
+          EMAIL_PASSWORD=${{ secrets.EMAIL_PASSWORD }}
+          ENVEOF
+          sed -i 's/^[[:space:]]*//' .env
+
+      - name: Build and deploy
+        run: |
+          echo "Deploying AgentLens ${{ gitea.ref_name }}..."
+          docker compose build web migrate
+          docker compose up -d --no-deps --remove-orphans web migrate redis postgres
+          echo "Waiting for migration and startup..."
+          sleep 25
+
+      - name: Health check
+        run: |
+          for i in 1 2 3 4 5; do
+            STATUS=$(docker inspect --format='{{.State.Running}}' agentlens-web-1 2>/dev/null || true)
+            if [ "$STATUS" = "true" ]; then
+              echo "Container running (attempt $i)"
+              exit 0
+            fi
+            echo "Attempt $i/5 — retrying in 10s..."
+            sleep 10
+          done
+          echo "Health check failed after 5 attempts"
+          docker compose logs web --tail 50
+          exit 1
+
+      - name: Create Gitea Release
+        if: startsWith(gitea.ref, 'refs/tags/')
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          TAG="${{ gitea.ref_name }}"
+          curl -s -X POST \
+            "https://gitea.vectry.tech/api/v1/repos/Vectry/agentlens/releases" \
+            -H "Authorization: token ${RELEASE_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "{\"tag_name\": \"${TAG}\", \"name\": \"${TAG}\", \"body\": \"Automated release for ${TAG}\", \"draft\": false, \"prerelease\": false}" \
+            || echo "Release may already exist — skipping"
+
+      - name: Cleanup
+        if: always()
+        run: docker image prune -f
--- a/.gitea/workflows/publish-npm.yml
+++ b/.gitea/workflows/publish-npm.yml
@@ -0,0 +1,40 @@
+name: Publish npm packages
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        run: |
+          echo "VERSION=$(echo $GITHUB_REF_NAME | sed 's/^v//')" >> $GITHUB_ENV
+
+      - name: Configure npm auth
+        run: |
+          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
+
+      - name: Update package versions
+        run: |
+          cd packages/sdk-ts && npm version $VERSION --no-git-tag-version
+          cd ../opencode-plugin && npm version $VERSION --no-git-tag-version
+
+      - name: Publish agentlens-sdk
+        run: |
+          cd packages/sdk-ts
+          npm install
+          npm run build
+          npm publish --access public
+
+      - name: Publish opencode-agentlens
+        run: |
+          cd packages/opencode-plugin
+          npm install
+          npm run build
+          npm publish --access public
--- a/.gitea/workflows/publish-pypi.yml
+++ b/.gitea/workflows/publish-pypi.yml
@@ -0,0 +1,34 @@
+name: Publish PyPI package
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    env:
+      TWINE_USERNAME: __token__
+      TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        run: |
+          echo "VERSION=$(echo $GITHUB_REF_NAME | sed 's/^v//')" >> $GITHUB_ENV
+
+      - name: Update version in pyproject.toml
+        run: |
+          cd packages/sdk-python
+          sed -i "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+
+      - name: Build and publish to PyPI
+        run: |
+          cd packages/sdk-python
+          python3 -m venv .venv
+          . .venv/bin/activate
+          pip install build twine
+          python -m build
+          twine upload dist/*
--- a/6
+++ b/6
@@ -14,7 +14,11 @@ FROM base AS builder
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
 RUN npx prisma generate --schema=packages/database/prisma/schema.prisma
-RUN npx turbo build
+RUN npx turbo build --filter=@agentlens/web...
+
+FROM base AS migrate
+COPY --from=deps /app/node_modules ./node_modules
+COPY packages/database/prisma ./packages/database/prisma

 FROM base AS web
 RUN addgroup --system --gid 1001 nodejs && \
--- a/README.md
+++ b/README.md
@@ -18,6 +18,15 @@

 Existing observability tools show you _what_ LLM calls were made. AgentLens shows you _why_ your agent made each decision along the way -- which tool it picked, what alternatives it rejected, and the reasoning behind every choice.

+## Getting Started
+
+1. **Register** at [agentlens.vectry.tech/register](https://agentlens.vectry.tech/register) with your email and password.
+2. **Log in** to the dashboard at [agentlens.vectry.tech](https://agentlens.vectry.tech).
+3. **Create an API key** in **Settings > API Keys**.
+4. **Install the SDK** and start tracing.
+
+> Self-hosting? You do not need to register with the hosted service. See [Self-Hosting](#self-hosting) below.
+
 ## Quick Start

 ```bash
@@ -27,6 +36,7 @@ pip install vectry-agentlens
 ```python
 import agentlens

+# Use the API key you created in Settings > API Keys
 agentlens.init(api_key="your-key", endpoint="https://agentlens.vectry.tech")

 with agentlens.trace("my-agent-task", tags=["production"]):
@@ -41,7 +51,7 @@ with agentlens.trace("my-agent-task", tags=["production"]):
 agentlens.shutdown()
 ```

-Open `https://agentlens.vectry.tech/dashboard` to see your traces.
+Open `https://agentlens.vectry.tech/dashboard` to see your traces (login required).

 ## Features

@@ -72,7 +82,7 @@ Add to your `opencode.json`:
 }
 ```

-Set environment variables:
+Set environment variables (use the API key from your dashboard at **Settings > API Keys**):

 ```bash
 export AGENTLENS_API_KEY="your-key"
@@ -90,6 +100,7 @@ npm install agentlens-sdk
 ```typescript
 import { init, TraceBuilder, SpanType, SpanStatus } from "agentlens-sdk";

+// Use the API key from Settings > API Keys in your dashboard
 init({ apiKey: "your-key", endpoint: "https://agentlens.vectry.tech" });

 const trace = new TraceBuilder("my-agent-task", {
@@ -173,8 +184,24 @@ with agentlens.trace("planner"):
 | `MEMORY_RETRIEVAL` | Agent chose what context to retrieve |
 | `CUSTOM` | Any other decision type |

+## Pricing
+
+AgentLens cloud ([agentlens.vectry.tech](https://agentlens.vectry.tech)) offers three billing tiers. One trace equals one session for billing purposes.
+
+| Plan | Price | Sessions | Details |
+|------|-------|----------|---------|
+| **Free** | $0 | 20 sessions/day | No credit card required |
+| **Starter** | $5/month | 1,000 sessions/month | For individual developers |
+| **Pro** | $20/month | 100,000 sessions/month | For teams and production workloads |
+
+Manage your subscription in **Settings > Billing** in the dashboard.
+
+Self-hosted instances are not subject to these limits.
+
 ## Self-Hosting

+Self-hosted AgentLens instances do not require registration with the hosted SaaS service. You manage your own API keys and have no session limits.
+
 ```bash
 git clone https://gitea.repi.fun/repi/agentlens.git
 cd agentlens
--- a/apps/web/src/app/docs/api-reference/page.tsx
+++ b/apps/web/src/app/docs/api-reference/page.tsx
@@ -55,9 +55,37 @@ export default function ApiReferencePage() {
      <section className="mb-6">
        <h2 className="text-2xl font-semibold mb-4">Authentication</h2>
        <p className="text-neutral-400 leading-relaxed mb-4">
-          All write endpoints require a Bearer token in the Authorization header:
+          All API endpoints require a Bearer token in the Authorization header.
+          To obtain an API key, register at{" "}
+          <a
+            href="https://agentlens.vectry.tech/register"
+            className="text-emerald-400 hover:underline"
+          >
+            agentlens.vectry.tech/register
+          </a>
+          , log in, and create a key in{" "}
+          <strong className="text-neutral-200">Settings &rarr; API Keys</strong>
+          .
        </p>
        <CodeBlock>{`Authorization: Bearer your-api-key`}</CodeBlock>
+        <div className="px-4 py-3 rounded-lg bg-neutral-900/50 border border-neutral-800/50 mt-4">
+          <p className="text-sm text-neutral-400">
+            <strong className="text-neutral-300">Rate limits:</strong>{" "}
+            API usage is governed by your billing tier. The Free plan allows 20
+            sessions per day. Starter ($5/month) allows 1,000 sessions per
+            month. Pro ($20/month) allows 100,000 sessions per month. One trace
+            equals one session for billing purposes. Manage your plan in{" "}
+            <strong className="text-neutral-300">Settings &rarr; Billing</strong>
+            . See{" "}
+            <a
+              href="/docs/authentication-billing"
+              className="text-emerald-400 hover:underline"
+            >
+              Authentication &amp; Billing
+            </a>{" "}
+            for details.
+          </p>
+        </div>
      </section>

      <hr className="border-neutral-800/50 my-10" />
--- a/apps/web/src/app/docs/authentication-billing/page.tsx
+++ b/apps/web/src/app/docs/authentication-billing/page.tsx
@@ -0,0 +1,200 @@
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Authentication & Billing",
+  description:
+    "Register for AgentLens, manage API keys, and understand billing tiers and session limits.",
+};
+
+export default function AuthenticationBillingPage() {
+  return (
+    <div>
+      <h1 className="text-4xl font-bold tracking-tight mb-4">
+        Authentication &amp; Billing
+      </h1>
+      <p className="text-lg text-neutral-400 mb-10 leading-relaxed">
+        AgentLens cloud requires an account to access the dashboard and ingest
+        traces. This page covers registration, API key management, billing
+        tiers, and session counting.
+      </p>
+
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">Registration</h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          To use AgentLens cloud, create an account at{" "}
+          <a
+            href="https://agentlens.vectry.tech/register"
+            className="text-emerald-400 hover:underline"
+          >
+            agentlens.vectry.tech/register
+          </a>
+          . You will need to provide an email address and password. Once
+          registered, log in at{" "}
+          <a
+            href="https://agentlens.vectry.tech"
+            className="text-emerald-400 hover:underline"
+          >
+            agentlens.vectry.tech
+          </a>{" "}
+          to access the dashboard.
+        </p>
+        <p className="text-neutral-400 leading-relaxed">
+          The dashboard requires authentication -- there is no anonymous access.
+          All features including trace viewing, analytics, and settings are
+          available only after login.
+        </p>
+      </section>
+
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">API keys</h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          API keys authenticate your SDKs and integrations when sending traces
+          to AgentLens. Keys are generated per-user in the dashboard.
+        </p>
+        <h3 className="text-lg font-medium text-neutral-200 mb-2">
+          Creating an API key
+        </h3>
+        <ol className="list-decimal list-inside text-neutral-400 space-y-2 ml-1 mb-4">
+          <li>Log in to the AgentLens dashboard.</li>
+          <li>
+            Navigate to{" "}
+            <strong className="text-neutral-200">
+              Settings &rarr; API Keys
+            </strong>
+            .
+          </li>
+          <li>
+            Click <strong className="text-neutral-200">Create API Key</strong>,
+            give it a name, and copy the generated key.
+          </li>
+          <li>
+            Store the key securely. It will not be shown again after you leave
+            the page.
+          </li>
+        </ol>
+        <h3 className="text-lg font-medium text-neutral-200 mb-2">
+          Using your API key
+        </h3>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          Pass the key to the SDK during initialization, or set it as the{" "}
+          <code className="text-emerald-400 font-mono text-xs bg-emerald-500/5 px-1.5 py-0.5 rounded">
+            AGENTLENS_API_KEY
+          </code>{" "}
+          environment variable. The SDKs will pick it up automatically.
+        </p>
+        <div className="px-4 py-3 rounded-lg bg-neutral-900/50 border border-neutral-800/50">
+          <p className="text-sm text-neutral-400">
+            <strong className="text-neutral-300">Security note:</strong>{" "}
+            Treat API keys like passwords. Do not commit them to version control.
+            Use environment variables or a secrets manager in production.
+          </p>
+        </div>
+      </section>
+
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">Billing tiers</h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          AgentLens cloud offers three billing tiers. One trace equals one
+          session for billing purposes.
+        </p>
+        <div className="overflow-x-auto mb-6">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b border-neutral-800">
+                <th className="text-left py-2 pr-4 text-neutral-400 font-medium">
+                  Plan
+                </th>
+                <th className="text-left py-2 pr-4 text-neutral-400 font-medium">
+                  Price
+                </th>
+                <th className="text-left py-2 pr-4 text-neutral-400 font-medium">
+                  Sessions
+                </th>
+                <th className="text-left py-2 text-neutral-400 font-medium">
+                  Details
+                </th>
+              </tr>
+            </thead>
+            <tbody className="text-neutral-300">
+              <tr className="border-b border-neutral-800/50">
+                <td className="py-2 pr-4 font-medium">Free</td>
+                <td className="py-2 pr-4">$0</td>
+                <td className="py-2 pr-4">20 sessions/day</td>
+                <td className="py-2">
+                  No credit card required. Ideal for experimentation and
+                  personal projects.
+                </td>
+              </tr>
+              <tr className="border-b border-neutral-800/50">
+                <td className="py-2 pr-4 font-medium">Starter</td>
+                <td className="py-2 pr-4">$5/month</td>
+                <td className="py-2 pr-4">1,000 sessions/month</td>
+                <td className="py-2">
+                  For individual developers with moderate tracing needs.
+                </td>
+              </tr>
+              <tr>
+                <td className="py-2 pr-4 font-medium">Pro</td>
+                <td className="py-2 pr-4">$20/month</td>
+                <td className="py-2 pr-4">100,000 sessions/month</td>
+                <td className="py-2">
+                  For teams and production workloads with high trace volume.
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </section>
+
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">Session counting</h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          A session is equivalent to a single trace sent to the AgentLens API.
+          Each call to{" "}
+          <code className="text-emerald-400 font-mono text-xs bg-emerald-500/5 px-1.5 py-0.5 rounded">
+            POST /api/traces
+          </code>{" "}
+          that includes one trace counts as one session, regardless of how many
+          spans, decision points, or events are inside that trace.
+        </p>
+        <p className="text-neutral-400 leading-relaxed">
+          If you batch multiple traces in a single API call, each trace in the
+          batch counts as a separate session.
+        </p>
+      </section>
+
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">
+          Managing your subscription
+        </h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          To view your current plan, upgrade, downgrade, or manage payment
+          methods, go to{" "}
+          <strong className="text-neutral-200">
+            Settings &rarr; Billing
+          </strong>{" "}
+          in the dashboard. Changes take effect immediately. If you downgrade
+          mid-cycle, you retain access to the higher tier until the end of the
+          current billing period.
+        </p>
+      </section>
+
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">Self-hosted instances</h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          If you are running a self-hosted AgentLens instance, registration with
+          the hosted SaaS service is not required. Self-hosted deployments
+          manage their own authentication and have no session limits or billing
+          tiers. See the{" "}
+          <a
+            href="/docs/self-hosting"
+            className="text-emerald-400 hover:underline"
+          >
+            Self-Hosting guide
+          </a>{" "}
+          for setup instructions.
+        </p>
+      </section>
+    </div>
+  );
+}
--- a/apps/web/src/app/docs/getting-started/page.tsx
+++ b/apps/web/src/app/docs/getting-started/page.tsx
@@ -63,6 +63,39 @@ export default function GettingStartedPage() {
        </ul>
      </section>

+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">
+          Step 0: Create your account
+        </h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          Before you can send traces, you need an AgentLens account. Register
+          with your email and password at{" "}
+          <a
+            href="https://agentlens.vectry.tech/register"
+            className="text-emerald-400 hover:underline"
+          >
+            agentlens.vectry.tech/register
+          </a>
+          . Once registered, log in to the dashboard and navigate to{" "}
+          <strong className="text-neutral-200">Settings &rarr; API Keys</strong>{" "}
+          to generate your first API key.
+        </p>
+        <div className="px-4 py-3 rounded-lg bg-neutral-900/50 border border-neutral-800/50 mb-4">
+          <p className="text-sm text-neutral-400">
+            <strong className="text-neutral-300">Self-hosting?</strong>{" "}
+            If you are running your own AgentLens instance, you do not need to
+            register with the hosted service. See the{" "}
+            <a
+              href="/docs/self-hosting"
+              className="text-emerald-400 hover:underline"
+            >
+              Self-Hosting guide
+            </a>{" "}
+            instead.
+          </p>
+        </div>
+      </section>
+
      <section className="mb-12">
        <h2 className="text-2xl font-semibold mb-4">
          Step 1: Install the SDK
@@ -194,6 +227,57 @@ await trace.end();`}</CodeBlock>
        </a>
      </section>

+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">
+          Billing and session limits
+        </h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          Each trace you send counts as one session for billing purposes.
+          AgentLens cloud offers three tiers:
+        </p>
+        <div className="overflow-x-auto mb-4">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b border-neutral-800">
+                <th className="text-left py-2 pr-4 text-neutral-400 font-medium">Plan</th>
+                <th className="text-left py-2 pr-4 text-neutral-400 font-medium">Price</th>
+                <th className="text-left py-2 text-neutral-400 font-medium">Sessions</th>
+              </tr>
+            </thead>
+            <tbody className="text-neutral-300">
+              <tr className="border-b border-neutral-800/50">
+                <td className="py-2 pr-4">Free</td>
+                <td className="py-2 pr-4">$0</td>
+                <td className="py-2">20 sessions/day</td>
+              </tr>
+              <tr className="border-b border-neutral-800/50">
+                <td className="py-2 pr-4">Starter</td>
+                <td className="py-2 pr-4">$5/month</td>
+                <td className="py-2">1,000 sessions/month</td>
+              </tr>
+              <tr>
+                <td className="py-2 pr-4">Pro</td>
+                <td className="py-2 pr-4">$20/month</td>
+                <td className="py-2">100,000 sessions/month</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+        <p className="text-neutral-400 leading-relaxed">
+          Manage your subscription in{" "}
+          <strong className="text-neutral-200">Settings &rarr; Billing</strong>{" "}
+          in the dashboard. Self-hosted instances are not subject to these
+          limits. See{" "}
+          <a
+            href="/docs/authentication-billing"
+            className="text-emerald-400 hover:underline"
+          >
+            Authentication &amp; Billing
+          </a>{" "}
+          for full details.
+        </p>
+      </section>
+
      <section className="mb-12">
        <h2 className="text-2xl font-semibold mb-4">Next steps</h2>
        <div className="grid sm:grid-cols-2 gap-4">
--- a/apps/web/src/app/docs/page.tsx
+++ b/apps/web/src/app/docs/page.tsx
@@ -22,6 +22,12 @@ const sections = [
        description:
          "Understand Traces, Spans, Decision Points, and Events — the four building blocks of AgentLens.",
      },
+      {
+        title: "Authentication & Billing",
+        href: "/docs/authentication-billing",
+        description:
+          "Register for an account, manage API keys, and understand billing tiers and session limits.",
+      },
    ],
  },
  {
--- a/apps/web/src/app/docs/self-hosting/page.tsx
+++ b/apps/web/src/app/docs/self-hosting/page.tsx
@@ -14,6 +14,9 @@ export default function SelfHostingPage() {
      <p className="text-lg text-neutral-400 mb-10 leading-relaxed">
        AgentLens is open source and designed to be self-hosted. You can deploy
        it with Docker in minutes, or run from source for development.
+        Self-hosted instances do not require registration with the AgentLens
+        cloud service and are not subject to any session limits or billing
+        tiers.
      </p>

      <section className="mb-12">
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -74,7 +74,7 @@ services:
  migrate:
    build:
      context: .
-      target: builder
+      target: migrate
    command: npx prisma db push --schema=packages/database/prisma/schema.prisma --skip-generate
    environment:
      - DATABASE_URL=postgresql://${POSTGRES_USER:-agentlens}:${POSTGRES_PASSWORD:-agentlens}@postgres:5432/${POSTGRES_DB:-agentlens}
--- a/packages/opencode-plugin/README.md
+++ b/packages/opencode-plugin/README.md
@@ -8,6 +8,8 @@ OpenCode plugin for AgentLens — trace your coding agent's decisions, tool call
 ## Requirements

 - OpenCode >= 1.1.0
+- An AgentLens account -- register at [agentlens.vectry.tech/register](https://agentlens.vectry.tech/register)
+- An API key created in **Settings > API Keys** in the AgentLens dashboard

 ## Install

@@ -44,7 +46,7 @@ Add the plugin to your OpenCode configuration at `~/.config/opencode/opencode.js
 }
 ```

-Set your API key:
+Set your API key (create one at **Settings > API Keys** in the [AgentLens dashboard](https://agentlens.vectry.tech)):

 ```bash
 export AGENTLENS_API_KEY="your-api-key"
@@ -52,6 +54,8 @@ export AGENTLENS_API_KEY="your-api-key"

 The plugin activates automatically when OpenCode starts. No code changes required.

+Each OpenCode session counts as one trace (one session) for billing purposes. See the [billing documentation](https://agentlens.vectry.tech/docs/authentication-billing) for plan details.
+
 ## What Gets Captured

 The plugin hooks into OpenCode's event system and records:
--- a/packages/sdk-python/README.md
+++ b/packages/sdk-python/README.md
@@ -12,6 +12,8 @@ AgentLens is an observability SDK for AI agents. Unlike generic LLM tracing tool

 ## Quick Start

+First, create an account at [agentlens.vectry.tech/register](https://agentlens.vectry.tech/register) and generate an API key in **Settings > API Keys** in the dashboard.
+
 ```bash
 pip install vectry-agentlens
 ```
@@ -19,7 +21,7 @@ pip install vectry-agentlens
 ```python
 import agentlens

-# Initialize once at startup
+# Initialize with the API key from Settings > API Keys
 agentlens.init(api_key="your-api-key")

 # Trace any function with a decorator
@@ -160,7 +162,7 @@ Initialize the SDK. Call once at application startup.

 ```python
 agentlens.init(
-    api_key="your-api-key",           # Required. Your AgentLens API key.
+    api_key="your-api-key",           # Required. Create at Settings > API Keys in the dashboard.
    endpoint="https://...",            # API endpoint (default: https://agentlens.vectry.tech)
    flush_interval=5.0,               # Seconds between batch flushes (default: 5.0)
    max_batch_size=10,                 # Traces per batch before auto-flush (default: 10)
@@ -168,6 +170,8 @@ agentlens.init(
 )
 ```

+You can also set the API key via the `AGENTLENS_API_KEY` environment variable instead of passing it directly.
+
 ### `agentlens.trace()`

 Decorator or context manager that creates a trace (or a nested span if already inside a trace).
@@ -264,13 +268,25 @@ The SDK is lightweight and non-blocking. Traces are serialized and batched in a

 ## Dashboard

-View your traces at [agentlens.vectry.tech](https://agentlens.vectry.tech):
+View your traces at [agentlens.vectry.tech](https://agentlens.vectry.tech) (login required):

 - **Decision Trees** - Visualize the full decision path of every agent run
 - **Analytics** - Token usage, cost breakdowns, latency percentiles
 - **Real-time Streaming** - Watch agent decisions as they happen
 - **Session Grouping** - Track multi-turn conversations by session ID

+## Billing
+
+Each trace counts as one session for billing. AgentLens cloud offers three tiers:
+
+| Plan | Price | Sessions |
+|------|-------|----------|
+| Free | $0 | 20 sessions/day |
+| Starter | $5/month | 1,000 sessions/month |
+| Pro | $20/month | 100,000 sessions/month |
+
+Manage your subscription in **Settings > Billing**. Self-hosted instances have no session limits.
+
 ## Development

 ```bash
--- a/packages/sdk-ts/README.md
+++ b/packages/sdk-ts/README.md
@@ -13,10 +13,12 @@ npm install agentlens-sdk

 ## Quick Start

+First, create an account at [agentlens.vectry.tech/register](https://agentlens.vectry.tech/register) and generate an API key in **Settings > API Keys** in the dashboard.
+
 ```typescript
 import { init, TraceBuilder, shutdown } from "agentlens-sdk";

-// Initialize the SDK
+// Initialize with the API key from Settings > API Keys
 init({
  apiKey: "your-api-key",
  endpoint: "https://agentlens.vectry.tech/api",
@@ -104,17 +106,31 @@ Pass `InitOptions` to `init()`:

 ```typescript
 init({
-  apiKey: "your-api-key",       // Required. Your AgentLens API key.
+  apiKey: "your-api-key",       // Required. Create at Settings > API Keys in the dashboard.
  endpoint: "https://...",      // API endpoint. Defaults to AgentLens cloud.
  maxBatchSize: 100,            // Max items per batch before auto-flush.
  flushInterval: 5000,          // Auto-flush interval in milliseconds.
 });
 ```

+You can also set the API key via the `AGENTLENS_API_KEY` environment variable instead of passing it directly.
+
 ## Transport

 The SDK ships with `BatchTransport`, which batches payloads and flushes them on an interval or when the batch size threshold is reached. This is used internally by `init()` — you typically do not need to instantiate it directly.

+## Billing
+
+Each trace counts as one session for billing. AgentLens cloud offers three tiers:
+
+| Plan | Price | Sessions |
+|------|-------|----------|
+| Free | $0 | 20 sessions/day |
+| Starter | $5/month | 1,000 sessions/month |
+| Pro | $20/month | 100,000 sessions/month |
+
+Manage your subscription in **Settings > Billing**. Self-hosted instances have no session limits.
+
 ## Documentation

 Full documentation: [agentlens.vectry.tech/docs/typescript-sdk](https://agentlens.vectry.tech/docs/typescript-sdk)
Author	SHA1	Message	Date
Vectry	2c83b945ab	feat: auto-create Gitea releases on tag push and fix PyPI publish venv All checks were successful Publish npm packages / publish (push) Successful in 56s Details Deploy AgentLens / deploy (push) Successful in 1m50s Details Publish PyPI package / publish (push) Successful in 18s Details	2026-02-11 00:43:36 +00:00
Vectry	32ed6e3f1d	docs: update all documentation for subscription auth, billing tiers, and API key management Some checks failed Publish npm packages / publish (push) Successful in 50s Details Publish PyPI package / publish (push) Failing after 3s Details Deploy AgentLens / deploy (push) Successful in 1m21s Details	2026-02-11 00:35:51 +00:00
Vectry	9e6f6337c0	feat: add CI/CD workflows for npm and PyPI auto-publish on tag Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-Claude) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>	2026-02-11 00:33:24 +00:00
Vectry	f4185364d5	fix: use correct package name @agentlens/web in turbo filter All checks were successful Deploy AgentLens / deploy (push) Successful in 1m19s Details	2026-02-11 00:02:00 +00:00
Vectry	860159ccd0	fix: use turbo --filter=web... to skip sdk-ts build in Docker Some checks failed Deploy AgentLens / deploy (push) Failing after 9s Details The builder stage was running 'npx turbo build' which builds ALL workspace packages including sdk-ts (needs tsup). The web app only depends on @agentlens/database, not sdk-ts. Using --filter=web... builds only web and its transitive dependencies.	2026-02-10 23:57:47 +00:00
Vectry	b21d8fe52c	fix: add lightweight migrate Dockerfile target to avoid tsup build failure in CI Some checks failed Deploy AgentLens / deploy (push) Failing after 9s Details The migrate service only needs Prisma CLI to run 'prisma db push'. Previously it used the 'builder' target which runs 'npx turbo build' (including sdk-ts needing tsup), causing failures in fresh CI builds over TCP where Docker cache is unavailable. New 'migrate' target copies only node_modules and prisma schema.	2026-02-10 23:56:09 +00:00
Vectry	c6fa25ed47	fix: skip Docker install, use pre-installed CLI from runner image Some checks failed Deploy AgentLens / deploy (push) Failing after 6s Details	2026-02-10 23:38:45 +00:00
Vectry	0e97c23579	fix: use TCP docker host, fix heredoc whitespace, fix health checks in deploy workflow	2026-02-10 23:31:18 +00:00
Vectry	865a1b0081	Fix deploy workflow: use ubuntu-latest with Docker CLI install	2026-02-10 23:22:06 +00:00
Vectry	b3e5119568	Add Gitea Actions deploy-on-tag workflow	2026-02-10 23:18:53 +00:00