Umans Code User Guide

Quick Start

Pick the tool you already use. Setup is one command or two env vars. Every tab links to its full walkthrough in Tool Setup.

OpenCodeClaude CodeπPiompDeepSeek HarnessCursorZedCrushAny other tool

OpenCode

Zero config

Umans AI Coding Plan is listed on models.dev, so OpenCode finds it natively. Add it under Providers and paste your key.

OpenCode · Providers

Umans AI Coding PlanAPI key

Connected

Or via the CLI: umans opencode

Full setup

Install the umans CLI

The OpenCode, Claude Code, and omp paths use the umans CLI. On first run it opens your browser to authenticate and saves your API key. After that, launches are instant.

curl -fsSL https://api.code.umans.ai/cli/install.sh | bash

CLI Commands

umans claude                              # Launch Claude Code (default: umans-coder, our current pick)
umans claude --model umans-kimi-k3        # Kimi K3: 1M context, native vision, max reasoning by default
umans claude --model umans-deepseek-v4-pro-0813  # DeepSeek V4 Pro: the long-context coding flagship (1M context, high reasoning by default)
umans claude --model umans-glm-5.3        # GLM 5.3: Z.ai's flagship coding model (1M context, always thinks)
umans claude --model umans-deepseek-v4-flash-0731  # DeepSeek V4 Flash: the cheapest production model
umans claude --model umans-flash          # Light, high-interactivity complement (Qwen3.6-35B-A3B-FP8)
umans claude --websearch native           # Umans web search: Kimi-backed path
umans claude --websearch exa              # Umans web search: Exa-backed path
umans claude --websearch none             # Disable server-side search; pass your own web_search tool through
umans opencode                            # Launch OpenCode with Umans backend
umans opencode --model umans-kimi-k3      # Use Kimi K3 on OpenCode
umans opencode --model umans-deepseek-v4-pro-0813  # Use DeepSeek V4 Pro on OpenCode
umans opencode --model umans-glm-5.3      # Use GLM 5.3 on OpenCode
umans opencode --model umans-deepseek-v4-flash-0731  # Use DeepSeek V4 Flash on OpenCode
umans opencode --model umans-flash        # Use umans-flash on OpenCode
umans omp                                 # Launch omp (Oh My Pi) with Umans backend
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 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)

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

* umans-coder routes to our current pick, which changes as we evaluate models. The live target is always listed on GET /v1/models/info.

Read more at blog.umans.ai.

Model IDs, exactly

Every model has one exact ID, starting with umans-, like umans-coder or umans-kimi-k3. The live list is always at GET /v1/models.

Using Claude Code or an Anthropic-style tool? Its claude-* names keep working out of the box. The mapping:

Typo or wrong ID? You get a clear 400 Unknown model error that lists the valid IDs, and when you are one character off it suggests the one you probably meant (for example kimi-k3 → umans-kimi-k3).

How to Choose

• Use umans-kimi-k3 for repository-scale work: the 1M context window reads a whole repo (or a whole spec tree) in one pass, native vision takes screenshots and diagrams directly, and it reasons at maximum effort by default. It is Moonshot's most capable model and the first open 3T-class release — closed-frontier-class quality at open-model prices ($3.00 / $15.00 per 1M tokens; see the evidence box below). Select a lower effort (low or high) when you want its context without the full think.
• Use umans-deepseek-v4-pro-0813 for the hardest long-horizon coding work: the coding flagship with a 1M context window and high-effort reasoning by default ($1.32 / $3.96 / $0.044 per 1M tokens, input / output / cached). It served here as a seat-gated pre-release lab from August 13 to 15, 2026, so its status page already carries that window's metrics as its pre-release period.
• 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; the live target is always on GET /v1/models/info.
• Use umans-flash for the workflow roles around umans-coder, not as a standalone coder (think Haiku or Sonnet alongside Opus). Its speed (200+ tps) compounds when gathering context, running scout subagents, doing research, writing summaries, documentation, or release notes.
• Use umans-glm-5.3 for GLM 5.2's lineage taken further: Z.ai's flagship coding model on a 1M context window, with large post-training gains on complex, long-horizon tasks ($1.40 / $4.40 / $0.26 per 1M tokens, input / output / cached). It always thinks — at max effort by default; dial low or high to tune latency and cost (thinking cannot be turned off).
• Use umans-deepseek-v4-flash-0731 for everyday agentic work at the lowest price in the lineup ($0.14 / $0.28 / $0.028 per 1M tokens, input / output / cached). Its 1M window covers most sessions, and for most users a month of it costs less than a flat subscription did. It thinks at low effort by default: select high or max on the hard tasks instead of switching models. Through September 10, 2026 every wallet top-up earns twice its amount in bonus credit usable on this model; see dsv4fx3 promotion terms.

