> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipe: Remote Server for Teams

> Step-by-step guide to setting up a centralized ChatCLI server for your entire team, with authentication, TLS, and multiple providers.

In this recipe, you will set up a centralized ChatCLI server that serves the entire development team. Each member can connect from their terminal and use the AI without needing to manage individual API keys.

***

## Scenario

<CardGroup cols={2}>
  <Card title="Small Team" icon="users">
    5-10 developers sharing resources
  </Card>

  <Card title="Corporate API Keys" icon="key">
    Central server with managed keys
  </Card>

  <Card title="Terminal Access" icon="terminal">
    Each dev connects from their local terminal
  </Card>

  <Card title="Flexible Authentication" icon="shield-halved">
    Shared token or individual credentials
  </Card>
</CardGroup>

***

<Steps>
  <Step title="Configure the Server">
    <Tabs>
      <Tab title="Docker Compose (Simple)">
        Create a `.env` file on the server:

        ```bash theme={"system"}
        # .env
        CHATCLI_SERVER_TOKEN=team-token-2024
        LLM_PROVIDER=CLAUDEAI
        ANTHROPIC_API_KEY=sk-ant-xxx-corporate-key
        ANTHROPIC_MODEL=claude-sonnet-4-6
        LOG_LEVEL=info
        ```

        Start with Docker Compose:

        ```bash theme={"system"}
        docker compose up -d
        ```
      </Tab>

      <Tab title="Direct Binary">
        ```bash theme={"system"}
        export CHATCLI_SERVER_TOKEN=team-token-2024
        export LLM_PROVIDER=CLAUDEAI
        export ANTHROPIC_API_KEY=sk-ant-xxx
        chatcli server --port 50051
        ```
      </Tab>

      <Tab title="Kubernetes (Helm)">
        ```bash theme={"system"}
        helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
          --namespace tools --create-namespace \
          --set llm.provider=CLAUDEAI \
          --set secrets.anthropicApiKey=sk-ant-xxx \
          --set server.token=team-token-2024 \
          --set service.type=LoadBalancer
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Distribute Access">
    Share with the team:

    ```bash theme={"system"}
    # Add to each dev's .bashrc or .zshrc
    export CHATCLI_REMOTE_ADDR=ai-server:50051
    export CHATCLI_REMOTE_TOKEN=team-token-2024

    # Alias for quick access
    alias cia='chatcli connect'
    ```
  </Step>

  <Step title="Each Dev Connects">
    ```bash theme={"system"}
    # Interactive mode
    chatcli connect

    # Quick one-shot
    chatcli connect -p "Explain the Repository pattern in Go"
    ```
  </Step>

  <Step title="Allow Individual Credentials (Optional)">
    Devs who prefer to use their own credentials can do so:

    ```bash theme={"system"}
    # Dev who has a Claude Pro subscription
    chatcli connect --use-local-auth

    # Dev who prefers OpenAI
    chatcli connect --provider OPENAI --llm-key sk-my-personal-key

    # Dev who uses GitHub Copilot
    chatcli connect --use-local-auth --provider COPILOT
    ```

    <Info>
      The server accepts both modes simultaneously. Devs can use the server credentials (default) or provide their own.
    </Info>
  </Step>

  <Step title="Add TLS (Production)">
    For production environments, add TLS:

    ```bash theme={"system"}
    # Generate certificates (e.g., with Let's Encrypt or certbot)
    # Or use mkcert for development

    # Start with TLS
    chatcli server \
      --tls-cert /etc/chatcli/cert.pem \
      --tls-key /etc/chatcli/key.pem \
      --token team-token-2024
    ```

    Devs connect with:

    ```bash theme={"system"}
    chatcli connect server:50051 --tls --token team-token-2024
    ```
  </Step>

  <Step title="Multiple Providers">
    Configure the server with multiple API keys. Devs can choose the provider:

    ```bash theme={"system"}
    # Server with OpenAI, Claude, Google AI, and Copilot
    export OPENAI_API_KEY=sk-xxx
    export ANTHROPIC_API_KEY=sk-ant-xxx
    export GOOGLEAI_API_KEY=AIzaSy-xxx
    export GITHUB_COPILOT_TOKEN=ghu_xxx  # or use /auth login github-copilot
    export LLM_PROVIDER=CLAUDEAI  # default
    chatcli server
    ```

    ```bash theme={"system"}
    # Dev chooses the provider
    chatcli connect --provider OPENAI
    chatcli connect --provider GOOGLEAI
    chatcli connect --provider COPILOT --use-local-auth
    chatcli connect  # uses the default (CLAUDEAI)
    ```
  </Step>

  <Step title="Share Agents, Skills, and Plugins (Optional)">
    Provision agents, skills, and plugins on the server so the entire team has access to the same resources:

    <Tabs>
      <Tab title="Via Helm">
        ```bash theme={"system"}
        helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
          --namespace tools --create-namespace \
          --set llm.provider=CLAUDEAI \
          --set secrets.anthropicApiKey=sk-ant-xxx \
          --set server.token=team-token-2024 \
          --set agents.enabled=true \
          --set-file agents.definitions.devops-senior\\.md=agents/devops-senior.md \
          --set skills.enabled=true \
          --set-file skills.definitions.k8s-best-practices\\.md=skills/k8s-best-practices.md \
          --set plugins.enabled=true \
          --set plugins.initImage=myregistry/chatcli-plugins:latest
        ```
      </Tab>

      <Tab title="Via ConfigMaps">
        ```bash theme={"system"}
        # Create ConfigMap with agents
        kubectl create configmap chatcli-agents \
          --from-file=devops-senior.md=agents/devops-senior.md \
          --from-file=go-expert.md=agents/go-expert.md \
          -n tools

        # Reference in Helm
        helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
          --set agents.enabled=true \
          --set agents.existingConfigMap=chatcli-agents
        ```
      </Tab>

      <Tab title="Via Skill Registry">
        In addition to provisioning skills via ConfigMaps, you can enable the **Skill Registry** to search and install skills from remote registries directly on the server:

        ```bash theme={"system"}
        helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
          --set skillRegistry.enabled=true \
          --set skillRegistry.registryUrls="https://skills.mycompany.com/api/v1"
        ```

        After connecting to the server, use the `/skill` commands to manage skills:

        ```bash theme={"system"}
        /skill search kubernetes     # Search across all registries
        /skill install k8s-ops       # Install on the server
        /agent skills                # Verify the skill is available
        ```
      </Tab>
    </Tabs>

    When devs connect, they automatically see the server resources:

    ```text theme={"system"}
    Connected to ChatCLI server (version: 1.3.0, provider: CLAUDEAI, model: claude-sonnet-4-6)
     Server has 2 plugins, 2 agents, 3 skills available
    ```
  </Step>
</Steps>

***

## Operational Tips

<AccordionGroup>
  <Accordion title="Server Logs">
    ```bash theme={"system"}
    # Docker
    docker logs chatcli-server -f

    # Kubernetes
    kubectl logs -f deployment/chatcli -n tools
    ```
  </Accordion>

  <Accordion title="Health Check">
    ```bash theme={"system"}
    # The Dockerfile includes a built-in health check
    docker inspect chatcli-server --format='{{.State.Health.Status}}'
    ```
  </Accordion>

  <Accordion title="Usage Monitoring">
    Set `LOG_LEVEL=info` on the server to log each request with the provider and model used.
  </Accordion>

  <Accordion title="Session Backup">
    ```bash theme={"system"}
    # Docker: persistent volumes
    docker cp chatcli-server:/home/chatcli/.chatcli/sessions ./backup/

    # Kubernetes: PVC already configured in the Helm chart
    ```
  </Accordion>

  <Accordion title="Remote Sessions">
    When connected to a server, the `/session` commands interact with **both** local and remote:

    * **`/session save`** asks where to save: local, remote, or both
    * **`/session list`** displays sessions from both in separate sections
    * **`/session load`** searches both; if found in both, asks which one to load
    * **`/session delete`** checks both; if found in both, asks which one to remove

    This allows devs to save sessions on the server to share with the team, or locally for offline use.
  </Accordion>
</AccordionGroup>

***

## Summary

| Component     | Configuration                                                                       |
| ------------- | ----------------------------------------------------------------------------------- |
| Server        | `chatcli server --token X`                                                          |
| Client        | `chatcli connect --token X`                                                         |
| Env Vars      | `CHATCLI_REMOTE_ADDR`, `CHATCLI_REMOTE_TOKEN`                                       |
| TLS           | `--tls-cert`, `--tls-key` (server) / `--tls` (client)                               |
| Credentials   | Server (default) or client (`--llm-key` / `--use-local-auth`)                       |
| Agents/Skills | `agents.enabled=true` + ConfigMap (Helm) or `agents.configMapRef` (Operator)        |
| Plugins       | `plugins.enabled=true` + init container or PVC (Helm) or `plugins.image` (Operator) |