Umans Code User Guide

Quick Start (Recommended)

The fastest way to get started is with the Umans CLI. It handles authentication and launches Claude Code with zero configuration.

macOS & Linux

# Install the CLI (one-time)
curl -fsSL https://api.code.umans.ai/cli/install.sh | bash

# Launch Claude Code with Umans backend
umans claude

First run: The CLI opens your browser for authentication. Log in to your Umans account, and the CLI automatically receives your API key. Claude Code launches immediately with the Umans backend configured.

Subsequent runs: umans claude launches instantly using your saved credentials.

CLI Commands

umans claude                          # Launch Claude Code (default: umans-coder)
umans claude --model umans-kimi-k2.6      # Use native Kimi K2.6 (next default after validation)
umans claude --model umans-glm-5.1        # Use GLM 5.1 with vision handoff
umans claude --websearch native           # Gateway websearch: Kimi-backed path
umans claude --websearch exa              # Gateway websearch: Exa-backed path
umans opencode                       # Launch OpenCode with Umans backend
umans opencode --model umans-glm-5.1      # Use GLM 5.1 on OpenCode
umans status                         # Check authentication status
umans logout                         # Remove saved credentials
umans --help                         # Show all available commands

Manual Configuration (Alternative)

If the CLI does not work for your setup (Windows users, custom environments) or you prefer to configure tools manually, use these settings:

API Endpoint

Getting Your API Key

1. Log in to app.umans.ai/billing
2. Go to your Dashboard → API Keys
3. Generate a new key (shown only once - copy it immediately)

Tool-Specific Setup

umans claude                              # Default: umans-coder (Kimi K2.5)
umans claude --model umans-kimi-k2.6      # Use native Kimi K2.6 (next default after validation)
umans claude --model umans-glm-5.1        # GLM 5.1 with vision handoff
umans claude --websearch native           # Gateway websearch: Kimi-backed path
umans claude --websearch exa              # Gateway websearch: Exa-backed path

export ANTHROPIC_BASE_URL=https://api.code.umans.ai
export ANTHROPIC_AUTH_TOKEN=sk-your-umans-api-key
claude --model umans-coder

umans opencode                          # Default: umans-coder
umans opencode --model umans-kimi-k2.5  # Use native Kimi K2.5
umans opencode --model umans-kimi-k2.6  # Use native Kimi K2.6
umans opencode --model umans-glm-5.1    # Use GLM 5.1