Benchmark Comparison

We believe in transparency. We start with the Artificial Analysis composite indices (Coding and Agentic, August 2026), which rank our whole lineup against the frontier at max reasoning effort. Then FrontierSWE and Terminal-Bench v2.1, which feature Claude Fable 5 (with MCP) and our Kimi K2.7-Code (retired September 10, 2026; what umans-coder routed to at the time). Use the tabs to compare our models against GPT-5.5/5.6, Claude Opus 4.8 and Opus 5, Gemini 3.1 Pro, and the leading open models. The remaining benchmarks are from Z.ai's GLM 5.2 model card. Different harnesses are not comparable across sources.

umans-flash: light model comparison

umans-flash sits in a different category from the headline coder above. It isn't a standalone coding model. Think of it the way you'd think of Claude Haiku or Sonnet next to Opus: a light, high-interactivity model meant as a workflow complement rather than the deepest solver. We target 200+ tokens per second on this route (median observed above 300 tps), so it stays snappy for quick edits, orchestration steps, and tight inner loops. It's built to make the rest of your coding workflow faster: gathering context, scout subagents, research, summaries, documentation, release notes, even quick reviews.

Below, we line it up against peer open-weight light and mid models, with Claude 4.5 Opus included as a frontier reference rather than a peer.

Source: scores from the Qwen3.6-35B-A3B model card. Throughput targets reflect our own measurements on the Umans serving stack.

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.

Reasoning & Extended Thinking

Umans coding models can produce extended reasoning (internal thinking) before their final answer. You control it with the same standard knobs the two APIs define, and you can use either one on either endpoint. Umans normalizes your request to a single effective setting before it reaches the model.

Two standard controls

• /v1/messages (Anthropic): the extended thinking standard, via the thinking object.
• /v1/chat/completions (OpenAI): the reasoning standard, via the reasoning_effort field.

You can send the OpenAI reasoning_effort on the Anthropic route, or the Anthropic thinking object on the OpenAI route. Both are accepted and mapped. Send one control per request; if both are present, the explicit thinking object wins, so the request never conflicts.

Enable or disable reasoning

• Anthropic: "thinking": {"type": "enabled"} to enable, {"type": "disabled"} to turn off.
• OpenAI: "reasoning_effort": "low" | "medium" | "high" to enable, "none" to turn off.

Per-model defaults: umans-glm-5.3 always thinks — at max effort by default; dial low or high (thinking cannot be turned off). umans-kimi-k3 also thinks by default — at max effort — but honors "reasoning_effort": "none" with a genuinely non-thinking answer, and accepts low/ high/max to trade depth for speed. Its sampling fields (temperature, top_p) are fixed server-side; the gateway removes them rather than failing your request. umans-deepseek-v4-pro-0813 thinks by default at high effort, honors "reasoning_effort": "none" with a genuinely non-thinking answer, and accepts high/ max (lower values map to high).

Effort level vs. thinking budget

reasoning_effort selects how hard the model thinks: none, low, medium, high (other values such as minimal are accepted and mapped to the nearest level). On the Anthropic route you can instead set an explicit token budget: "thinking": {"type": "enabled", "budget_tokens": 4096}. Higher effort or larger budget means deeper reasoning. If you give an effort rather than a budget, Umans picks an appropriate budget for you.

Max output tokens

max_tokens (/v1/messages) and max_completion_tokens (/v1/chat/completions) cap the total tokens the model generates, and reasoning counts toward that cap. Your thinking budget must therefore be smaller than your max output tokens. Umans never raises the max_tokens you set; if your thinking budget would not leave room under it, Umans automatically reduces the budget to fit instead of rejecting the request, and if max_tokens is too small for any meaningful reasoning, thinking is turned off for that request.

Where reasoning appears in the response

• /v1/messages: as thinking content blocks (streamed as thinking_delta events), separate from the text answer.
• /v1/chat/completions: in a reasoning_content field on the message and on streamed deltas, separate from content.

Reasoning streams live, token by token, alongside the answer.

