# Instagit Anonymous Token Limitations and Upgrade Guide

> Discover Instagit anonymous token limitations including IP restrictions and credit sharing. Upgrade easily using INSTAGIT_API_KEY to remove all limits and access full features.

- Repository: [Instalabs AI/instagit](https://github.com/instalabsai/instagit)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Instagit’s anonymous token system restricts users to three tokens per IP address, shared free-tier credits, and a 2 GB repository limit, but upgrading to a paid plan via the `INSTAGIT_API_KEY` environment variable removes these restrictions entirely.**

The `instalabsAI/instagit` repository provides a Model Context Protocol (MCP) server for AI-powered Git repository analysis. While the tool offers an anonymous token mode for quick experimentation, production use requires understanding its hard limits and the upgrade path to authenticated API access.

## How Instagit’s Anonymous Token System Works

Instagit operates in two distinct authentication modes, controlled primarily by the presence of an API key.

### Anonymous Token Registration

When no API key is present, the client automatically requests a temporary token via the `registerAnonymousToken` function in [`src/token.ts`](https://github.com/instalabsAI/instagit/blob/main/src/token.ts) (lines 60-78). This function sends a `POST /v1/auth/anonymous` request to the Instagit API, creating a token bound to the requesting IP address.

### API Key Authentication

Paid users bypass the anonymous flow entirely. The `getOrCreateToken` function in [`src/token.ts`](https://github.com/instalabsAI/instagit/blob/main/src/token.ts) (lines 45-55) checks for the `INSTAGIT_API_KEY` environment variable first. If present, it returns the key directly, skipping registration and removing all anonymous-tier limitations.

## Instagit Anonymous Token Limitations

The anonymous system imposes three specific hard caps designed to prevent abuse of the free tier.

### 3-Token-per-IP Cap

The server enforces a strict limit of three anonymous tokens per public IP address. When a fourth registration attempt occurs from the same IP, the API refuses the request. This error handling is implemented in [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) (lines 99-107), where the server returns a specific error message directing users to upgrade.

### Shared Free-Tier Credit Pool

Anonymous tokens draw from a communal pool of free credits. When this pool is exhausted, the API returns **HTTP 429 Rate-Limited**. The client handles this in [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) (lines 48-66) by displaying an upgrade hint pointing to the pricing page. This is not a per-user limit but a global resource shared across all anonymous users.

### 2 GB Repository Size Ceiling

The free tier rejects repositories larger than 2 GB, returning **HTTP 413 Payload Too Large**. This limit prevents excessive bandwidth consumption on the shared infrastructure. Paid plans remove this ceiling entirely, with the **Max** plan specifically advertising unlimited repository sizes.

## How to Upgrade from Anonymous Tokens

Upgrading requires obtaining an API key from the Instagit dashboard and configuring your environment.

Set the `INSTAGIT_API_KEY` environment variable to your paid key:

```bash
export INSTAGIT_API_KEY="sk_live_..."

```

The **Pro** plan ($20/month) provides 10× more credits than the free tier, while the **Max** plan removes repository size limits entirely. Once the key is set, `getOrCreateToken` in [`src/token.ts`](https://github.com/instalabsAI/instagit/blob/main/src/token.ts) automatically uses it, bypassing all anonymous limitations.

## Code Examples

### Using an Explicit API Key in Production

```typescript
// Set the environment variable before importing Instagit
process.env.INSTAGIT_API_KEY = "sk_live_…"; // replace with your real key

import { getOrCreateToken } from "./token.js";

const token = getOrCreateToken(); // returns the API key directly
console.log("Using paid token:", token);

```

This approach works because `getOrCreateToken` checks `process.env.INSTAGIT_API_KEY` first (lines 45-48 of [`src/token.ts`](https://github.com/instalabsAI/instagit/blob/main/src/token.ts)), skipping the anonymous registration flow entirely.

### Handling the 3-Token-per-IP Error

```typescript
import { registerAnonymousToken } from "./token.js";

async function obtainToken(apiUrl: string) {
  const token = await registerAnonymousToken(apiUrl);
  if (!token) {
    console.error(
      "Reached the 3-anonymous-token limit. " +
      "Create an account and set INSTAGIT_API_KEY to continue."
    );
    return null;
  }
  return token;
}

```

This mirrors the error handling logic found in [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) (lines 99-107), providing a clear path to resolution when the IP limit is reached.

### Detecting Rate Limit Responses

```typescript
import { analyzeRepoStreaming } from "./api.js";

try {
  await analyzeRepoStreaming({ repo, prompt, token });
} catch (err: any) {
  if (err.status === 429) {
    console.log(
      "Free credits exhausted. Upgrade to Pro for more credits: " +
      "https://app.instagit.com/pricing"
    );
  }
}

```

The server surfaces rate limits via HTTP 429, as handled in [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) (lines 48-66), often including an `upgradeHint` field in the response.

## Summary

- **Anonymous tokens** are auto-generated via `registerAnonymousToken` in [`src/token.ts`](https://github.com/instalabsAI/instagit/blob/main/src/token.ts) but impose strict limits: 3 tokens per IP, shared credit pools, and 2 GB repo caps.
- **Rate limiting** (HTTP 429) occurs when the global free credit pool is exhausted, handled in [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts).
- **Upgrading** requires setting `INSTAGIT_API_KEY`, which causes `getOrCreateToken` to bypass anonymous registration entirely, removing all limits.
- **Pro and Max plans** offer 10× credits and unlimited repository sizes, respectively.

## Frequently Asked Questions

### What happens when I hit the 3-token-per-IP limit in Instagit?

When you attempt to register a fourth anonymous token from the same public IP address, the API refuses the request and the client displays an error message directing you to create an account. As implemented in [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) (lines 99-107), this hard cap prevents abuse of the free tier and can only be bypassed by upgrading to a paid API key.

### How do I know if Instagit has run out of free credits?

The API returns an **HTTP 429 Rate-Limited** status when the shared free-tier credit pool is exhausted. The client catches this in [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) (lines 48-66) and prints a message suggesting an upgrade to the Pro plan. Unlike per-user limits, this indicates global pool depletion that affects all anonymous users simultaneously.

### Can I use Instagit with large repositories on the free tier?

No. The anonymous token system enforces a **2 GB repository size limit**, returning **HTTP 413 Payload Too Large** for bigger repositories. This ceiling is removed only on paid plans, with the **Max** plan specifically offering unlimited repository sizes. To analyze larger repos, you must set the `INSTAGIT_API_KEY` environment variable with a paid key.

### Where should I store my Instagit API key for production use?

Set the `INSTAGIT_API_KEY` environment variable before starting the Instagit server. The `getOrCreateToken` function in [`src/token.ts`](https://github.com/instalabsAI/instagit/blob/main/src/token.ts) (lines 45-55) checks this variable first and returns it directly, completely bypassing the anonymous token flow. While you can manually store keys in `~/.instagit/token.json`, environment variables are the recommended approach for production deployments.