{
  "$schema": "https://opencode.ai/config.json",
  "model": "umans/umans-coder",
  "provider": {
    "umans": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Umans AI",
      "options": {
        "baseURL": "https://api.code.umans.ai/v1",
        "apiKey": "sk-your-umans-api-key"
      },
      "models": {
        "umans-coder": {
          "id": "umans-coder",
          "name": "Umans Coder",
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "umans-kimi-k2.5": {
          "id": "umans-kimi-k2.5",
          "name": "Umans Kimi K2.5",
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "umans-kimi-k2.6": {
          "id": "umans-kimi-k2.6",
          "name": "Umans Kimi K2.6",
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "umans-glm-5.1": {
          "id": "umans-glm-5.1",
          "name": "Umans GLM 5.1",
          "modalities": { "input": ["text"], "output": ["text"] }
        }
      }
    }
  }
}

{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "umans": {
      "type": "anthropic",
      "base_url": "https://api.code.umans.ai",
      "api_key": "sk-your-umans-api-key",
      "models": [
        {
          "id": "umans-coder",
          "name": "Umans Coder",
          "default_max_tokens": 50000,
          "can_reason": true
        },
        {
          "id": "umans-kimi-k2.5",
          "name": "Umans Kimi K2.5",
          "default_max_tokens": 50000,
          "can_reason": true
        },
        {
          "id": "umans-kimi-k2.6",
          "name": "Umans Kimi K2.6",
          "default_max_tokens": 50000,
          "can_reason": true
        },
        {
          "id": "umans-glm-5.1",
          "name": "Umans GLM 5.1",
          "default_max_tokens": 50000,
          "can_reason": true
        }
      ]
    }
  }
}

Desktop App with Umans

Prefer a GUI over the terminal? Try OpenCode Desktop. It is open-source and talks to any OpenAI-compatible backend, which is the kind of tool we enjoy working with.

The models we serve are open-weight too, so your whole stack stays open and auditable. Nothing here is designed to lock you in.

One-command setup

The fastest path: run the CLI setup once and OpenCode Desktop picks up the Umans provider automatically.

# Install the Umans CLI (one-time)
curl -fsSL https://api.code.umans.ai/cli/install.sh | bash

# Write the Umans provider into OpenCode's global config
umans opencode --setup

This writes to ~/.config/opencode/opencode.json (or $XDG_CONFIG_HOME/opencode/opencode.json if set). Launch OpenCode Desktop and select any umans/* model from the model picker.

Manual configuration

If you'd rather edit the config file yourself, use the JSON snippet from Tool-Specific Setup → OpenCode.

Code from Your Phone

Keep a long-running agent working on your main machine and drive it from your phone over a secure private network. The stack is four pieces that each do one thing well:

• tmux: persistent terminal sessions that survive disconnects.
• Tailscale: zero-config mesh VPN; your machine gets a private 100.x.x.x IP reachable only from your own devices. No port-forwarding.
• Termius: mobile SSH client with proper key handling and a touchscreen-friendly terminal.
• umans claude: your agent, running inside the tmux session.

Based on Emre Işık's walkthrough: Code from your phone like a boss.

1. Prepare your machine (macOS / Linux)

# Install tmux, Tailscale, and the Umans CLI
brew install tmux tailscale
curl -fsSL https://api.code.umans.ai/cli/install.sh | bash

# Sign in to Tailscale and note your IP (100.x.x.x)
sudo tailscale up
tailscale ip -4

Sane tmux defaults (optional):

cat > ~/.tmux.conf <<'EOF'
set -s escape-time 1
set -g mouse on
set -g default-terminal "screen-256color"
set -g history-limit 10000
set -g base-index 1
setw -g pane-base-index 1
EOF

2. Enable SSH

• macOS: System Settings → General → Sharing → enable Remote Login.
• Linux: sudo systemctl enable --now ssh.
• Verify locally: ssh yourusername@localhost.

3. Add a reattach-or-create helper

Add this to ~/.zshrc (or ~/.bashrc) so one command always drops you back into the same session:

function umans-tmux() {
  if tmux has-session -t umans 2>/dev/null; then
    tmux attach -t umans
  else
    tmux new -s umans 'umans claude'
  fi
}

4. Connect from your phone

1. Install the Tailscale app on your phone and sign in with the same account.
2. Install Termius (or any SSH client you prefer).
3. Add a new host in Termius:
   • Host: your Tailscale IP (100.x.x.x)
   • Username: your machine username
   • Port: 22
4. Connect, then run umans-tmux.

5. Survive every disconnect

• Ctrl+b then d detaches the session. The agent keeps running.
• Reconnect later from anywhere and run umans-tmux again to reattach exactly where you left off.
• tmux list-sessions shows every session, including detached ones.

Personal Assistants (Telegram, WhatsApp, Discord)

Drive Umans from the chat apps you already live in. Tools like AutoClaw expose Telegram, WhatsApp, and Discord channels that you can wire up to any OpenAI-compatible model, including Umans.

Configure Umans as the model

Open the app's Settings → Models & API, click Add Model, and fill in:

Click Connectivity Test to verify the endpoint, then Save. Any Umans model works here: swap umans-coder for umans-kimi-k2.6 or umans-glm-5.1 if you prefer.

Connect a channel

Follow the app's own instructions to connect Telegram, WhatsApp, or Discord. Once a channel is linked and Umans is selected as the model, messages you send in that channel are handled by the assistant running locally on your machine.

API Reference

curl -N -X POST https://api.code.umans.ai/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-your-umans-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "umans-coder",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 4096,
    "stream": true
  }'

curl -N -X POST https://api.code.umans.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-umans-api-key" \
  -d '{
    "model": "umans-coder",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

Models

Available Models

* Today, umans-coder routes to Kimi K2.5. This may change as we continuously evaluate models. Read more at blog.umans.ai.

How to Choose

• Use umans-coder (default) to let us choose the best model for you. We continuously evaluate and select what works best for most coding tasks. Today this is Kimi K2.5.
• Use umans-kimi-k2.5 when you specifically want native Kimi K2.5. Overall best experience. It leads benchmarks on vision-heavy workflows and document understanding tasks.
• Use umans-kimi-k2.6 when you specifically want native Kimi K2.6. It becomes the default once validation is complete.
• Use umans-glm-5.1 when you want GLM 5.1 behind the Umans route. Well-suited for text-first coding workflows.

Benchmark Comparison

We believe in transparency. Select a benchmark below to see how our served models compare across different capabilities. Our open-weight models match (and often beat) frontier closed labs on agentic coding and research.

Model Information API

For programmatic access to current model information, including context windows, pricing, and capabilities:

curl https://api.code.umans.ai/v1/models/info | jq

This public endpoint returns up-to-date information about all available models, their capabilities, and current pricing.

Web Search

When your agent needs to look something up, the gateway runs the search itself and hands the results back to the model. These calls show up in your usage breakdown next to model requests, with the chosen backend in the Served column.

Backends

Choosing a backend

Set it once per Claude Code session via the CLI:

umans claude --websearch native    # Kimi-backed
umans claude --websearch exa       # Exa-backed

Or set it per request when calling the API directly:

X-Umans-Websearch-Provider: native
X-Umans-Websearch-Provider: exa

If neither is set, the gateway uses its environment default. The override only takes effect on requests that actually carry a web search tool, and only on routes where the gateway owns the search step (some upstream models run search themselves, in which case the header is moot).

What we record

Only usage metrics: the bucket timestamp, requested model alias, served backend, route, status, and token counts. We do not store the search query, the results, or anything from your conversation. The gateway also does not log per-call payloads in production logs.

Troubleshooting

FAQ

Support

Need help?