Examples

Anthropic, explicit budget:

curl -N -X POST https://api.code.umans.ai/v1/messages \
  -H "x-api-key: sk-your-umans-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "umans-coder",
    "max_tokens": 8000,
    "thinking": {"type": "enabled", "budget_tokens": 4096},
    "messages": [{"role": "user", "content": "Refactor this function for clarity."}],
    "stream": true
  }'

OpenAI, effort level:

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

Web Search

When your agent needs to look something up, we can run the search for you and hand 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
umans claude --websearch none      # Off; pass your own web_search tool through

Or set it per request when calling the API directly:

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

If neither is set, we use the default backend. The override only takes effect on requests that actually carry a web search tool, and only on routes where we own the search step (some models run search themselves, in which case the header is moot). Use none to turn server-side search off entirely and pass your own web_search tool through to the model unchanged.

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. We also do not log per-call payloads in production logs.

Pay by Token

Umans Code is pay-per-token. You prepay a wallet and every request bills exactly what it uses at the published per-token prices. One key works for every job: you coding interactively in Claude Code, OpenCode, Cursor, Zed, or Pi, and also CI, scheduled jobs, unattended automations, bots serving other people, and cloud agents funded from your wallet.

Your balance is the real spend limit. Burst limits come from your wallet's tier (they grow with lifetime top-ups; see Limits), and wallet keys are never auto-paused. Automations get plain, retryable 429s at worst.

Looking for the flat monthly plans? They were sunset on August 1, 2026 — kept for reference in the plans archive.

Which key for which job

Mint keys from your wallet. When the spend belongs to a team, an organization wallet keeps the budget, keys, and audit in one place, with service accounts for its automations.

Limits

Every key draws from a prepaid wallet and bills per token, so your balance is the real spend limit. On top of it, your wallet's tier bounds burst: how much you can run at once, and how fast you can fire requests. Tiers grow with your lifetime top-ups and never go down. (Flat-rate subscription plans were retired on August 1, 2026 — see the plans archive.) There are two kinds of limit: how much you can use over time, and how much you can run at once. This page explains exactly how both work and what happens when you reach them, so nothing here ever surprises you. The short version: enforcement starts gently, everything is visible in your dashboard, and the rare hard stop exists to protect you from a runaway setup as much as it protects everyone else's experience.

Wallet tiers at a glance

Wallet keys work differently: your balance is the real spend limit, so tiers only bound burst. Your tier is set by your lifetime paid top-ups and never goes down. Bonus credits count toward your balance but never toward your tier.

All of a wallet's keys share its tier limits: they are per wallet, not per key. That includes keys you mint for automations and any wallet-funded cloud agents. Your current tier, and how far you are from the next one, is always visible on the Wallet tab.

When the wallet runs dry

