How to Configure HTTP Sources Alongside the Main Git Team Repo in TeamAI

TeamAI supports a hybrid setup where a local Git repository serves as the canonical source while a secondary HTTP endpoint provides supplementary skills and rules via teamai source add-http.

The Tencent TeamAI CLI allows developers to combine version-controlled Git repositories with read-only HTTP endpoints for flexible knowledge management. When you configure HTTP sources alongside the main Git team repo in TeamAI, you create a fallback mechanism where the CLI checks local Git assets first, then queries the HTTP service for missing skills or rules. This architecture is implemented in the src/config.ts and src/source.ts modules of the open-source repository.

Understanding TeamAI Source Architecture

TeamAI consumes knowledge from two distinct source types that operate in a hierarchical relationship.

Git Repository (Primary Source)

The Git repository remains the canonical source for your team's skills, rules, and documents. Initialized via teamai init <git-url> or teamai init --repo <url>, this source is cloned locally and version-controlled. According to the configuration schema in src/config.ts, the repository kind is defined as "git" in the repo.kind field.

HTTP Source (Secondary Supplement)

An HTTP source provides read-only access to JSON payloads matching the TeamAI contract, fetched via authenticated GET requests. This source type is ideal for "team-as-a-service" deployments where shared assets live on a remote API rather than in Git. The CLI stores HTTP credentials in the httpSource object within ~/.teamai/config.json, as defined in src/config.ts, and transmits the token via the Authorization: Bearer <api-key> header.

Adding an HTTP Source to Your Git Repository

You can supplement your main Git repository with exactly one HTTP source using the CLI commands implemented in src/source.ts.

Prerequisites

• An active Git repository initialized with teamai init
• An HTTP endpoint exposing the TeamAI HTTP contract
• A valid API key for Bearer token authentication

Step-by-Step Configuration

1. Initialize the Git repository (if not already done):

   teamai init https://github.com/yourorg/yourrepo.git

2. Add the HTTP source with authentication:

   teamai source add-http https://your-team-host/api --token <api-key>

   • Replace https://your-team-host/api with your endpoint base URL
   • Replace <api-key> with your service authentication token
   • The CLI validates that no existing HTTP source is configured before proceeding

3. Verify the configuration:

   teamai source list

   You should see output similar to:

   
   HTTP source: https://your-team-host/api
   

Configuration File Structure and Schema

TeamAI persists source settings in ~/.teamai/config.json, or the path specified by the TEAMAI_CONFIG environment variable. The configuration schema, defined in src/config.ts, supports hybrid mode through the following structure:

{
  "repo": {
    "kind": "git",
    "httpsUrl": "https://github.com/owner/repo.git"
  },
  "httpSource": {
    "endpoint": "https://your-team-host/api",
    "token": "********"
  }
}

Key constraints enforced by the configuration logic:

• When repo.kind is "git", the httpSource object is optional and can be added or removed anytime
• When repo.kind is "http", the httpSource field is prohibited because the main repository already occupies the HTTP slot

Source Resolution and Fallback Behavior

During runtime, TeamAI resolves skills and rules using a specific priority order implemented in the CLI's dispatch mechanism. First, the system checks the local Git clone for requested assets. If the asset is not present locally, the CLI falls back to polling the configured HTTP source via the hook-dispatch mechanism. This ensures that private or experimental skills in your Git repository override shared HTTP assets while maintaining access to centralized resources.

Managing and Removing HTTP Sources

You can manage your HTTP source configuration using the following commands from src/source.ts:

• List sources: teamai source list displays both Git and HTTP configurations
• Remove HTTP source: teamai source remove-http deletes the HTTP configuration while preserving the Git repository
• Replace HTTP source: Run teamai source add-http again with new parameters; the CLI implicitly uses --force to overwrite the existing entry

Limitations of HTTP Source Configuration

TeamAI enforces strict constraints on HTTP source configuration to prevent conflicts:

• Single source limit: Only one HTTP source can exist per installation. The validation logic in src/source.ts enforces this rule during the add-http command.
• Mutual exclusivity: If you initialize the main repository in HTTP mode using teamai init --http <baseUrl>, the add-http command becomes disabled. In this configuration, the repo.kind field is set to "http" and the system operates in HTTP-only mode, as guarded by src/read-only.ts.

Summary

• Configure HTTP sources alongside your Git repository using teamai source add-http <endpoint> --token <key>
• The CLI stores settings in ~/.teamai/config.json with schema defined in src/config.ts
• Git assets take precedence over HTTP assets during skill resolution
• Only one HTTP source is permitted; HTTP-only mode (init with --http) disables supplementary HTTP sources
• Remove HTTP sources with teamai source remove-http to revert to Git-only operation

Frequently Asked Questions

Can I use multiple HTTP sources with one Git repository?

No. According to the implementation in src/source.ts, TeamAI restricts installations to a single HTTP source when operating in hybrid mode. If you need to aggregate multiple HTTP endpoints, you must proxy them through a single service or switch the main repository to HTTP mode using teamai init --http.

What happens if the same skill exists in both Git and HTTP sources?

The Git repository serves as the canonical source. The CLI checks the local Git clone first during the resolution process. Only if the asset is missing locally does it query the HTTP endpoint configured in the httpSource object.

Is the HTTP source configuration stored securely?

The configuration file at ~/.teamai/config.json stores the API token in plain text (shown as masked asterisks in CLI output). You should set appropriate filesystem permissions (600) on this file or use the TEAMAI_CONFIG environment variable to relocate it to a secure secrets management system.

Why is the add-http command disabled after running teamai init --http?

When you initialize with teamai init --http, the repo.kind field is set to "http" and the main repository itself becomes an HTTP source. Since TeamAI enforces a single HTTP source limit, the add-http command is disabled to prevent configuration conflicts, as validated in both src/source.ts and src/read-only.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}