Rate limits are the gentle part; balance exhaustion is the hard one. A wallet with no credit at all — no paid top-up, no active promo grant — does not serve until it has some. Promo credit (like the founders' bonus) serves while it lasts; the moment it drains or expires, the wallet suspends until a paid top-up. And a funded wallet that drains to its tier's floor — a small negative allowance ($5 at Tiers 0–1, $25 at Tier 2, $100 at Tier 3), there to absorb in-flight requests and auto-refill latency, never free credit — suspends at the gateway. That is a stop, not a 429: requests fail until you top up, then everything resumes on its own, keys untouched. Your balance and state are always on the Wallet tab, and auto-refill exists exactly so production automations never meet the floor.

The window rolls, it doesn't reset

Your tier's request budget counts in a rolling five-hour window: each request stops counting exactly five hours after it happened. There is no fixed reset time, no daily quota, and no weekly cap on top. If you ever reach the limit, capacity comes back continuously as your oldest requests age out, so a heavy morning never costs you the afternoon. And since billing is per token, the window only ever throttles burst — it can never charge you more than the balance you chose to top up.

Light requests count less

Requests are weighted by the model that serves them. The headline coding models count as one request each. Lighter models count as a fraction: today, umans-flash counts as half a request. Coding agents route plenty of small steps to a light model (summaries, titles, quick checks), so your effective usage grows more slowly than your raw request count. The Usage tab in your dashboard shows raw and effective numbers side by side. Weights can change as models evolve; the Usage tab always reflects the ones actually applied.

Concurrency means requests in flight, not terminals open

Your concurrency limit caps how many requests are being processed at the same instant, not how many sessions you have open. An agent session only holds a slot while a model is actually generating; while it runs tools, edits files, or waits for you, it holds none. In practice, 3 or 4 slots cover more parallel sessions than the numbers suggest. What does add up quickly is fan-out: five subagents thinking at the same moment is five requests in flight.

Headroom before errors

We don't return errors at exactly your limit. Today, hard enforcement starts around twice the stated number. The headroom exists to absorb honest mistakes, like a forgotten cron job or a runner you didn't know was still alive, so you can spot the problem in your dashboard and fix it before it costs you anything. Treat it as a safety net, not extra capacity: it is operational slack we tune over time, and workflows that depend on it will eventually hit the real limit.

If you push past it

Beyond the headroom, requests return HTTP 429 (rate limited). Coding agents handle 429s by backing off and retrying, so brushing the limit usually feels like a short pause rather than a failure. Each 429 also places your account at lower priority for about 30 minutes: requests keep working, just slower. The fastest way back to full speed is to reduce the parallelism that caused it.

The automatic pause

On the remaining flat-rate seat keys (legacy team orgs), an account that racks up repeated concurrency 429s in a single day is paused for five hours. Normal individual use doesn't get there. In practice, a pause means something is hammering the API without you noticing: a loop spawning agents, a stuck script, a key being used somewhere it shouldn't be. When it happens, your dashboard shows a banner with a countdown, and you have two ways out:

• Wait it out. The pause lifts on its own after five hours, and your API keys are untouched.
• Reactivate now from the dashboard. This revokes and rotates all your API keys, which guarantees that whatever was hammering the API stops with them. You can self-reactivate up to five times a week; after that, contact support and we'll figure it out with you.

The pause is a flat-rate leftover and can only reach those seat keys. Wallet keys are never paused: they exist for real workloads, where a surprise five-hour stop would hurt more than it helps. Past your tier's limits they get plain, retryable 429s, and nothing else. (One different thing can stop them: an exhausted wallet — see When the wallet runs dry below.)

Exceptionally heavy days: low-interactivity mode

Flat-rate seat keys are sized for a person coding, even intensively, all day. On the very rare days an account goes far beyond that (think an agent fleet left running overnight, not a long day of work), we serve it in low-interactivity mode for the next 24 hours: at quiet moments nothing changes, and at busy moments its requests queue behind interactive sessions and may occasionally be asked to retry. Nothing is blocked, and your models and answer quality stay exactly the same. Interactive mode resumes automatically at the shown time; you never have to do anything.

You always see where you stand: umans usage and the Usage tab show your current mode and the exact time interactive mode resumes, and the CLI mentions it when you start a session. In a team, this only ever applies to the seat having the heavy day, never to teammates. If your workload is genuinely this large, that is exactly what wallet keys (billed per token) are for: they never enter low-interactivity mode. And if it ever surprises you, check for a runaway automation first, then ask us on Discord.

Fair use, in one paragraph

Pay-per-token has no fair-use puzzle: if it bills to your wallet, it is a legitimate workload — your own coding, your automations, your production traffic. What a key still is: a credential. Keep it on machines and runners you control, never publish it, and don't hand it to other people — anyone holding it spends your balance. For teams, an organization wallet keeps the budget shared and the audit per key, with service accounts for its automations. If you are not sure which side of the line your setup is on, ask us on Discord; the answer is usually that you are fine.

See where you stand

The Usage tab at umans.ai/billing shows your requests (raw and effective), your concurrency peaks, and any rate-limited requests, over the same rolling window the limits use. If anything on this page ever affects you, that is where it shows up first.

Images

A single request can include up to 20 images, counted across all messages on both /v1/messages and /v1/chat/completions. Past that, the request is rejected with a 400 before it reaches a model.

The API is stateless: your tool resends the whole conversation on every turn, so this is really “20 images in the conversation you send,” not 20 per session on our side. Long, image-heavy sessions reach it quickly. The usual fix, which good harnesses do for you, is to keep only the most recent images and replace older ones with a short text description of what they showed, so the model keeps the context without resending every pixel.

Usage

See where you stand at any time, from the CLI or the API. The quickest way is umans usage:

$ umans usage
  Requests      [█░░░░░░░░░]  480 / 4,000   burst 8,000   resets in 3h 12m
  Concurrency   [█░░░░░░░░░]  1 / 8         burst 16
  Tokens        1.2M in · 340K out

  ✓ You're all set — requests are flowing normally.

(The header line, elided here, names the plan or tier your key was created under; the bars reflect your wallet's current tier.)

The bars show how close you are to each soft cap, the burst ceiling is the headroom you get before any throttling, and the last line tells you how your traffic is being served right now: all set, briefly deprioritized after a burst, or in low-interactivity mode with the time interactive mode resumes. Wallet keys are never deprioritized and never enter low-interactivity mode, so for them the last line always reads all set. Pass --json for the raw response.

Current window: GET /v1/usage

Returns your key's plan or tier, your limits (soft cap + burst ceiling), and live counters for the rolling window: requests used, remaining, in-flight concurrency, and token totals. It is scoped to your account — all keys under the same wallet share the tier's counters, which is exactly what triggers a 429.

curl https://api.code.umans.ai/v1/usage \
  -H "Authorization: Bearer sk-your-umans-api-key"

{
  "limits": {
    "requests":    { "limit": 4000, "hard_cap": 8000, "burst_pct": 1.0, "window_seconds": 18000 },
    "concurrency": { "limit": 8,    "hard_cap": 16,   "burst_pct": 1.0 }
  },
  "usage": {
    "requests_in_window": 480,
    "remaining_requests": 3520,
    "concurrent_sessions": 1,
    "tokens_in": 1200000,
    "tokens_out": 340000,
    "priority": { "low": false, "boxed_until": null, "reason": null },
    "service_mode": { "current": "interactive", "resets_at": null }
  }
}

limit is the soft cap; hard_cap is the burst ceiling we let you reach before throttling (null when unlimited). The example above shows a Tier 1 wallet; the plan block (omitted here) echoes the plan slug the key was created under. If priority.low is true — seat keys only, never wallet keys — your requests are briefly deprioritized after a rate-limit burst: they still go through, just queued behind other traffic. service_mode.current is interactive in normal operation and low_interactivity during exceptionally heavy days, with resets_at the exact time interactive mode resumes. concurrent_sessions is this server's view; concurrency is enforced fleet-wide.

History: GET /v1/usage/history

Bucketed history for your account, up to 90 days back. Pass from, to, and granularity (hour or day). Each bucket breaks down requests, weighted requests, tokens (in / out / cached), peak concurrency, and a machine-readable error_category when something failed.

curl "https://api.code.umans.ai/v1/usage/history?from=2026-06-01T00:00:00Z&to=2026-06-22T00:00:00Z&granularity=day" \
  -H "Authorization: Bearer sk-your-umans-api-key"

Scoped to the authenticated key's account — you can't read another account's usage. Add scope=mine to narrow an org seat's view to its own keys. When summing tokens across the Anthropic and OpenAI routes, prefer tokens_in_total / tokens_in_uncached — the legacy tokens_in counts cache reads differently per route.

Service status

Live status, uptime, and per-model speed (median time to first token and output tokens per second) are published at status.umans.ai. The same data is available from the CLI and the API.

From the CLI: umans health

$ umans health

Current status band, 24h uptime, and median TTFT / output speed per model. Pass --json for the raw response.

Snapshot: GET /v1/status

Public health snapshot: a status band (operational, degraded, or major_outage), 24h uptime, median TTFT, and median output tokens per second, overall and per model.

curl https://api.code.umans.ai/v1/status \
  -H "Authorization: Bearer sk-your-umans-api-key"

History: GET /v1/status/history

Bucketed history for the public metrics (uptime_pct, ttft_ms, output_tokens_per_second), up to 90 days back. Pass from, to, granularity (minute, hour, or day), and optionally metric and model.

curl "https://api.code.umans.ai/v1/status/history?granularity=day&metric=uptime_pct" \
  -H "Authorization: Bearer sk-your-umans-api-key"

Liveness: GET /health

An unauthenticated probe that returns OK when the gateway is up. Good for uptime monitors; /v1/status is the richer, per-model view.

Tool-Specific Setup

umans claude                              # Default: umans-coder (our current pick)
umans claude --model umans-kimi-k3        # Kimi K3: 1M context, native vision, max reasoning by default
umans claude --model umans-glm-5.3        # GLM 5.3: Z.ai's flagship coding model
umans claude --model umans-flash          # Light, high-interactivity complement
umans claude --websearch native           # Umans web search: Kimi-backed path
umans claude --websearch exa              # Umans web search: Exa-backed path
umans claude --websearch none             # Disable server-side search; pass your own web_search tool through

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-flash      # Light, high-interactivity complement
umans opencode --model umans-kimi-k3    # Use Kimi K3
umans opencode --model umans-glm-5.3    # Use GLM 5.3

{
  "$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-flash": {
          "id": "umans-flash",
          "name": "Umans Flash",
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "umans-kimi-k3": {
          "id": "umans-kimi-k3",
          "name": "Umans Kimi K3",
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "umans-glm-5.3": {
          "id": "umans-glm-5.3",
          "name": "Umans GLM 5.3",
          "modalities": { "input": ["text"], "output": ["text"] }
        },
        "umans-deepseek-v4-pro-0813": {
          "id": "umans-deepseek-v4-pro-0813",
          "name": "Umans DeepSeek V4 Pro",
          "modalities": { "input": ["text"], "output": ["text"] }
        },
        "umans-deepseek-v4-flash-0731": {
          "id": "umans-deepseek-v4-flash-0731",
          "name": "Umans DeepSeek V4 Flash",
          "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-flash",
          "name": "Umans Flash",
          "default_max_tokens": 50000,
          "can_reason": true
        },
        {
          "id": "umans-kimi-k3",
          "name": "Umans Kimi K3",
          "default_max_tokens": 50000,
          "can_reason": true
        },
        {
          "id": "umans-glm-5.3",
          "name": "Umans GLM 5.3",
          "default_max_tokens": 50000,
          "can_reason": true
        },
        {
          "id": "umans-deepseek-v4-pro-0813",
          "name": "Umans DeepSeek V4 Pro",
          "default_max_tokens": 50000,
          "can_reason": true
        },
        {
          "id": "umans-deepseek-v4-flash-0731",
          "name": "Umans DeepSeek V4 Flash",
          "default_max_tokens": 50000,
          "can_reason": true
        }
      ]
    }
  }
}

# Install omp from https://omp.sh, then inside omp:
/login umans           # Select the Umans provider and paste your API key

# Or set it without a prompt:
export UMANS_AI_CODING_PLAN_API_KEY=sk-your-umans-api-key

umans omp                # Launch omp wired to Umans (installs it if needed)
umans omp --setup        # Make a bare 'omp' use Umans by default (and cap concurrency to your tier)
umans install omp        # Install omp (Oh My Pi)

llm-pi-ai:
  providers:
    umans:
      displayName: Umans AI
      apiKeyEnv: UMANS_AI_API_KEY
      api: openai-completions
      baseURL: https://api.code.umans.ai/v1
      models:
        - id: umans-coder
        - id: umans-flash
        - id: umans-kimi-k3
        - id: umans-glm-5.3
        - id: umans-deepseek-v4-pro-0813
        - id: umans-deepseek-v4-flash-0731

export UMANS_AI_API_KEY=sk-your-umans-api-key

umans setup dsh            # Write the Umans provider into ~/.dsh/settings.yaml

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-flash, umans-kimi-k3, umans-glm-5.3, umans-deepseek-v4-pro-0813, or umans-deepseek-v4-flash-0731 if you prefer — the full live list is at GET /v1/models.

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.

Troubleshooting

curl -fsSL https://api.code.umans.ai/cli/install.cmd -o install.cmd && install.cmd && del install.cmd

$env:ANTHROPIC_BASE_URL="https://api.code.umans.ai"
$env:ANTHROPIC_AUTH_TOKEN="sk-your-umans-api-key"

FAQ

Support

Need help?

Archive: subscription plans (sunset August 1, 2026)

Until August 1, 2026, Umans Code also came in two flat monthly plans for individual coding: Code Pro (200 effective requests per rolling 5-hour window, up to 5 requests in flight) and Code Max (unlimited tokens, no request window, up to 4 in flight). A plan covered one human coding interactively in the tools they already used, on every machine they owned — never shared, never powering automations.

Plan keys carried mechanics built for flat-rate abuse protection: a five-hour automatic pause after repeated concurrency abuse (with self-reactivation that rotated keys), low-interactivity mode on exceptionally heavy days, and fair-use enforcement. None of these apply to wallet keys, which bill per token and are never paused.

At the sunset, every remaining subscription was canceled and refunded (monthly: the last payment in full; yearly: prorated to the cutoff), and founding members kept their ★ Founding badge and perks. The story is on blog.umans.ai.