DEV Community: Preecha

Open Source API Management Tools

Preecha — Fri, 26 Jun 2026 13:02:58 +0000

APIs are the backbone of modern applications, but managing them across microservices, mobile apps, partner integrations, and internal platforms gets difficult fast. Open source API management tools give teams a flexible way to secure, publish, monitor, and govern APIs without committing fully to a closed vendor platform.

Try Apidog today

This guide breaks down what open source API management tools do, which features matter, which projects are commonly used in 2026, and how to implement a practical API management workflow from design to runtime governance.

What Are Open Source API Management Tools?

Open source API management tools help teams manage the full API lifecycle:

Designing and publishing APIs
Routing traffic through an API gateway
Applying authentication and authorization
Enforcing rate limits and quotas
Monitoring usage, latency, and errors
Managing versions, deprecations, and developer access

Unlike proprietary API platforms, open source tools provide more transparency and customization. You can inspect the source code, extend behavior with plugins or policies, and adapt the platform to your infrastructure.

Why API Management Matters

As systems scale, APIs often become distributed across teams, regions, and environments. Without API management, common problems include:

Unauthorized or poorly governed API access
Inconsistent authentication and rate limiting
No centralized visibility into API usage
Difficult API versioning and deprecation
Scaling issues during traffic spikes
Vendor lock-in from closed commercial platforms

An API management layer helps standardize how APIs are exposed, secured, monitored, and consumed.

Core Features to Look For

When evaluating open source API management tools, focus on implementation-critical capabilities.

1. API Gateway

The gateway is the runtime entry point for API traffic. It typically handles:

Request routing
Load balancing
Authentication
Rate limiting
Protocol handling
Request and response transformations

Example gateway flow:

Client -> API Gateway -> Backend Service
              |
              +-- Auth policy
              +-- Rate limit policy
              +-- Logging policy
              +-- Routing rule

2. Security and Access Control

Look for support for common API security patterns:

API keys
OAuth2
JWT validation
IP allowlists and blocklists
mTLS where required
Role-based or policy-based access control

A basic policy model might look like this:

security:
  authentication:
    type: jwt
    issuer: https://auth.example.com
  access:
    allowed_roles:
      - partner
      - internal
  traffic:
    rate_limit:
      requests: 1000
      period: 1m

3. Traffic Management

Traffic controls protect backend services and create fair usage rules for consumers.

Common controls include:

Rate limiting
Throttling
Quotas
Retry rules
Circuit breaking
Request size limits

4. Analytics and Monitoring

API management tools should help you answer questions like:

Which APIs are used most?
Which consumers generate the most traffic?
What is the error rate?
Which endpoints are slow?
Are there suspicious request patterns?

Useful metrics include:

requests_total
request_latency_ms
error_rate
status_code_distribution
consumer_usage
upstream_response_time

5. Developer Portal

A developer portal gives internal or external developers a self-service place to:

Discover available APIs
Read documentation
Test endpoints
Request access
View credentials or subscriptions

This is especially useful for partner APIs and API-as-a-product platforms.

6. API Lifecycle Management

API management is not only about routing traffic. You also need lifecycle controls for:

API design
Review and approval
Publishing
Versioning
Deprecation
Retirement

A simple lifecycle could be:

Design -> Review -> Publish -> Monitor -> Version -> Deprecate -> Retire

7. Extensibility

Open source API management tools often support plugins, custom policies, or scripting.

Use extensibility when you need to integrate with:

Internal identity providers
Custom logging pipelines
CI/CD workflows
Observability platforms
Compliance systems

Top Open Source API Management Tools in 2026

The open source API management ecosystem includes several mature options. The right choice depends on your runtime environment, team skills, traffic patterns, and governance requirements.

1. Kong

Kong is a high-performance API gateway built on NGINX. It is commonly used for scalable API traffic management and has a broad plugin ecosystem.

Key capabilities:

Traffic control
Authentication plugins
Logging plugins
Analytics integrations
Kubernetes-native deployment options
Declarative configuration

Good fit for:

Teams running high-traffic APIs
Kubernetes-based environments
Plugin-driven gateway customization

2. Tyk

Tyk provides an open source gateway with API management features including a dashboard and developer portal options.

Key capabilities:

REST, GraphQL, and gRPC support
Fine-grained security controls
Rate limiting
API analytics
Hybrid and multi-cloud deployment support

Good fit for:

Teams that need a lightweight gateway
Multi-protocol API environments
Hybrid infrastructure

3. Gravitee.io

Gravitee.io is a modular open source API platform that includes gateway, access management, and developer portal components.

Key capabilities:

Policy-based security
Traffic shaping
Analytics
Developer portal
Support for event-driven and asynchronous APIs

Good fit for:

Teams managing both synchronous and asynchronous APIs
Organizations that need centralized access management
API platforms with event-driven architecture

4. WSO2 API Manager

WSO2 API Manager is a comprehensive open source API management platform with strong integration and identity management capabilities.

Key capabilities:

API gateway
API publisher
API store
Analytics
Monetization support
OAuth2 support

Good fit for:

Enterprise API programs
Teams needing broader integration capabilities
Organizations with complex identity requirements

5. Apache APISIX

Apache APISIX is a cloud-native API gateway known for dynamic configuration and real-time plugin hot reload.

Key capabilities:

Traffic control
Security policies
Real-time logging
Plugin ecosystem
Support for multiple protocols

Good fit for:

Cloud-native deployments
Teams that need dynamic runtime configuration
High-performance gateway use cases

6. KrakenD

KrakenD is a stateless API gateway focused on aggregation and transformation. It is often used in microservices architectures.

Key capabilities:

Endpoint aggregation
Request and response transformation
Security controls
No-code endpoint configuration
High-performance stateless design

Good fit for:

Backend-for-frontend patterns
Microservices aggregation
APIs that need response composition

7. Apiman

Apiman is an extensible open source API management tool focused on policy-based runtime governance.

Key capabilities:

Multi-tenancy
Metrics
Custom policies
Management UI
Developer portal
Integration with Java stacks

Good fit for:

Java-based organizations
Teams needing custom governance policies
Internal API platforms

How Open Source API Management Tools Work

Most API management platforms sit between API consumers and backend services.

Web App / Mobile App / Partner App
                |
                v
          API Management Layer
          - Authentication
          - Authorization
          - Rate limiting
          - Routing
          - Logging
          - Analytics
                |
                v
        Backend APIs / Microservices

A typical workflow looks like this:

Design the API

Define endpoints, methods, parameters, request bodies, responses, and error formats using OpenAPI or Swagger.
Publish the API

Register the API in your API management platform and expose it through the gateway.
Secure the API

Apply authentication, authorization, API key, OAuth2, JWT, or IP filtering policies.
Control traffic

Configure rate limits, quotas, throttling, and request validation.
Monitor usage

Track requests, errors, latency, and consumer behavior.
Iterate safely

Version APIs, update documentation, deprecate old endpoints, and retire unused APIs.

Using Apidog Before Runtime API Management

Apidog can complement open source API management tools during the API design, testing, and documentation phase.

A practical workflow is:

Design the API contract in Apidog.
Define endpoints, parameters, request examples, and response examples.
Generate or maintain OpenAPI/Swagger definitions.
Share online API documentation with your team.
Create mock data for frontend or integration testing.
Export the API specification.
Import the spec into an API management tool such as Kong, Tyk, Gravitee.io, or Apiman.

This helps ensure APIs are defined and tested before they are exposed through a production gateway.

Real-World Use Cases

1. Banking and Fintech

Banks and fintech platforms use API management to expose secure partner APIs for open banking, payment integrations, and regulatory reporting.

Example implementation:

Use Tyk Gateway to expose partner APIs.
Apply OAuth2 policies.
Enforce rate limits per partner.
Log API activity for audit and compliance.
Monitor failed authentication attempts.

2. E-commerce Platforms

E-commerce companies use API management to scale APIs for storefronts, mobile apps, vendors, and logistics partners.

Example implementation:

Use Kong as the API gateway.
Route traffic to catalog, cart, checkout, and logistics services.
Apply rate limits to public APIs.
Track request volume and latency.
Use analytics to identify slow or error-prone endpoints.

3. Healthcare and IoT

Healthcare and IoT systems often need strict access control and audit logging for sensitive data APIs.

Example implementation:

Use Gravitee.io to expose FHIR APIs.
Apply access policies for healthcare apps.
Monitor unusual request patterns.
Centralize audit logs.
Enforce security controls for patient data APIs.

4. SaaS and Developer Platforms

Developer-focused SaaS companies use API management to provide self-service onboarding, documentation, and sandbox environments.

Example implementation:

Use Apidog for API design, testing, and documentation.
Use Apiman for runtime governance.
Publish APIs through a developer portal.
Apply subscription-based access policies.
Monitor usage by developer account or tenant.

Practical Implementation Workflow

Here is a practical implementation path for combining API design tooling with open source API management.

Step 1: Design the API Contract

Start with an API specification.

Example OpenAPI fragment:

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders
      responses:
        "200":
          description: A list of orders
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    status:
                      type: string

Use Apidog to define endpoints, parameters, examples, and responses before exporting the OpenAPI or Swagger file.

Step 2: Export the OpenAPI or Swagger Spec

Export the API contract from your design tool.

Example file:

apidog-exported-api.json

Keep this file versioned in Git so API changes can go through review.

git add apidog-exported-api.json
git commit -m "Add Orders API specification"

Step 3: Import the API into Your Management Tool

Import the exported API definition into your API management platform.

Example: importing a Swagger/OpenAPI spec into Apiman:

curl -X POST \
  -H "Content-Type: application/json" \
  -d @apidog-exported-api.json \
  https://{apiman-server}/apiman/rest/apis/import

Replace {apiman-server} with your Apiman server hostname.

Step 4: Configure Runtime Policies

After importing the API, configure policies such as:

Authentication
Authorization
Rate limiting
Request validation
Logging
CORS
Quotas

Example policy checklist:

[ ] Require authentication
[ ] Validate JWT issuer
[ ] Apply per-consumer rate limit
[ ] Enable request logging
[ ] Track 4xx and 5xx errors
[ ] Add versioning rules

Step 5: Publish Through the Gateway

Expose the API through your gateway endpoint.

Example:

https://api.example.com/orders

Route requests to the backend service:

https://orders-service.internal/orders

Step 6: Monitor and Iterate

Track operational metrics after release:

Request count
Error rate
Latency
Top consumers
Rate limit violations
Authentication failures

Use these signals to decide when to optimize, scale, version, or deprecate endpoints.

Advantages of Open Source API Management Tools

Open source API management tools offer several practical benefits.

Advantage	Why it matters
Cost savings	No licensing fees for the open source components
Transparency	Source code can be reviewed for security and compliance
Customization	Policies, plugins, and integrations can be adapted to your stack
Community support	Active communities help with troubleshooting and improvements
Reduced vendor lock-in	Teams can migrate, fork, or extend tools as requirements change

Challenges and Considerations

Open source API management is powerful, but it still requires operational planning.

Operational Overhead

You need in-house expertise to deploy, secure, scale, upgrade, and monitor the platform.

Plan for:

High availability
Backups
Configuration management
Gateway scaling
Observability
Security patching

Feature Gaps

Some advanced capabilities may require commercial editions, plugins, or custom implementation.

Examples include:

Advanced monetization
AI-based analytics
Enterprise support
Advanced developer portal features
Managed hosting

Integration Complexity

Before choosing a tool, validate compatibility with your existing stack:

CI/CD pipelines
Identity providers
Logging systems
Metrics platforms
Kubernetes or VM infrastructure
Secrets management
API documentation workflow

Implementation Checklist

Use this checklist before adopting an open source API management platform:

[ ] Identify APIs that need centralized management
[ ] Define authentication and authorization requirements
[ ] Choose gateway deployment model
[ ] Decide how API specs will be created and versioned
[ ] Configure logging and monitoring
[ ] Define rate limits and quotas
[ ] Set up developer onboarding flow
[ ] Test failure scenarios
[ ] Document API publishing process
[ ] Create versioning and deprecation rules

Conclusion

Open source API management tools help teams secure, govern, publish, and monitor APIs with more flexibility and transparency. Tools like Kong, Tyk, Gravitee.io, WSO2 API Manager, Apache APISIX, KrakenD, and Apiman can provide the runtime control layer for modern API platforms.

For a practical implementation, separate API design from runtime governance:

Design and test the API contract.
Export an OpenAPI or Swagger specification.
Import it into your API management platform.
Apply security and traffic policies.
Monitor usage and iterate over time.

Combining open source API management tools with an API design and documentation workflow helps teams ship APIs that are easier to secure, operate, and evolve.

Hermes Agent: The Better OpenClaw Alternative Is Here

Preecha — Fri, 26 Jun 2026 01:02:51 +0000

TL;DR / Quick Answer

For API-heavy workflows, Hermes Agent is the stronger OpenClaw alternative for most teams. It combines official MCP support, broader provider flexibility, built-in OpenClaw migration, self-improving skills, and more deployment options. OpenClaw still makes sense if you prefer a gateway-first runtime, a tightly scoped workspace model, and its existing plugin and cron setup.

Try Apidog today

Introduction

If you are evaluating Hermes Agent as an OpenClaw alternative, the short answer is yes for many developer-facing API workflows. The reason is not hype. It is stack coverage.

Hermes Agent is positioned as a self-improving agent with MCP support, multiple messaging surfaces, scheduled automations, provider choice, and an official hermes claw migrate path for OpenClaw users.

OpenClaw is still a capable runtime. Its docs describe a gateway scheduler, custom skills, plugins, and a clear workspace model. The practical decision is not “which agent is newer?” It is “which runtime fits the way your team connects APIs, tools, webhooks, and MCP servers?”

That is also where Apidog fits. If you are building the API contracts either agent will call, Apidog helps you design, mock, test, and document those integrations before an agent touches production data.

What Is Hermes Agent?

Hermes Agent is an open-source AI assistant from NousResearch. It is designed to retain context, learn from past sessions, and become more useful over time.

Unlike a stateless assistant that starts from zero each session, Hermes builds persistent context around projects, preferences, and workflow patterns.

Its main differentiator is the learning loop:

Conversations and completed tasks can feed future behavior.
Repeated workflows can become reusable skills.
Past sessions can be searched for relevant context.
Project-specific preferences can persist across runs.

For developers, that matters when the agent is not just answering questions but repeatedly working with codebases, APIs, internal tools, and operational workflows.

Why Developers Compare Hermes Agent and OpenClaw

Hermes and OpenClaw target overlapping use cases:

CLI-based agent workflows
Long-lived project context
Skills or reusable workflows
Scheduled automation
Tool integration
Messaging or gateway-style interaction

But their public positioning is different.

Hermes presents itself as a broader agent platform with:

built-in learning loop
cross-session memory
skills
scheduled automations
parallel delegation
MCP support
OpenClaw migration tooling

OpenClaw is framed more as a gateway-centered runtime with:

a single workspace model
bootstrap files such as AGENTS.md and SOUL.md
openclaw cron
WebSocket gateway
custom skills
plugin extension points
context-engine plugins

That difference changes implementation choices:

Choose Hermes when you want more of the agent stack pre-integrated.
Choose OpenClaw when you want a focused runtime around an existing workspace and gateway setup.

For API work, this distinction matters because the agent is only one layer. The difficult parts are usually underneath it:

HTTP APIs
MCP servers
webhooks
secrets
approval policies
test environments
documentation
schema drift

Core Product Differences

Dimension	Hermes Agent	OpenClaw	Why it matters for API workflows
Memory model	Built-in learning loop, skill creation, session search, user modeling	Workspace context, runtime memory model, bootstrap files	Hermes does more out of the box for long-running operational knowledge
Tool extension	Skills plus official MCP support	Skills plus plugins and plugin slots	Hermes is easier if your tools already exist as MCP servers
Runtime shape	CLI, gateway, multiple terminal backends, scheduled automations	Embedded runtime centered around workspace and gateway	Hermes is easier to stretch across local, VPS, and remote environments
Migration	Official `hermes claw migrate` flow	N/A	Hermes lowers switching cost for OpenClaw users
Provider surface	Nous Portal, OpenRouter, OpenAI, Anthropic, GitHub Copilot, local endpoints, and more	Model options exist, but public positioning is less expansive	Hermes is easier to match to team budget and provider constraints
Project context	Context files and project-level instructions	`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `BOOTSTRAP.md`	Both are workable; Hermes aims for broader operational context

The important point: OpenClaw still has substance. Its docs cover cron jobs, plugins, gateway configuration, and custom skills.

Hermes adds a more complete stack around those same categories, especially for teams that want MCP, migration, provider flexibility, and multi-surface automation in one path.

Hermes vs OpenClaw: Feature Comparison

Feature	Hermes Agent	OpenClaw	Practical takeaway
OpenClaw migration	Yes, via `hermes claw migrate`	N/A	Hermes makes switching realistic instead of theoretical
MCP support	Official docs and config path	Not the main public extension story	Hermes is easier if your tool layer is MCP-based
Messaging surfaces	Broad multi-surface story across CLI and messaging	Gateway-first runtime with messaging workflows	Both can work; Hermes packages more of the setup
Scheduling	Built-in scheduled automations	`openclaw cron` scheduler	Both support scheduled workflows
Skills	Self-improving skill loop	Custom skills	Hermes emphasizes automatic skill evolution
Plugins	Multiple extension paths	Plugin and context-engine plugin model	OpenClaw still has serious extension points
Provider flexibility	Wider public provider story	Less central in public docs	Hermes is easier to adapt to cost or provider changes
Deployment options	Local plus broader backend and VPS-friendly options	Tighter runtime and workspace model	Hermes fits more operations use cases

Migration Guide: OpenClaw to Hermes

If you already use OpenClaw, start with a dry run.

hermes claw migrate --dry-run

Use the output to review what Hermes can import before changing your active setup.

Then run the migration:

hermes claw migrate

Based on the public Hermes migration docs and README, the migration path is designed to bring over operational state such as:

memories and user context
existing skills
command approval patterns
messaging settings
some workspace-level instructions

A safer migration sequence:

Install Hermes.
Run the health check.

   hermes doctor

Run the migration dry run.

   hermes claw migrate --dry-run

Review imported skills, messaging settings, and command approvals.
Run the full migration.

   hermes claw migrate

Start with a CLI-only session.
Reconnect messaging surfaces after the base runtime works.
Re-add MCP servers or external tool integrations last.

That order isolates failures. If something breaks, you can tell whether the cause is imported state, provider configuration, or a new integration.

If your OpenClaw setup depends on custom plugins or strict workspace bootstrap files, treat migration like a runtime change:

export important state
test one workflow at a time
validate API-backed tools before handing them to the agent
keep rollback instructions available

For API-backed workflows, validate the contract in Apidog first. Otherwise, you may blame the agent for an unstable integration.

Standout Hermes Features

Hermes stands out where it combines capabilities that OpenClaw does not present as its main path today.

1. First-class OpenClaw migration

Hermes directly acknowledges OpenClaw users with a migration command.

hermes claw migrate

That lowers switching cost compared with manually recreating skills, memory, approvals, and messaging settings.

2. Official MCP-based expansion

OpenClaw supports plugins and skills. Hermes adds an official MCP configuration path.

That matters if your team is already exposing tools through MCP servers, such as:

filesystem access
GitHub operations
database tools
fetch tools
internal service wrappers
custom operational APIs

3. Broader provider and backend surface

Hermes is more explicit about provider choice and runtime backends.

That helps when you need to change model vendors, run locally, use a VPS, or connect through remote execution environments without redesigning the whole workflow.

4. Stronger learning-loop model

Both tools care about persistent usefulness, but Hermes makes self-improving skills, user modeling, and cross-session recall central to the product.

For recurring API operations, that can reduce repeated prompting and manual setup.

5. Better fit for API-plus-messaging workflows

Hermes combines:

migration support
MCP
provider flexibility
messaging
scheduling
broader deployment options

That combination is why it feels more complete for API operations, not just more feature-heavy on paper.

Which One Is Better for API Workflows?

For most teams building against internal APIs, webhooks, or MCP-connected services, Hermes is the stronger default.

1. Hermes has a cleaner path to external tool ecosystems

Hermes has official MCP documentation and example configuration for local and remote MCP servers.

A typical Hermes MCP configuration looks like this:

mcp_servers:
  filesystem:
    command: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "/home/user/projects"

  github:
    command: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-github"
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"

That fits teams that already think in service boundaries and tool contracts.

If your engineering org exposes capabilities through MCP, Hermes maps cleanly to that model.

2. Hermes has the stronger migration story

The migration command makes the OpenClaw comparison practical instead of theoretical.

hermes claw migrate --dry-run
hermes claw migrate

If you already use OpenClaw, this is the first feature to test.

3. Hermes is broader without forcing a browser-first workflow

Hermes can run in the CLI, but it is not limited to the CLI. Its docs also describe messaging surfaces such as Telegram and WhatsApp, plus scheduled job output.

That is useful for operational tasks like:

posting nightly API audit summaries
sending deployment health checks
surfacing failed contract tests
summarizing queue backlogs
reporting webhook failures

OpenClaw can handle scheduled gateway work too. Its cron docs show scheduler behavior such as retention, retries, and job history.

The difference is that Hermes presents more of the full path together: model selection, tools, messaging, cron, provider setup, and migration.

4. Hermes is better aligned with provider churn

API-heavy agent workflows can break or become expensive when model providers change pricing, rate limits, or behavior.

Hermes emphasizes provider flexibility, including OpenRouter, OpenAI-compatible endpoints, and multiple direct integrations.

That flexibility is useful if your team does not want agent architecture tied to one model vendor.

Where OpenClaw Still Makes Sense

OpenClaw should not be dismissed.

Its current docs still describe:

clear agent runtime model
dedicated workspace abstraction
bootstrap context files
custom skills
plugin support
context-engine plugins
gateway scheduling via openclaw cron

OpenClaw remains a good option if you value:

a simpler workspace model
gateway-first workflows
existing skills or plugins your team depends on
avoiding migration work
predictable workspace policy

OpenClaw can also be easier to treat as a contained runtime with a known home directory and workspace structure.

A better framing is:

Hermes is the better default for API-heavy, MCP-based, multi-surface automation.
OpenClaw is still valid if your current runtime and plugin model already work.

How Apidog Fits Into Either Stack

Hermes and OpenClaw are agent layers. Apidog is the API contract layer beneath them.

The fragile part of an agent workflow is usually not the chat interface. It is the service interface.

If the agent calls an unclear webhook, a drifting OpenAPI schema, or an undocumented status model, the workflow becomes unreliable.

A practical stack looks like this:

Apidog -> define and test the API contract
MCP server or plugin -> expose that contract to the agent
Hermes Agent or OpenClaw -> call the tool in a workflow

Example: your team wants an agent that triggers an internal API audit and posts the result in Telegram.

Define the HTTP contract first:

POST /audits
GET /audits/{audit_id}

Set up an environment:

base_url = https://internal-api.example.com
token = redacted
audit_id =

Add assertions:

POST /audits returns 202
response includes audit_id
GET /audits/{audit_id} moves from queued to completed
failure states are documented
auth errors return predictable status codes
retry behavior is clear

Only after the contract is stable should you expose it to the agent:

Hermes via MCP or another compatible tool path
OpenClaw via plugin, skill, or gateway workflow

This prevents a common failure mode: blaming the agent for a weak API contract.

Use Apidog to design, test, and document the APIs your Hermes Agent or OpenClaw workflows rely on before those integrations go live.

Advanced Evaluation Checklist

Do not choose based only on “which one writes better replies.”

Use this checklist instead.

1. How does the tool handle context pressure?

Hermes emphasizes compression, session search, and persistent knowledge.

OpenClaw also has a context engine model and plugin hooks.

If your workflows run for days or weeks, context management matters more than demo quality.

2. How much of your tool layer already exists as APIs or MCP servers?

If much of your tooling is already API-backed or MCP-ready, Hermes has the simpler story today.

3. How hard is it to move existing operational state?

If you are already on OpenClaw, test:

hermes claw migrate --dry-run

The migration path is one of Hermes’ strongest practical advantages.

4. How much deployment flexibility do you need?

Hermes is explicit about local, Docker, SSH, Modal, and other backend options.

That matters if you want the agent to run on a VPS, connect to remote systems, or wake up only for scheduled jobs.

5. Do you need a platform or a runtime?

Use this as the final decision line:

Choose Hermes if you want a broader agent platform.
Stay with OpenClaw if you want a tighter runtime and your current setup already works.

Alternatives and Comparisons

If your main goal is coding assistance, Hermes and OpenClaw are not the only options.

Tool	Best fit	Where it differs
Hermes Agent	API-heavy personal or team agent workflows	Broader stack with MCP, messaging, automation, and migration path
OpenClaw	Gateway-first agent runtime with existing plugin or skill investment	More focused workspace model and runtime-centered design
Claude Code	Code-first terminal agent	Strong for coding, weaker as a messaging-first personal agent
Codex-style agents	Repo work, automation, code change execution	Good for engineering tasks, not the same long-lived messaging agent model

Hermes is the closer OpenClaw alternative because it competes at the same architectural layer: long-lived agent runtime plus tools, scheduling, and integrations.

Real-World Use Cases

1. Internal API operations assistant

You want a bot that can:

summarize failed contract tests
create follow-up tickets
post a digest to Telegram
rerun checks after fixes

Hermes is a better fit if you also want MCP-based tool growth and scheduled delivery.

OpenClaw is still viable if your gateway flow already exists.

2. Team knowledge and workflow agent

You want:

project instructions
reusable skills
cross-session recall
workflow memory

Hermes has the stronger public story here because the learning loop is central to the product.

3. API watchdog on a cheap VPS

You want a small always-on agent that watches:

logs
health checks
webhook activity
failed jobs
API contract test results

Hermes is easier to recommend because its docs describe VPS-friendly and remote backend setups.

Conclusion

Hermes Agent is the better OpenClaw alternative for most API-heavy workflows right now.

OpenClaw still has a credible runtime, scheduler, skills system, and plugin model. If your team already built around OpenClaw and it works, there may be no urgent reason to migrate.

The biggest Hermes advantage is not one feature. It is how much of the modern agent stack is already connected:

MCP
migration
scheduling
messaging
provider flexibility
persistent learning
broader deployment paths

The biggest OpenClaw advantage is simplicity for teams already aligned with its workspace and gateway model.

If you are starting fresh, Hermes is the better default. If you are already on OpenClaw, test the migration path before rebuilding anything manually. And if your real problem is unstable API contracts, fix that first in Apidog so the agent layer has reliable tools to call.

FAQ

Is “Hermers Agent” the same as Hermes Agent?

Yes. People sometimes type “Hermers Agent,” but the project is Hermes Agent by NousResearch.

Is Hermes Agent connected to OpenClaw?

They are separate projects today, but Hermes explicitly supports migration from OpenClaw. That is why the comparison appears often.

Does OpenClaw still support plugins and cron jobs?

Yes. OpenClaw’s current docs describe a plugin system, context-engine plugins, custom skills, and scheduler commands under openclaw cron.

Why is Hermes better for API-heavy workflows?

Because Hermes combines broader provider support, official MCP documentation, migration tooling, scheduling, messaging, and a stronger learning-loop story in one stack.

Can Hermes Agent replace Apidog?

No. Hermes is an agent. Apidog is for API design, testing, mocking, environments, and documentation. They solve different layers of the same workflow.

Does Hermes Agent run on native Windows?

No. The official install docs say Linux, macOS, and WSL2 are supported, while native Windows is not.

How to Use Hermes Agent

Preecha — Thu, 25 Jun 2026 13:03:32 +0000

TL;DR: Hermes Agent is an open-source AI assistant that keeps persistent memory across sessions, learns reusable skills, and can run through CLI, Telegram, Discord, Slack, your IDE, or scheduled automation. This guide walks through installation, configuration, daily usage, integrations, memory, skills, and troubleshooting.

Try Apidog today

What Is Hermes Agent?

Hermes Agent is a personal AI assistant from NousResearch that can run continuously, remember prior work, and improve over time. Unlike tools that start each conversation from scratch, Hermes builds persistent context around your projects, preferences, conversations, and workflows.

Core capabilities:

Persistent memory: stores conversations, decisions, and code context
Learning system: turns repeated tasks into reusable skills
Multi-platform access: CLI, Telegram, Discord, Slack, WhatsApp, and IDE workflows
Self-hosting: run locally, on a VPS, or in cloud infrastructure
Model flexibility: use OpenRouter or direct LLM providers
Extensibility: add plugins, tools, commands, and hooks

Hermes is useful if you want:

An AI pair programmer that can remember your codebase
A shared assistant for a team or workspace
Long-running automation through scheduled tasks
Data for training or evaluating custom agent behavior

Installation

Prerequisites

Before installing Hermes, make sure you have:

macOS, Linux, or Windows with WSL recommended
Python 3.10+
Git
An API key from OpenRouter, Anthropic, OpenAI, or another supported provider

Quick Install

Use the installer script:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The script:

Clones the Hermes repository
Installs uv
Creates a Python virtual environment
Installs dependencies
Adds Hermes to your PATH

Reload your shell:

source ~/.bashrc  # bash
source ~/.zshrc   # zsh

Verify the installation:

hermes --version

You should see output similar to:

Hermes Agent v0.5.0

Manual Install

Use this path if you want to work on Hermes directly or control the environment yourself.

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

curl -LsSf https://astral.sh/uv/install.sh | sh

uv venv venv --python 3.11
source venv/bin/activate

On Windows:

.\venv\Scripts\activate

Install Hermes with all features:

uv pip install -e ".[all,dev]"

Run tests:

python -m pytest tests/ -q

Install RL Training Support

If you plan to train custom models, initialize the training submodule and install its dependencies:

git submodule update --init tinker-atropos
uv pip install -e "./tinker-atropos"

Initial Setup

Run the Setup Wizard

For first-time setup, use:

hermes setup

The wizard helps you configure:

LLM provider
API keys
Persistent memory
Terminal backend
Optional gateways such as Telegram, Discord, or Slack

Manual Configuration

Open the config file:

hermes config edit

Or set values directly:

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend local
hermes config set OPENROUTER_API_KEY sk-or-...
hermes config set ANTHROPIC_API_KEY sk-ant-...

Hermes stores API keys in:

~/.hermes/.env

Do not commit or share this file.

Configuration Directory

Hermes stores local data under ~/.hermes/:

~/.hermes/
├── config.yaml      # Main configuration
├── .env             # API keys
├── memory/          # Persistent memory storage
├── skills/          # Installed skills
└── plugins/         # Custom plugins

Verify Your Setup

Run:

hermes doctor

This checks:

Config validity
API key connectivity
Memory status
Gateway status
Terminal backend connection

Choose an LLM Provider

Hermes can work with multiple model providers. Pick the provider based on cost, privacy, context length, and coding quality requirements.

OpenRouter

OpenRouter is a good default because one API key gives access to many models.

hermes config set model openrouter
hermes config set OPENROUTER_API_KEY sk-or-...

Example model choices:

Model	Use case	Relative cost
`anthropic/claude-opus-4`	Complex coding and reasoning	High
`anthropic/claude-sonnet-4`	Balanced development work	Medium
`openai/gpt-4o`	General-purpose tasks	Medium
`google/gemini-pro-1.5`	Long-context workflows	Low
`meta/llama-3-70b`	Open-source, fast tasks	Low

Anthropic Direct

Use Anthropic directly if you want direct access to Claude models.

hermes config set model anthropic
hermes config set ANTHROPIC_API_KEY sk-ant-...
hermes config set model.default claude-opus-4

OpenAI Direct

Use OpenAI directly for GPT-4o or o1 workflows.

hermes config set model openai
hermes config set OPENAI_API_KEY sk-...

Local Models with Ollama

Use Ollama if you want local, private, offline-capable inference.

hermes config set model ollama
hermes config set model.default qwen2.5-coder:32b

Install Ollama first from:

https://ollama.ai

Example Model Config

Smart routing with fallbacks:

model:
  provider: openrouter
  default: anthropic/claude-opus-4
  fallback:
    - anthropic/claude-haiku-4-5
    - openai/gpt-4o-mini

Budget controls:

model:
  budget:
    daily_limit: 5.00
    monthly_limit: 100.00

Basic CLI Usage

Start Hermes:

hermes

Then chat naturally:

> Help me write a Python function to parse JSON safely.

Useful Slash Commands

> /help       # Show commands
> /skills     # Browse skills
> /memory     # View memory status
> /config     # View or edit config
> /clear      # Clear current conversation
> /history    # View past conversations

Work with Files

Ask Hermes to inspect a file:

> Look at ./src/main.py and explain the database connection flow.

Ask it to edit a file:

> In main.py, change the database port from 5432 to 5433.

Create a new file:

> Create utils.py with helper functions for date formatting.

Run Terminal Commands

You can ask Hermes to run commands:

> Run: npm install && npm run build

Hermes asks for confirmation before executing commands.

Use a Persistent Shell

Hermes keeps shell state across commands:

> cd /my/project && source venv/bin/activate
> python src/main.py

The virtual environment remains active for later commands in the same shell session.

Run Multi-Step Development Tasks

Example:

> Add user authentication to my Flask app:
> 1. Create database models
> 2. Add login and logout endpoints
> 3. Generate JWT tokens
> 4. Write tests for the auth flow

Hermes can break the task into steps and ask for confirmation as it works.

Messaging Gateways

Hermes can run as a bot in messaging platforms so you can use it from your phone or team chat.

Telegram Setup

Open Telegram and search for @BotFather
Send /newbot
Follow the prompts
Copy the bot token

Configure Hermes:

hermes config set TELEGRAM_BOT_TOKEN 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Start the gateway:

hermes gateway setup telegram
hermes gateway start

Then open your bot in Telegram, send /start, and chat.

Discord Setup

Go to https://discord.com/developers/applications
Create a new application
Open the Bot section
Create a bot and copy the token
Use OAuth2 → URL Generator to invite the bot to your server

Configure Hermes:

hermes config set DISCORD_BOT_TOKEN MTIzNDU2...
hermes gateway setup discord
hermes gateway start

Use it by mentioning the bot:

@Hermes help me write a function that validates email addresses

You can also use it in DMs.

Slack Setup

Go to https://api.slack.com/apps
Create a new app from scratch
Add bot permissions
Install the app to your workspace
Copy the bot token

Configure Hermes:

hermes config set SLACK_BOT_TOKEN xoxb-...
hermes gateway setup slack
hermes gateway start

Run All Gateways

To start every configured gateway:

hermes gateway start --all

Hermes syncs conversation state across platforms.

IDE Integration

Hermes integrates with editors through the Agent Communication Protocol.

VS Code

Open Extensions with Ctrl+Shift+X
Search for Agent Communication Protocol
Install the extension
Start the Hermes ACP server:

hermes acp start

Then open the ACP sidebar, select Hermes, and chat from the editor.

JetBrains IDEs

For IntelliJ, PyCharm, and other JetBrains IDEs:

Open Settings → Plugins
Search for ACP or Agent Communication Protocol
Install the plugin
Restart the IDE
Start Hermes:

hermes acp start

Then configure Hermes under:

Settings → Tools → AI Agents

Zed

Configure Zed:

{
  "agent": {
    "provider": "acp",
    "endpoint": "hermes"
  }
}

Start Hermes:

hermes acp start

Memory and Learning

Hermes uses memory to make future sessions more useful.

Memory Types

Type	Purpose
Episodic memory	Stores conversations and sessions
Semantic memory	Builds knowledge about projects, preferences, and patterns
Procedural memory	Stores reusable skills and workflows

Search memory:

> /memory search "database migration"

List project memory:

> /memory projects

List skills:

> /skills list

Search Past Sessions

Example:

> /memory search "How did we handle JWT expiration last week?"

Hermes searches prior context and summarizes relevant results.

Memory Nudges

Hermes can surface related context while you work:

[Hermes]: I noticed you're working on the auth system. Last Tuesday you
mentioned a problem with JWT expiration. Want to revisit that?

Context Compression

Hermes automatically compresses context to avoid hitting model limits:

Gateway compression at 85% context usage
Agent-level compression at 50%, configurable

This helps keep long conversations usable without manual pruning.

Backup and Restore Memory

Export memory:

hermes memory export ~/backup/hermes-memory.json

Import memory:

hermes memory import ~/backup/hermes-memory.json

Skills and Plugins

Skills

Skills are reusable workflows Hermes can execute.

Built-in examples include:

code_review
debug_session
api_tester
git_workflow
documentation

List skills:

> /skills list

Install a skill:

> /skills install code_review

Run a skill:

> /skills run code_review ./src/auth.py

Create a Custom Skill

Create a file under ~/.hermes/skills/:

# ~/.hermes/skills/my_skill.py
from hermes.skills import Skill

class MyCustomSkill(Skill):
    name = "my_custom_skill"
    description = "Does something useful"

    def execute(self, context):
        # Your skill logic here
        return "Skill executed successfully"

Plugins

Plugins extend Hermes with custom tools, slash commands, and lifecycle hooks.

Example custom tool:

# ~/.hermes/plugins/my_tool.py
from hermes.tools import Tool

class MyCustomTool(Tool):
    name = "my_tool"
    description = "A custom tool for specific tasks"

    def run(self, **kwargs):
        # Tool logic here
        return {"result": "success"}

Plugin types:

Tools: new capabilities the agent can use
Commands: new slash commands
Hooks: before/after turn handlers

Advanced Workflows

Cron Scheduling

Ask Hermes to create a scheduled task:

> Set up a daily digest of my GitHub notifications at 9am.

Or configure a task manually:

cron:
  - name: "Daily digest"
    schedule: "0 9 * * *"
    command: "/skills run github_digest"
    model: "anthropic/claude-haiku-4-5"

Subagent Delegation

Hermes can spawn subagents for parallel work.

Example:

> Review all PRs in my repo and summarize the changes.

Hermes can delegate work to multiple subagents and synthesize the results.

Voice Mode

Start CLI voice mode:

hermes --voice

Messaging platforms can also support voice-note workflows:

Send a voice message
Hermes transcribes it
Hermes responds in the chat

For Discord voice channels, Hermes can join and handle real-time voice interaction.

Browser Control

Hermes can integrate with Browser Use CLI 2.0 for web automation.

Example:

> Go to github.com and find the top 5 trending Python repos.

Connect to a live Chrome instance with CDP:

hermes browser connect --cdp

MCP Integration

Hermes supports Model Context Protocol servers.

Example config:

mcp:
  servers:
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "~/projects"]
    git:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-git"]

Worktree Mode

Run Hermes in an isolated Git worktree:

hermes -w

This lets multiple agents work on the same repo concurrently without conflicting changes.

Run Other Agents Inside Hermes

You can ask Hermes to call another specialized agent:

> Use claude-code to review this pull request.

This is useful when a subagent is better suited for a specific task.

Troubleshooting

API Key Not Found

Check whether the key is set:

hermes config get OPENROUTER_API_KEY

Set it again if needed:

hermes config set OPENROUTER_API_KEY sk-or-...

Model Not Available

List available models:

hermes models list

Change the model:

hermes config set model anthropic/claude-opus-4

Gateway Failed to Start

Check status:

hermes gateway status

Restart:

hermes gateway stop
hermes gateway start

Memory Corruption Detected

Back up memory first:

hermes memory export ~/backup/memory-backup.json

Reset memory:

hermes memory reset

Re-import if needed:

hermes memory import ~/backup/memory-backup.json

Get Help

Inside Hermes:

> /help

View logs:

hermes logs tail --follow

Run diagnostics:

hermes doctor

FAQ

How much does Hermes cost?

Hermes itself is free. You pay for LLM usage.

Typical monthly ranges:

Light use: $5–15
Moderate development use: $20–50
Heavy automation: $50–200

Local models through Ollama can avoid API usage costs but require suitable hardware.

Can Hermes run 24/7?

Yes. For example, on a VPS:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

hermes service install
hermes service start

Is Hermes suitable for enterprise use?

Hermes includes features relevant to enterprise deployments, including:

Multi-user gateway mode with session isolation
PII redaction
Supply chain security hardening
Self-hosted deployment
Audit logging

How do I migrate from OpenClaw?

Preview the migration:

hermes claw migrate --dry-run

Run it:

hermes claw migrate

Verify the result:

hermes doctor

Can I use Hermes without internet?

Yes, with local models.

Install Ollama:

curl -fsSL https://ollama.ai/install.sh | sh

Pull a model:

ollama pull qwen2.5-coder:32b

Configure Hermes:

hermes config set model ollama
hermes config set model.default qwen2.5-coder:32b

Hermes vs. ChatGPT

Feature	Hermes	ChatGPT
Memory	Persistent and searchable	Session-only
Deployment	Self-hosted, can run 24/7	Cloud-only
Model choice	200+ models	GPT models
Extensibility	Plugins and skills	Limited
Cost model	Pay for usage	Subscription
Privacy	You control deployment and data	OpenAI stores data

How do I back up all Hermes data?

hermes export --all ~/backup/hermes-full-backup.tar.gz

Can Hermes access my local files?

Hermes can access files you explicitly reference or directories you grant permission to. By default, it does not have unrestricted filesystem access.

Want to include API testing in your AI-assisted development workflow? Use Apidog to design, test, and document APIs alongside your agent-based coding process.

Qwen 3.6 Available on OpenRouter: How to Use It Right Now

Preecha — Thu, 25 Jun 2026 01:03:12 +0000

TL;DR

Qwen 3.6 Plus Preview launched on March 30, 2026, with a 1-million-token context window, mandatory chain-of-thought reasoning, and tool use support. It is currently free on OpenRouter. Use the model ID qwen/qwen3.6-plus-preview:free with any OpenAI-compatible client to start sending requests.

Try Apidog today

The model that showed up quietly

Alibaba Cloud released Qwen 3.6 Plus Preview on March 30, 2026. There was no waitlist or major launch campaign. The model appeared on OpenRouter at $0 per million tokens.

In its first two days, it processed more than 400 million completion tokens across roughly 400,000 requests. Developers also reported fast responses.

This guide shows how to:

Create an OpenRouter account
Generate an API key
Call Qwen 3.6 with cURL, Python, Node.js, and the OpenAI SDK
Use tool calling for agentic workflows
Work with the 1M-token context window
Test OpenRouter requests with Apidog
Plan around free-tier limitations

If you build on top of AI APIs, you also need a reliable way to test and debug HTTP requests. Apidog can help with request building, response inspection, and API test automation for REST APIs including OpenRouter.

By the end, you should be able to call Qwen 3.6 for free, understand where it works well, and know what constraints to account for before using it in an app.

What Qwen 3.6 adds over the 3.5 series

The jump from Qwen 3.5 to Qwen 3.6 is meaningful in three areas.

1. The context window grew to 1 million tokens

Qwen 3.5 supported a 32K to 128K context window depending on the variant. Qwen 3.6 supports up to 1 million input tokens.

In practical terms, 1 million tokens is roughly 750,000 words. That is enough to pass in:

A large codebase
Long Slack or support logs
A full legal document set
A research corpus
Large API documentation sets

Most free models top out around 8K to 32K tokens, so 1M tokens at the free tier is unusual.

2. Reasoning is built in

Qwen 3.6 uses mandatory reasoning tokens. Before returning the final answer, the model performs internal chain-of-thought reasoning.

You do not need to add prompts like:

Think step by step.

This is similar to the pattern popularized by DeepSeek R1. Qwen 3.6 applies it across coding, front-end development, and general problem-solving tasks.

3. Tool use is more reliable

Tool calling in the Qwen 3.5 series could be inconsistent. Common issues included:

Incorrect function argument types
Hallucinated tool names
Invalid JSON arguments
Missed tool calls in multi-step workflows

Alibaba Cloud describes Qwen 3.6 as delivering “stronger reasoning and more reliable agentic behavior compared to the 3.5 series.”

For developers, that mainly means fewer broken tool calls when building agents.

Qwen 3.6 is tuned for:

Agentic coding: multi-step code generation with tool use
Front-end development: HTML, CSS, JavaScript, and component generation
Complex problem-solving: research, analysis, and long-context summarization

How to access Qwen 3.6 for free

You need:

An OpenRouter account
An OpenRouter API key

No credit card is required for free models.

Step 1: Create an OpenRouter account

Go to openrouter.ai and sign up with email or Google.

After email verification, you can use free models without adding a payment method.

Step 2: Generate an API key

In OpenRouter:

Click your profile avatar in the top-right corner
Select API Keys
Click Create Key
Give the key a name, for example qwen-test
Click Create
Copy the key

The key starts with:

sk-or-v1-...

Store it securely. OpenRouter will not show it again.

Step 3: Send your first request

Use this model ID:

qwen/qwen3.6-plus-preview:free

OpenRouter uses an OpenAI-compatible API format, so most OpenAI SDKs and clients work with only a base URL change.

cURL

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer sk-or-v1-YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3.6-plus-preview:free",
    "messages": [
      {
        "role": "user",
        "content": "Write a Python function that parses a JWT token and returns the payload as a dictionary."
      }
    ]
  }'

Python with `requests`

import requests

def call_qwen(prompt: str, api_key: str) -> str:
    response = requests.post(
        "https://openrouter.ai/api/v1/chat/completions",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={
            "model": "qwen/qwen3.6-plus-preview:free",
            "messages": [{"role": "user", "content": prompt}],
        },
        timeout=60,
    )

    response.raise_for_status()
    return response.json()["choices"][0]["message"]["content"]

result = call_qwen(
    "Write a Python function that parses a JWT token and returns the payload.",
    api_key="sk-or-v1-YOUR_KEY_HERE",
)

print(result)

Node.js with `fetch`

async function callQwen(prompt, apiKey) {
  const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "qwen/qwen3.6-plus-preview:free",
      messages: [{ role: "user", content: prompt }],
    }),
  });

  if (!response.ok) {
    throw new Error(`OpenRouter error: ${response.status} ${await response.text()}`);
  }

  const data = await response.json();
  return data.choices[0].message.content;
}

callQwen(
  "Write a JavaScript function that validates an email address.",
  "sk-or-v1-YOUR_KEY_HERE"
).then(console.log);

Python with the OpenAI SDK

If you already use the OpenAI Python SDK, point it at OpenRouter:

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="sk-or-v1-YOUR_KEY_HERE",
)

response = client.chat.completions.create(
    model="qwen/qwen3.6-plus-preview:free",
    messages=[
        {
            "role": "system",
            "content": "You are a senior backend engineer. Write clean, production-ready code.",
        },
        {
            "role": "user",
            "content": "Write a Python function that retries a failed HTTP request up to 3 times with exponential backoff.",
        },
    ],
)

print(response.choices[0].message.content)

Tool use and agentic workflows

Tool use is where Qwen 3.6 is especially useful at the free tier.

The pattern is:

Define tools as JSON schemas
Send the user request plus tool definitions
Let the model choose a tool
Execute the tool in your code
Send the tool result back to the model
Repeat until the task is complete

Here is a minimal tool-calling example:

from openai import OpenAI
import json

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="sk-or-v1-YOUR_KEY_HERE",
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_api_docs",
            "description": "Search the API documentation for a specific endpoint or parameter",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The search query",
                    },
                    "version": {
                        "type": "string",
                        "enum": ["v1", "v2", "v3"],
                        "description": "API version to search",
                    },
                },
                "required": ["query"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "run_api_test",
            "description": "Execute a test request against an API endpoint",
            "parameters": {
                "type": "object",
                "properties": {
                    "endpoint": {"type": "string"},
                    "method": {
                        "type": "string",
                        "enum": ["GET", "POST", "PUT", "DELETE"],
                    },
                    "body": {"type": "object"},
                },
                "required": ["endpoint", "method"],
            },
        },
    },
]

messages = [
    {
        "role": "user",
        "content": "Find documentation for the /users endpoint and run a test GET request against it.",
    }
]

response = client.chat.completions.create(
    model="qwen/qwen3.6-plus-preview:free",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

message = response.choices[0].message

if message.tool_calls:
    for tool_call in message.tool_calls:
        print(f"Tool: {tool_call.function.name}")

        args = json.loads(tool_call.function.arguments)
        print(f"Arguments: {json.dumps(args, indent=2)}")
else:
    print(message.content)

The model should return a structured function call instead of a free-form answer. Your app is still responsible for executing the function and returning the result in the next turn.

That loop is the core of most agentic workflows.

Using the 1 million token context window

A 1M-token context window is not useful for simple prompts. It is useful when the model needs a large amount of context in a single request.

Good use cases include:

Full codebase review
Large document analysis
Long technical debugging sessions
API documentation comparison
Research corpus summarization

Full codebase review

You can load source files into one prompt and ask the model to inspect them for specific issues.

from pathlib import Path
from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="sk-or-v1-YOUR_KEY_HERE",
)

def load_codebase(directory: str, extensions: list[str]) -> str:
    """Load all source files from a directory into a single string."""
    content_parts = []

    for path in Path(directory).rglob("*"):
        if path.suffix in extensions and path.is_file():
            try:
                text = path.read_text(encoding="utf-8", errors="ignore")
                content_parts.append(f"--- FILE: {path} ---\n{text}\n")
            except Exception:
                continue

    return "\n".join(content_parts)

codebase = load_codebase("./src", [".py", ".js", ".ts"])

response = client.chat.completions.create(
    model="qwen/qwen3.6-plus-preview:free",
    messages=[
        {
            "role": "user",
            "content": (
                "Review this codebase and identify:\n"
                "1. Security vulnerabilities\n"
                "2. Functions with no error handling\n"
                "3. Inconsistent naming conventions\n\n"
                f"Codebase:\n{codebase}"
            ),
        }
    ],
)

print(response.choices[0].message.content)

When using this pattern, filter out files that add noise:

node_modules
Build artifacts
Lock files
Generated files
Binary files
Test snapshots

Large document analysis

For long reports, legal documents, or API docs, pass the full document and ask for specific extraction.

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="sk-or-v1-YOUR_KEY_HERE",
)

with open("annual_report_2025.txt", "r", encoding="utf-8") as f:
    document = f.read()

response = client.chat.completions.create(
    model="qwen/qwen3.6-plus-preview:free",
    messages=[
        {
            "role": "user",
            "content": (
                "Extract all mentions of API rate limits and pricing changes "
                f"from this document:\n\n{document}"
            ),
        }
    ],
)

print(response.choices[0].message.content)

Multi-turn conversation with full history

For long debugging sessions, keep the entire conversation in memory and send it with each request.

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="sk-or-v1-YOUR_KEY_HERE",
)

conversation = []

def chat(user_message: str) -> str:
    conversation.append({"role": "user", "content": user_message})

    response = client.chat.completions.create(
        model="qwen/qwen3.6-plus-preview:free",
        messages=conversation,
    )

    assistant_message = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": assistant_message})

    return assistant_message

print(chat("I'm getting a 401 error from the GitHub API. Here's my code..."))
print(chat("I added the token but now I get a 403. The token has repo scope."))
print(chat("The repo is private. What scopes do I actually need?"))

Testing OpenRouter API requests with Apidog

When you build against the OpenRouter API, you need to debug HTTP requests, inspect JSON responses, and iterate on prompts. Doing that only from the command line can get slow.

Apidog is a free API client for request building, response inspection, and test automation.

To test Qwen 3.6 in Apidog:

Create a new POST request
Set the URL:

https://openrouter.ai/api/v1/chat/completions

Add the authorization header:

Authorization: Bearer sk-or-v1-YOUR_KEY_HERE

Add the content type header:

Content-Type: application/json

Set the request body:

{
  "model": "qwen/qwen3.6-plus-preview:free",
  "messages": [
    {
      "role": "user",
      "content": "Write a TypeScript function that validates an email address."
    }
  ]
}

Send the request and inspect the response.

You can also save the request in a collection and create tests such as:

choices exists
choices[0].message.content is not empty
choices[0].message.tool_calls contains the expected function name
The response status is 200
The model returns valid JSON when your prompt requires JSON

For example, a basic response-shape test could assert that the assistant message exists before your app depends on it.

If your app calls OpenRouter in production, adding these tests early makes it easier to catch model, schema, or integration regressions.

Free tier limits to know before you build

Qwen 3.6 is free now, but you should still design around free-tier constraints.

Rate limits are shared

Free models on OpenRouter share capacity across users. During peak hours, such as US evenings, you may see:

Higher latency
Occasional rate limit errors
Temporary failures

Add retry logic before using the endpoint in any production workflow.

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

session = requests.Session()

retry_strategy = Retry(
    total=3,
    backoff_factor=2,
    status_forcelist=[429, 500, 502, 503, 504],
)

adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("https://", adapter)

response = session.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-or-v1-YOUR_KEY_HERE",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen/qwen3.6-plus-preview:free",
        "messages": [{"role": "user", "content": "Hello"}],
    },
    timeout=30,
)

response.raise_for_status()
print(response.json())

Data is logged

OpenRouter’s model page states that “the model collects prompt and completion data that can be used to improve the model.”

Do not send:

API keys
Passwords
Private tokens
Personally identifiable information
Confidential customer data

Preview behavior can change

Qwen 3.6 Plus Preview is a preview release. Model behavior may change.

If you use it for production inference:

Pin your integration to the current model ID
Add regression tests for important prompts
Monitor response format changes
Keep fallback model options ready

Text only

Qwen 3.6 accepts text input and produces text output.

It does not support:

Images
Audio
File uploads

Real-world use cases

Code review agent

A team building an internal PR review tool can pass full pull request diffs into Qwen 3.6 and ask for:

Logic errors
Missing tests
Security issues
Risky dependency changes
Inconsistent patterns

The 1M-token context window makes this possible without splitting many large diffs into chunks.

Front-end component generation

For front-end work, you can give the model a design spec and ask for React, TypeScript, HTML, CSS, or JavaScript components.

Example prompt:

Generate a responsive React TypeScript pricing table component.

Requirements:
- Three pricing tiers
- Monthly and yearly toggle
- Accessible buttons
- Mobile-first layout
- Tailwind CSS classes

Qwen 3.6 is tuned for front-end development tasks, so this is a strong fit.

API documentation summarization

If you are comparing two third-party APIs, pass in the relevant docs and ask for a structured comparison.

Useful comparison dimensions include:

Authentication methods
Rate limits
Webhook payloads
Error response formats
Pagination models
Pricing-related API constraints

Example prompt:

Compare these two payment API documentation sets.

Return a table with:
1. Authentication method
2. Webhook verification flow
3. Rate limit policy
4. Pagination style
5. Refund API behavior
6. Migration risks

FAQ

Is Qwen 3.6 actually free to use?

Yes. As of March 2026, the model is listed at $0 per million input tokens and $0 per million output tokens on OpenRouter.

That can change when the preview period ends, so check OpenRouter pricing before building anything that depends on the price staying at zero.

What is the rate limit for the free tier?

OpenRouter does not publish exact rate limits for free-tier models.

In practice, free models share capacity and can be throttled during high-traffic periods. Start with one request at a time, add retry logic, and increase concurrency gradually.

Can I use Qwen 3.6 for commercial projects?

Yes, OpenRouter allows commercial use.

Also check Alibaba Cloud’s Qwen model license for restrictions on the underlying model, especially if you are distributing outputs.

Why does Qwen 3.6 take longer to respond than other models?

Mandatory reasoning tokens add latency. Before producing the final response, the model performs internal reasoning.

For simple prompts, this can add a few seconds. For complex reasoning tasks, the tradeoff may be worth it.

Use streaming if you want to show partial output while the response is generated.

Is there a way to disable reasoning tokens?

As of the current preview, reasoning is mandatory and cannot be turned off.

If you need lower latency without chain-of-thought reasoning, use a different model variant when available or a smaller free model for latency-sensitive tasks.

How does the 1M-token context window affect cost?

On the free tier, it does not affect cost. You pay $0 regardless of the number of tokens sent.

However, very large requests take longer and may time out. Start with a 30 to 60 second timeout and increase it for requests over 100K tokens.

Final setup checklist

To start using Qwen 3.6:

Create an OpenRouter account
Generate an API key
Use this model ID:

qwen/qwen3.6-plus-preview:free

Send requests to:

https://openrouter.ai/api/v1/chat/completions

Add retry logic for 429 and 5xx errors
Avoid sending secrets or sensitive data
Test your requests and response assumptions before shipping

Once your API key is ready, you can swap qwen/qwen3.6-plus-preview:free into any OpenAI-compatible client and start testing.

Claude Code Can Now Control Your Mac. Here's How to Use It

Preecha — Wed, 24 Jun 2026 13:03:13 +0000

TL;DR

Claude Code can now control your Mac from the same terminal session where it writes code. It can open apps, click through UIs, run tests, capture screenshots, and use the results to patch code. The feature is a research preview for Pro and Max plan subscribers on macOS.

Try Apidog today

To enable it, run /mcp in Claude Code, enable the computer-use MCP server, then grant macOS Accessibility and Screen Recording permissions.

Claude can now use your computer

Anthropic announced Claude Code computer use on March 23, 2026. The workflow is simple: Claude writes code, runs it, interacts with the UI, observes the result, and fixes issues without you leaving the terminal.

Before computer use, Claude could generate a macOS menu bar app, but you still had to compile it, launch it, click through the UI, and report back what failed.

Now you can ask for the whole loop:

Build this app and make sure it works.

Claude can compile the project, launch the binary, interact with controls, screenshot failures, inspect the relevant source, patch the issue, and re-run the flow.

That changes the unit of work from:

Write this feature.

to:

Build this feature, run it, and verify the UI behavior.

If you’re building on APIs, this is useful for GUI-driven flows that do not expose a CLI or API. Claude can verify the app behavior visually, and you can then build automated API test suites in Apidog to validate the same flows programmatically.

What you can do with it

Build and validate native apps end-to-end

Use computer use when you want Claude to verify the result in the actual app, not just generate code.

Example prompt:

Build the MenuBarStats target, launch it, open the preferences window,
and verify the interval slider updates the label. Screenshot the
preferences window when done.

Claude can:

Run xcodebuild
Launch the compiled app
Open the preferences window
Move the slider
Check whether the label updates
Screenshot the final state
Patch and re-test if something fails

You get a verified build instead of a code-only draft.

Run UI checks without setting up a test framework

For early-stage projects, you may not want to configure Playwright, Selenium, or XCTest yet.

Prompt Claude with the flow:

Open the app, click through the onboarding screens, and tell me if any
screen takes more than a second to load.

Claude can open the app, click through the UI, screenshot each step, and flag slow or broken transitions.

This is useful for:

Electron apps
Native macOS apps
iOS Simulator flows
GUI-only tools
Prototypes without formal test coverage

It is not a replacement for deterministic production test suites, but it is fast for exploratory validation.

Debug visual and layout bugs

Visual bugs are often hard to describe precisely. With computer use, Claude can reproduce the UI state directly.

Example:

The settings modal clips its footer on narrow windows. Resize the app
window until you can reproduce it, screenshot the clipped state, then
check the CSS for the modal container.

Claude can:

Resize the app window
Capture the broken layout
Inspect the relevant CSS
Apply a fix
Re-test the same window size

This works well for issues such as:

Overflow bugs
Clipped footers
Broken responsive layouts
Misaligned controls
Modals that fail at narrow widths

Drive GUI-only tools

Some tools do not expose useful automation APIs. Examples include design tools, hardware control panels, proprietary enterprise apps, and simulators.

With computer use, you can describe the interaction in natural language and let Claude operate the UI.

Open the simulator, launch the app, tap through onboarding, and screenshot
each screen where the UI changes.

How to enable computer use

Computer use is disabled by default. It ships as a built-in MCP server named computer-use, and you enable it per project.

Before you start, confirm these requirements:

macOS only
Claude Code v2.1.85 or later
Pro or Max plan
Authentication through claude.ai
Interactive Claude Code session
Not using the -p non-interactive flag

Check your Claude Code version:

claude --version

Update if needed:

npm install -g @anthropic-ai/claude-code

Step 1: Open the MCP menu

In an active Claude Code session, run:

/mcp

This opens the server list.

Find:

computer-use

It should appear as disabled.

Step 2: Enable the server

Select computer-use, then choose Enable.

This setting persists per project. You only need to enable it once for each project where you want Claude to control the GUI.

Step 3: Grant macOS permissions

The first time Claude tries to control your screen, macOS prompts for two permissions:

Accessibility: allows Claude to click, type, and scroll
Screen Recording: allows Claude to see what is on screen

The prompts include links to the relevant System Settings panes.

After granting Screen Recording, restart Claude Code if the permission does not take effect immediately.

Step 4: Run a GUI verification prompt

Try a small, low-risk workflow first:

Build the app target, launch it, and click through each tab to confirm
nothing crashes. Screenshot any error states you find.

Start with test apps or isolated development environments before using computer use on workflows that contain sensitive data.

How Claude works on your screen

Only one session can control your Mac

Computer use uses a machine-wide lock.

If another Claude Code session is already using computer use, new requests fail with a message showing which session holds the lock.

To continue:

Finish the active computer use task.
Exit the other Claude Code session.
Retry the request.

Other apps hide while Claude works

When Claude takes control, visible apps hide so Claude interacts only with approved apps.

Your terminal stays visible, but it is excluded from screenshots. This prevents Claude from seeing its own prompts on screen.

When Claude finishes a turn, hidden apps restore automatically.

You can stop it immediately

When Claude acquires the lock, macOS shows a notification:

Claude is using your computer - press Esc to stop.

You can stop computer use in either of these ways:

Press Esc from anywhere
Press Ctrl+C in the terminal

Claude releases the lock, restores hidden apps, and returns control to you.

Per-app approval

Enabling computer-use does not give Claude access to every app.

The first time Claude needs a specific app in a session, Claude Code shows a terminal approval prompt with:

Which apps Claude wants to control
Any extra permissions requested, such as clipboard access
How many other apps will hide while Claude works

You can choose:

Allow for this session
Deny

Approvals last only for the current session. You approve apps again in the next session.

Apps with extra warnings

Some app categories show additional warnings because they grant broad access.

Warning	Apps
Equivalent to shell access	Terminal, iTerm2, VS Code, Warp, other terminals and IDEs
Can read or write any file	Finder
Can change system settings	System Settings

These apps are not blocked automatically. The warning exists so you can decide whether the task needs that level of access.

App control tiers

Claude’s control level depends on the app category.

Control level	App types
View-only	Browsers, trading platforms
Click-only	Terminals, IDEs
Full control	All other apps

Browsers are view-only because they can expose account data and sensitive information. If you need full browser automation, use Claude in Chrome instead.

How Claude decides when to use computer use

Computer use is Claude’s last resort.

Claude chooses the most precise available tool first:

MCP server for the service, if configured
Bash for shell commands
Claude in Chrome for browser tasks, if configured
Computer use when no programmatic interface can reach the target

For example, if you ask:

Run the tests.

Claude should use a shell command such as:

npm test

It should not click a UI button unless the target workflow requires GUI interaction.

Use computer use for tasks like:

Native desktop app validation
iOS Simulator flows
GUI-only tools
Visual bug reproduction
App interactions without a CLI or API

Safety model

Computer use runs on your real desktop. That is different from Claude’s sandboxed Bash tool.

The Bash tool runs in an isolated environment with limited filesystem and network access. Computer use can interact with apps on your actual machine, depending on what you approve.

Anthropic built several guardrails into the feature.

Per-app approval

Claude can only control apps you explicitly allow in the current session.

There is no blanket machine-wide approval.

Sentinel warnings

Apps that expose shell access, filesystem access, or system settings changes are flagged before approval.

This helps you understand what level of access you are granting.

Terminal excluded from screenshots

Claude does not see your terminal window in screenshots.

This prevents on-screen terminal prompts from being fed back into the model.

Global escape

Pressing Esc aborts computer use from anywhere.

The key press is consumed by Claude Code, so prompt injection attacks cannot use it to dismiss dialogs.

Lock file

Only one Claude Code session can control your screen at a time.

This prevents concurrent computer use sessions from competing for the same machine.

Prompt injection detection

Claude checks actions and flags on-screen content that appears to be an attempt to redirect its behavior.

Anthropic’s guidance is to avoid sensitive workflows until you are comfortable with how computer use behaves on your machine. Start with sandboxed apps, test environments, and non-sensitive data.

Example workflows

End-to-end Swift app validation

Prompt:

Build the MenuBarStats target, launch it, open the preferences window,
and verify the interval slider updates the label. Screenshot the
preferences window when done.

Expected Claude workflow:

Run xcodebuild
Launch the app
Open the preferences window
Move the interval slider
Verify that the label updates
Capture a screenshot
Report failures with source locations
Patch and re-test if needed

Reproduce a layout bug

Prompt:

The settings modal clips its footer on narrow windows. Resize the app
window down until you can reproduce it, screenshot the clipped state,
then check the CSS for the modal container.

Expected Claude workflow:

Resize the window in increments
Capture the clipped state
Inspect modal.css
Identify the overflow issue
Apply a layout fix
Re-test at the failing size

Test an iOS Simulator flow without XCTest

Prompt:

Open the iOS Simulator, launch the app, tap through the onboarding
screens, and tell me if any screen takes more than a second to load.

Claude controls the Simulator through the GUI. You do not need to create XCTest targets, UI test selectors, or Instruments configuration for this exploratory pass.

Validate an Electron onboarding flow

Prompt:

Launch the desktop app in dev mode, complete the signup flow using
test@example.com, and screenshot each step. Flag any step where the
button is not clickable or the UI shows an error.

Claude can:

Start the app
Fill form fields
Click through each onboarding screen
Capture screenshots
Report blocked buttons or UI errors

Using computer use with API testing

Claude Code computer use pairs well with Apidog for full-stack API verification.

A practical workflow:

Claude writes or updates a local server.
Claude builds and launches the app.
Claude uses computer use to trigger a user action in the UI.
You capture or inspect the underlying API call in Apidog.
You create an automated API test for the same request.
Future regressions are caught by the API test instead of manual UI validation.

This gives you two layers:

Claude validates the user-facing flow through the GUI.
Apidog validates the underlying API behavior programmatically.

The GUI pass confirms the happy path. The API test guards that behavior going forward, including in CI.

Differences between CLI and Desktop app

The CLI and Desktop app use the same computer use engine, but some settings are Desktop-only for now.

Feature	Desktop	CLI
Enable	Settings > Desktop app > General	`/mcp` > enable `computer-use`
Denied apps list	Configurable in Settings	Not available yet
Auto-unhide toggle	Optional	Always on
Dispatch integration	Yes	Not applicable

For most development workflows, the CLI version covers the core computer use flow.

Troubleshooting

“Computer use is in use by another Claude session”

Another Claude Code session holds the machine lock.

Fix:

Exit the other session.
If it crashed, wait for Claude Code to detect that the process is gone.
Retry the computer use request.

macOS permissions prompt keeps reappearing

macOS may require a process restart after granting Screen Recording.

Fix:

Quit Claude Code completely.
Start a new Claude Code session.
Open System Settings > Privacy & Security > Screen Recording.
Confirm your terminal emulator is listed and enabled.

Also check Accessibility permissions in the same Privacy & Security area.

`computer-use` does not appear in `/mcp`

Check the following:

You are on macOS.
claude --version shows v2.1.85 or later.
You are on a Pro or Max plan.
/status confirms the expected account.
You are authenticated through claude.ai.
You are not using Bedrock, Vertex AI, or another third-party provider.
You are in an interactive session.
You are not using the -p flag.

Claude cannot see the app after approval

Make sure you selected Allow for this session in the per-app approval prompt.

If you accidentally denied the app:

Exit the Claude Code session.
Start a new session.
Retry the task.
Approve the app when prompted.

Approvals and denials reset each session.

FAQ

Which Claude Code version do I need?

You need Claude Code v2.1.85 or later.

Check your version:

claude --version

Update if needed:

npm install -g @anthropic-ai/claude-code

Does it work on Windows or Linux?

No. Computer use is macOS-only in the current research preview.

Anthropic has not announced a timeline for Windows or Linux support.

Can I use computer use through Amazon Bedrock or Google Vertex AI?

No. Computer use requires authentication through a claude.ai account on a Pro or Max plan.

Third-party providers such as Amazon Bedrock, Google Vertex AI, and Microsoft Foundry do not support this feature.

Is it available on Team or Enterprise plans?

No. During the research preview, it is available only on Pro and Max plans.

What happens if I do not grant Screen Recording permission?

Claude may still click and type if Accessibility is granted, but it cannot verify visual results without Screen Recording.

Most useful computer use workflows require both permissions.

Can Claude access apps I did not approve?

No. Claude can only control apps you explicitly approve in the current session.

The approval prompt appears the first time Claude needs each app.

How do I revoke computer use access completely?

Disable the MCP server:

/mcp

Then disable:

computer-use

To remove macOS permissions:

Open System Settings > Privacy & Security.
Remove your terminal app from Accessibility.
Remove your terminal app from Screen Recording.

Is computer use safe for sensitive work?

Anthropic recommends avoiding sensitive data during the research preview.

Start with:

Isolated test environments
Local development apps
Non-production accounts
Non-sensitive datasets

Review Anthropic’s computer use safety guidance before using it with credentials, personal data, production systems, or regulated workflows.

Can multiple Claude Code sessions use computer use at the same time?

No. Computer use holds a machine-wide lock.

Only one Claude Code session can control your screen at a time. If another session holds the lock, Claude Code shows an error with the session details.

How is this different from Playwright or Selenium?

Playwright and Selenium are scripted test frameworks. They require selectors, assertions, configuration, and test maintenance.

Computer use lets Claude interact with an app through natural language, without a test harness.

Use computer use for:

Exploratory testing
Quick UI validation
Visual bug reproduction
GUI-only tools
Apps that do not expose automation APIs

Use Playwright, Selenium, XCTest, or similar tools for:

Deterministic regression tests
CI pipelines
Repeatable production test coverage
Complex assertions
Long-term test suites

Computer use is faster to start. Scripted tests are more reliable over time.

How to Use Qwen3.5-Omni: Text, Audio, Video, and Voice Cloning via API

Preecha — Wed, 24 Jun 2026 01:03:30 +0000

TL;DR

Qwen3.5-Omni accepts text, images, audio, and video as input and returns text or real-time speech. You can access it through the Alibaba Cloud DashScope API or run it locally with HuggingFace Transformers. This guide walks through API setup, working examples for each modality, voice cloning, streaming, local deployment, retries, and testing with Apidog.

Try Apidog today

What you’re working with

Qwen3.5-Omni is a single multimodal model that handles four input types in one request:

Text
Images
Audio
Video

It can return either text or natural speech, depending on your request configuration.

Released March 30, 2026, Qwen3.5-Omni uses a Thinker-Talker architecture with an MoE backbone:

Thinker: processes multimodal input and performs reasoning.
Talker: converts output into speech using a multi-codebook system that can start streaming audio before the full response is complete.

Available variants:

Variant	Best for
Plus	Highest quality, reasoning, voice cloning
Flash	Balanced speed and quality for most production use
Light	Lowest latency for mobile and edge scenarios

Most examples below use qwen3.5-omni-flash. Use qwen3.5-omni-plus when quality matters most, and qwen3.5-omni-light when latency is the main constraint.

API access via DashScope

Alibaba Cloud DashScope is the primary hosted API for Qwen3.5-Omni. You need:

A DashScope account
A DashScope API key
Either the DashScope SDK or the OpenAI-compatible API endpoint

Step 1: Create a DashScope account

Go to dashscope.aliyuncs.com and sign up. If you already have an Alibaba Cloud account, use that account.

Step 2: Create an API key

In the DashScope console:

Open API Key Management.
Click Create API Key.
Copy the key.

The key format starts with:

sk-...

Step 3: Install an SDK

Install the DashScope SDK:

pip install dashscope

Or use the OpenAI Python SDK with DashScope’s OpenAI-compatible endpoint:

pip install openai

DashScope exposes an OpenAI-compatible API at:

https://dashscope.aliyuncs.com/compatible-mode/v1

That means you can reuse OpenAI-style chat completion code by changing base_url and api_key.

Text input and output

Start with the simplest request: text in, text out.

from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

response = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    messages=[
        {
            "role": "user",
            "content": "Explain the difference between REST and GraphQL APIs in plain terms."
        }
    ],
)

print(response.choices[0].message.content)

Use a different model ID when needed:

model="qwen3.5-omni-plus"   # better quality
model="qwen3.5-omni-flash"  # balanced default
model="qwen3.5-omni-light"  # lower latency

Audio input: transcription and understanding

You can send audio as a URL or as base64-encoded data. The model can transcribe and reason over the audio directly, so you do not need a separate ASR step.

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

with open("meeting_recording.wav", "rb") as f:
    audio_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_audio",
                    "input_audio": {
                        "data": audio_data,
                        "format": "wav"
                    }
                },
                {
                    "type": "text",
                    "text": "Summarize the key decisions made in this meeting and list any action items."
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)

Qwen3.5-Omni handles 113 languages for speech recognition and detects the language automatically.

Supported audio formats include:

WAV
MP3
M4A
OGG
FLAC

Audio output: text-to-speech response

To receive speech in the response, set modalities and configure the audio output.

from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

response = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    modalities=["text", "audio"],
    audio={"voice": "Chelsie", "format": "wav"},
    messages=[
        {
            "role": "user",
            "content": "Describe the steps to authenticate a REST API using OAuth 2.0."
        }
    ],
)

text_content = response.choices[0].message.content
audio_data = response.choices[0].message.audio.data

with open("response.wav", "wb") as f:
    f.write(base64.b64decode(audio_data))

print(f"Text: {text_content}")
print("Audio saved to response.wav")

Built-in voices:

Chelsie
Ethan

Speech generation works in 36 languages.

Image input: visual understanding

Send an image URL with a text prompt when you want the model to inspect visual content.

from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

response = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/api-diagram.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Describe this API architecture diagram and identify any potential bottlenecks."
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)

For local images, encode the file as base64 and pass it as a data URL.

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

with open("screenshot.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

image_url = f"data:image/png;base64,{image_data}"

response = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": image_url}
                },
                {
                    "type": "text",
                    "text": "What error is shown in this screenshot?"
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)

Video input: understand recordings and screen captures

Video input lets Qwen3.5-Omni reason across visual frames and audio tracks in one request.

from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

response = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://example.com/product-demo.mp4"
                    }
                },
                {
                    "type": "text",
                    "text": "Describe what the developer is building in this demo and write equivalent code."
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)

Audio-Visual Vibe Coding

A common workflow is to pass a screen recording and ask the model to generate code from what it sees.

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

with open("screen_recording.mp4", "rb") as f:
    video_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="qwen3.5-omni-plus",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "video_url",
                    "video_url": {
                        "url": f"data:video/mp4;base64,{video_data}"
                    }
                },
                {
                    "type": "text",
                    "text": "Watch this screen recording and write the complete code that replicates what you see being built. Include all the UI components and their interactions."
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)

The 256K token context window fits roughly 400 seconds of 720p video with audio. For longer recordings, trim or split the video before sending it.

Voice cloning

Voice cloning lets you provide a target voice sample and have the model respond in that voice. This is available through the API on Plus and Flash.

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

with open("voice_sample.wav", "rb") as f:
    voice_sample = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="qwen3.5-omni-plus",
    modalities=["text", "audio"],
    audio={
        "voice": "custom",
        "format": "wav",
        "voice_sample": {
            "data": voice_sample,
            "format": "wav"
        }
    },
    messages=[
        {
            "role": "user",
            "content": "Welcome to the Apidog developer portal. How can I help you today?"
        }
    ],
)

audio_data = response.choices[0].message.audio.data

with open("cloned_response.wav", "wb") as f:
    f.write(base64.b64decode(audio_data))

For better voice cloning quality:

Use a clean recording with minimal background noise.
Prefer 15-30 seconds of speech.
Use WAV at 16kHz or higher.
Use natural speech instead of read-aloud text when possible.

Streaming responses

For real-time voice chat or interactive apps, use streaming. The model can start returning audio before the full response is complete.

from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

stream = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    modalities=["text", "audio"],
    audio={"voice": "Ethan", "format": "pcm16"},
    messages=[
        {
            "role": "user",
            "content": "Explain how WebSocket connections differ from HTTP polling."
        }
    ],
    stream=True,
)

audio_chunks = []
text_chunks = []

for chunk in stream:
    delta = chunk.choices[0].delta

    if hasattr(delta, "audio") and delta.audio:
        if delta.audio.get("data"):
            audio_chunks.append(delta.audio["data"])

    if delta.content:
        text_chunks.append(delta.content)
        print(delta.content, end="", flush=True)

print()

if audio_chunks:
    full_audio = b"".join(base64.b64decode(chunk) for chunk in audio_chunks)

    with open("streamed_response.pcm", "wb") as f:
        f.write(full_audio)

pcm16 is useful for streaming because you can pipe chunks directly into an audio output buffer without waiting for a complete file.

Multi-turn conversation with mixed modalities

You can keep conversation state across turns and mix modalities as needed.

from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

conversation = []

def send_message(content_parts):
    conversation.append({"role": "user", "content": content_parts})

    response = client.chat.completions.create(
        model="qwen3.5-omni-flash",
        messages=conversation,
    )

    reply = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": reply})

    return reply

# Turn 1: text
print(send_message([
    {
        "type": "text",
        "text": "I have an API that keeps returning 503 errors."
    }
]))

# Turn 2: image + text
with open("error_log.png", "rb") as f:
    img = base64.b64encode(f.read()).decode()

print(send_message([
    {
        "type": "image_url",
        "image_url": {
            "url": f"data:image/png;base64,{img}"
        }
    },
    {
        "type": "text",
        "text": "Here's the error log screenshot. What's causing this?"
    }
]))

# Turn 3: follow-up text
print(send_message([
    {
        "type": "text",
        "text": "How do I fix the connection pool exhaustion you mentioned?"
    }
]))

The 256K context window supports long conversations, including conversations with images and audio in the history.

Local deployment with HuggingFace

To run Qwen3.5-Omni on your own infrastructure, install the required packages.

pip install transformers==4.57.3
pip install accelerate
pip install qwen-omni-utils -U
pip install -U flash-attn --no-build-isolation

Then load the model and processor.

import soundfile as sf
from transformers import Qwen3OmniMoeForConditionalGeneration, Qwen3OmniMoeProcessor
from qwen_omni_utils import process_mm_info

model_path = "Qwen/Qwen3-Omni-30B-A3B-Instruct"

model = Qwen3OmniMoeForConditionalGeneration.from_pretrained(
    model_path,
    device_map="auto",
    attn_implementation="flash_attention_2",
)

processor = Qwen3OmniMoeProcessor.from_pretrained(model_path)

conversation = [
    {
        "role": "system",
        "content": [
            {
                "type": "text",
                "text": "You are Qwen, a virtual human developed by the Qwen Team, Alibaba Group, capable of perceiving auditory and visual inputs, as well as generating text and speech."
            }
        ],
    },
    {
        "role": "user",
        "content": [
            {
                "type": "audio",
                "audio": "path/to/your/audio.wav"
            },
            {
                "type": "text",
                "text": "What is being discussed in this audio?"
            }
        ],
    },
]

text = processor.apply_chat_template(
    conversation,
    add_generation_prompt=True,
    tokenize=False,
)

audios, images, videos = process_mm_info(
    conversation,
    use_audio_in_video=True
)

inputs = processor(
    text=text,
    audio=audios,
    images=images,
    videos=videos,
    return_tensors="pt",
    padding=True,
)

inputs = inputs.to(model.device).to(model.dtype)

text_ids, audio_output = model.generate(
    **inputs,
    speaker="Chelsie"
)

text_response = processor.batch_decode(
    text_ids,
    skip_special_tokens=True
)[0]

sf.write(
    "local_response.wav",
    audio_output.reshape(-1).cpu().numpy(),
    samplerate=24000
)

print(text_response)

Approximate GPU memory requirements:

Variant	Precision	Min VRAM
Plus / 30B MoE	BF16	~40GB
Flash	BF16	~20GB
Light	BF16	~10GB

For production local inference, use vLLM instead of HuggingFace Transformers. MoE models run faster with vLLM routing optimizations.

Testing Qwen3.5-Omni requests with Apidog

Multimodal API requests are harder to debug than plain JSON. You may need to inspect base64-encoded media, nested content arrays, and responses that include both text and audio.

A practical workflow in Apidog:

Create a new collection for DashScope.
Set the base URL to:

   https://dashscope.aliyuncs.com/compatible-mode/v1

Store your DashScope API key as an environment variable.
Create request templates for each modality:
- Text
- Audio input
- Audio output
- Image input
- Video input
Duplicate the base request for Plus, Flash, and Light.
Change only the model parameter to compare output quality and latency.

You can also add test assertions for response validation:

Verify choices[0].message.content is not empty for text responses.
Verify choices[0].message.audio.data exists when audio output is requested.
Assert that Flash latency stays under your target threshold.

This helps you choose the right model variant before building the full application.

Error handling and retry logic

Large multimodal requests can hit rate limits, connection errors, or timeouts. Add retries from the start.

import time
import random
from openai import OpenAI, RateLimitError, APITimeoutError, APIConnectionError

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
    timeout=120,
)

def call_with_retry(messages, model="qwen3.5-omni-flash", max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
            )

        except RateLimitError:
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limit hit. Waiting {wait:.1f}s...")
            time.sleep(wait)

        except (APITimeoutError, APIConnectionError) as e:
            if attempt == max_retries - 1:
                raise

            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Connection error: {e}. Retrying in {wait:.1f}s...")
            time.sleep(wait)

    raise RuntimeError(f"Failed after {max_retries} attempts")

For video inputs larger than 100MB:

Trim to the relevant section.
Reduce resolution to 480p when high visual detail is not required.
Split long recordings into segments and aggregate the results in your app.

Common issues and fixes

Audio output is garbled on numbers or technical terms

This is the problem ARIA technology addresses. Make sure you are using Qwen3.5-Omni, not an earlier version. If you self-host, use the latest model weights from HuggingFace.

The model keeps talking when I send an audio interruption

Semantic interruption requires Flash or Plus. Light may not support this feature. Also make sure you are streaming the response instead of using a batch request.

Voice cloning quality is poor

Use a cleaner voice sample. Remove background noise with a tool such as Audacity before uploading. Use at least 15 seconds of audio. WAV at 16kHz or 44.1kHz works best.

Video input returns a token limit error

The 256K token context covers roughly 400 seconds of 720p video. For longer videos, trim the clip or lower the resolution. Keep videos under about 6 minutes for a safer margin.

Local deployment is very slow

Use vLLM instead of HuggingFace Transformers for production local inference. MoE models need vLLM routing optimizations for better throughput.

For developers whose primary need is high-fidelity speech synthesis rather than full multimodal inference, Fish Audio S2's dedicated TTS and voice-cloning API offers a narrower, faster endpoint worth evaluating alongside all-in-one multimodal models.

FAQ

Which DashScope model ID should I use for Qwen3.5-Omni?

Use one of these:

qwen3.5-omni-plus
qwen3.5-omni-flash
qwen3.5-omni-light

Start with qwen3.5-omni-flash for most use cases.

Can I use the OpenAI Python SDK with DashScope?

Yes. Configure the client like this:

from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

The request and response format follows the OpenAI-compatible API style.

How do I send multiple files, such as audio and image, in one request?

Put each file in the content array as a separate typed object.

content = [
    {
        "type": "input_audio",
        "input_audio": {
            "data": audio_data,
            "format": "wav"
        }
    },
    {
        "type": "image_url",
        "image_url": {
            "url": image_url
        }
    },
    {
        "type": "text",
        "text": "Use the audio and image to explain what is happening."
    }
]

All four modalities can appear in the same message.

Is there a size limit for audio or video files?

DashScope has per-request payload limits. For large files, use a URL reference instead of base64 encoding. Host the file on accessible storage and pass the URL in the audio or video_url field.

How do I disable audio output and get text only?

Omit modalities, or set it to text only:

modalities=["text"]

Text-only responses are faster and cheaper.

Does Qwen3.5-Omni support function calling?

Yes. Use the standard tools parameter with function definitions, the same way you would with other OpenAI-compatible models. The model returns structured tool call objects that your application executes.

What is the best way to handle long audio recordings?

For recordings under 10 hours, send them as a single request. For longer recordings, split at natural pause points, process each segment, and aggregate the results in your application layer.

How do I test multimodal requests before building a full application?

Use Apidog to build saved request templates for each modality, switch between model variants, inspect the full response structure, and write assertions before integrating the API into your application.

Qwen3.5-Omni Is Here: Alibaba's Omnimodal AI Beats Gemini on Audio

Preecha — Tue, 23 Jun 2026 13:03:20 +0000

TL;DR

Alibaba released Qwen3.5-Omni on March 30, 2026. It processes text, images, audio, and video in a single model and outputs both text and real-time speech. It outperforms Gemini 3.1 Pro on general audio understanding and reasoning benchmarks, supports 113 languages for speech recognition, and includes voice cloning. Three variants are available: Plus, Flash, and Light.

Try Apidog today

Why Qwen3.5-Omni matters for developers

Most multimodal AI apps are still built as pipelines:

Speech-to-text for audio input
Vision model for images or video frames
LLM for reasoning and response generation
Text-to-speech for voice output

That architecture works, but every handoff adds latency, cost, and failure points.

Qwen3.5-Omni collapses that stack into one model. It accepts text, images, audio, and video as input, then returns text or speech as output from a single inference call.

The model supports a 256,000-token context window, which can fit:

More than 10 hours of audio
Roughly 400 seconds of 720p video with audio
Around 190,000 words of text

Alibaba trained it on more than 100 million hours of native audio-visual data. The practical result: you can build applications where the model reasons across speech, visuals, and text together instead of stitching together separate model outputs.

Use cases include:

Voice assistants
Video analysis tools
Multilingual support agents
Accessibility tools
Developer productivity workflows using screen recordings

What changed from Qwen3-Omni

The previous generation, Qwen3-Omni Flash, launched in December 2025 with 234ms response latency. Qwen3.5-Omni is the next full release.

1. Speech recognition now covers 113 languages

Qwen3-Omni supported speech recognition in 19 languages. Qwen3.5-Omni expands that to 113 languages and dialects.

Speech generation also increased from 10 languages to 36.

For developers, this matters if your app needs to support users outside major Western markets. Instead of routing different languages through separate ASR vendors, you can test one model across a much broader language set.

Example workflows:

Transcribe customer support calls in multiple languages
Summarize non-English podcasts or interviews
Handle bilingual conversations with mid-sentence language switching

2. Voice cloning is available through the API

Qwen3.5-Omni Plus and Flash support voice cloning through the API.

The workflow is:

Upload or reference a voice sample
Send the user prompt and voice configuration
Receive speech output in the cloned voice

This is useful for:

Consistent voice personas
Branded voice agents
Long-running conversational assistants

Voice cloning was not available in the previous generation.

3. ARIA improves pronunciation for numbers and technical terms

Neural TTS systems often struggle with:

Product names
Technical terms
Proper nouns
Prices
Version numbers
Acronyms

Qwen3.5-Omni introduces ARIA, a dynamic text-speech synchronization layer. It reads ahead in the text buffer and adjusts phoneme generation before audio is emitted.

That helps terms like these render correctly:

IPv6
$249.99
Qwen3.5-Omni

This is especially relevant for developer tools, sales assistants, support bots, and technical documentation readers.

4. Semantic interruption improves voice UX

In many voice systems, any incoming audio is treated as an interruption.

That creates bad UX:

User says “uh-huh” → assistant stops
User says “right” → assistant stops
User says “wait, stop” → assistant should stop

Qwen3.5-Omni distinguishes between backchannels and real interruptions.

This makes it more useful for real-time voice assistants where users naturally acknowledge, pause, or interrupt during conversation.

5. Real-time web search is integrated

Qwen3.5-Omni can query the web during inference and include live results in its response.

That means you do not always need to pre-fetch external context and inject it into the prompt yourself.

Use this when your app needs current information, such as:

Recent documentation
Current pricing
News or market updates
Live product information

6. Screen recordings can become coding input

Qwen3.5-Omni supports “Audio-Visual Vibe Coding.”

The workflow:

Record a screen interaction
Send the video to the model
Ask the model to replicate, explain, or improve what it sees
Use the generated code as a starting point

This gives coding assistants a new input format: video.

Instead of describing UI behavior in text, you can provide a screen recording and ask for implementation guidance.

Benchmark results

Across 36 audio and audio-visual benchmarks:

Qwen3.5-Omni achieves state-of-the-art on 32 out of 36
It sets new state-of-the-art on 22 of those 36
It outperforms Gemini 3.1 Pro on general audio understanding, reasoning, and translation
It matches Gemini 3.1 Pro on audio-visual comprehension

For speech generation quality, Alibaba reports that Qwen3.5-Omni beats ElevenLabs, GPT-Audio, and Minimax on multilingual voice stability across 20 languages.

That comparison is notable because ElevenLabs is a dedicated voice AI company. Still, you should benchmark against your own prompts, languages, accents, and audio conditions before choosing a production model.

Model variants

Alibaba ships three versions.

Variant	Best for
Qwen3.5-Omni Plus	Maximum quality; audio-visual reasoning, voice cloning, long-context tasks
Qwen3.5-Omni Flash	Balanced speed and quality; real-time voice chat, production APIs
Qwen3.5-Omni Light	Low-latency tasks; mobile and edge scenarios

All three handle text, images, audio, and video as input.

The differences are mainly:

Output quality
Latency
Cost
Deployment fit

For most production APIs, start by testing Flash. Use Plus when quality matters more than latency or cost. Use Light for latency-sensitive scenarios.

Working with the 256K token context window

Qwen3.5-Omni supports up to 256,000 input tokens.

In practice, that means you can send:

A long meeting recording
A full support call
A product demo video
A large document
Mixed text, audio, image, and video context

Approximate capacity:

Input type	Approximate capacity
Audio	More than 10 hours of continuous speech
Video	Roughly 400 seconds of 720p video with embedded audio
Text	Around 190,000 words

For many multimodal use cases, this removes the need to chunk inputs manually.

Example prompt for a meeting recording:

Summarize this meeting recording.

Return:
1. Main decisions
2. Open questions
3. Action items with owners
4. Risks mentioned
5. Follow-up email draft

Example prompt for a product demo video:

Analyze this product demo video.

Return:
1. What feature is being demonstrated
2. Step-by-step user flow
3. Any visible bugs or UX friction
4. Suggested improvements
5. A short release note

Qwen3.5-Omni’s 256K context is smaller than Gemini 2.5 Pro’s 1M context and larger than many standard multimodal workflows require. Compared with GPT-4o’s 128K context, it gives more room for long audio-visual inputs.

Building multilingual voice workflows

The increase from 19 to 113 speech recognition languages changes how you can design multilingual systems.

Customer support

You can route voice input from many regions into the same model rather than maintaining separate ASR pipelines per language.

Example support-agent prompt:

You are a customer support assistant.

Input:
- Customer audio
- Product documentation
- Recent order information

Tasks:
1. Detect the spoken language
2. Transcribe the user request
3. Identify the issue
4. Reply in the same language
5. Escalate if the issue involves billing, legal, or account security

Content processing

For podcasts, interviews, and videos, one request can cover transcription, translation, and summarization.

Example:

Process this interview.

Return:
1. Original-language transcript
2. English translation
3. 5-bullet summary
4. Notable quotes
5. Speaker-by-speaker topic breakdown

Mid-conversation language switching

Bilingual users often switch languages mid-sentence.

Qwen3.5-Omni handles this natively, which is useful for:

Support conversations
Education apps
Travel assistants
Internal company tools for global teams

Architecture: Thinker-Talker with MoE

Qwen3.5-Omni uses a Thinker-Talker architecture.

The Thinker processes multimodal input and generates reasoning tokens.

The Talker converts those tokens into natural speech in real time using a multi-codebook approach designed to reduce latency.

The Plus variant uses Mixture of Experts, or MoE. With MoE, only a subset of model parameters activates per token. This keeps inference more efficient than a dense model of equivalent quality.

For local deployment:

Use vLLM when possible for MoE-optimized serving
Use HuggingFace Transformers if you need broader compatibility
Expect higher latency with Transformers on MoE architectures

Basic local deployment decision flow:

Need production local serving?
→ Start with vLLM

Need experimentation or custom model loading?
→ Try HuggingFace Transformers

Limited GPU memory?
→ Test Flash or Light before Plus

Testing Qwen3.5-Omni APIs with Apidog

If you evaluate Qwen3.5-Omni through an API, you will likely send multimodal request bodies containing:

Text prompts
Image URLs
Base64-encoded audio
Video references
Model variant settings
Streaming options
Voice cloning parameters

This gets hard to debug with raw curl commands.

Apidog is useful for building, saving, and testing these request templates. You can:

Store DashScope API keys as environment variables
Create reusable request bodies for Plus, Flash, and Light
Compare latency across variants
Validate response structure
Write automated tests for expected fields

Example API test checklist:

[ ] Request returns HTTP 200
[ ] Response includes text output
[ ] Response includes audio output when requested
[ ] Latency is within target range
[ ] Language detection matches input
[ ] Streaming response starts before full generation completes
[ ] Error responses are handled correctly

A typical multimodal request template might include:

{
  "model": "qwen3.5-omni-flash",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Summarize this video and extract action items."
          },
          {
            "type": "video_url",
            "video_url": "https://example.com/demo.mp4"
          }
        ]
      }
    ]
  },
  "parameters": {
    "output_modalities": ["text", "audio"],
    "language": "auto"
  }
}

Use the same saved request against Plus, Flash, and Light to compare output quality and latency under identical inputs.

Download Apidog free to start testing multimodal API requests.

Who should evaluate Qwen3.5-Omni?

Qwen3.5-Omni is worth testing if you are building any of the following.

Voice assistants

Use it for real-time speech input and speech output with conversation memory and web retrieval.

The semantic interruption and ARIA features address two common voice UX problems:

False interruptions
Mispronounced technical terms

Video analysis tools

Use it for:

Meeting transcription
Product demo analysis
Tutorial generation
Video summarization
Screen-recording-to-code workflows

The 256K context window means many recordings can fit in one request.

Multilingual customer products

Use it when your app needs:

113-language ASR
36-language TTS
Language switching
One multimodal model instead of multiple vendors

Accessibility tooling

Potential workflows include:

Alt text generation
Audio descriptions for video
Real-time captions
Multilingual caption generation

Developer productivity tools

Audio-Visual Vibe Coding lets developers provide screen recordings as context.

Example prompt:

Watch this screen recording of a UI interaction.

Generate:
1. React component structure
2. Required state management
3. CSS layout
4. Edge cases
5. A minimal working implementation

Access options

Qwen3.5-Omni is available through:

Alibaba Cloud DashScope API for production API access
qwen.ai for web-based testing
HuggingFace Hub for model weights and local deployment
ModelScope, recommended for users in mainland China

The API follows Alibaba Cloud’s standard authentication model. You need a DashScope API key.

Check the DashScope documentation for:

Endpoint details
Authentication
Streaming support
Pricing by modality
Rate limits
Model availability

What to test before production

Benchmarks are useful, but your own workload matters more.

Before adopting Qwen3.5-Omni, test:

Your users’ accents
Your supported languages
Domain-specific vocabulary
Audio quality from real devices
Long recordings
Noisy environments
Video formats and resolutions
Latency under load
Voice cloning quality
Streaming behavior

Also note:

Voice cloning is API-only for now
The qwen.ai web interface does not expose voice cloning yet
Local deployment requires significant GPU memory
The Plus variant, a 30B MoE model, needs at least 40GB VRAM for comfortable inference
Flash and Light are more accessible for smaller deployments

FAQ

How is Qwen3.5-Omni different from Qwen2.5-Omni?

Qwen2.5-Omni supported 7B and 3B dense model sizes with 19 languages for speech. Qwen3.5-Omni uses an MoE architecture, expands speech recognition to 113 languages, adds voice cloning, and introduces ARIA for better audio quality. Benchmark performance and context length also increased.

Can I run Qwen3.5-Omni locally?

Yes. You can run it with HuggingFace Transformers or vLLM.

For production local deployment, vLLM is the better option because it handles MoE routing more efficiently.

The Plus variant needs 40GB+ VRAM. Flash and Light run on smaller GPUs.

Is there a free tier?

The qwen.ai web interface is free to use. API access through DashScope is paid.

Pricing depends on modality, such as audio tokens, video frames, and text tokens. Check the DashScope pricing documentation for current details.

Does it support real-time streaming?

Yes. The Thinker-Talker architecture outputs audio in streaming chunks, so the first audio bytes can arrive before the full response is generated.

This is important for live voice conversations.

What is the difference between Plus, Flash, and Light?

Plus is the highest-quality variant and is best when accuracy matters more than speed.

Flash balances speed and quality and is the best starting point for most production APIs.

Light is the fastest option and is intended for latency-sensitive applications such as mobile or edge scenarios.

Can I use my own voice with the API?

Yes. Voice cloning is available through the API.

You provide an audio sample of the target voice, and the model uses it for speech output.

This feature is not available through the web interface yet.

How does it compare to ElevenLabs for voice generation?

On Alibaba’s benchmarks across 20 languages, Qwen3.5-Omni Plus outperforms ElevenLabs on multilingual voice stability.

ElevenLabs still has a longer product track record and more voice-specific customization options. If you only need voice generation, compare both. If you need one integrated multimodal model, Qwen3.5-Omni is the cleaner architecture to test.

Is it safe to send sensitive audio or video data through the API?

Review Alibaba Cloud’s data processing agreement before sending sensitive data.

As with any cloud API, assume data may be logged unless the agreement explicitly states otherwise.

Pretext.js: The 15KB Library That Makes Text Layout 500x Faster

Preecha — Tue, 23 Jun 2026 01:01:35 +0000

TL;DR

Pretext.js is a zero-dependency TypeScript library that measures and positions multiline text with arithmetic instead of DOM layout reads. It avoids forced synchronous reflows, reports benchmarks up to ~500x faster than getBoundingClientRect() for text measurement, and supports major writing systems. If you build virtual scrollers, chat UIs, or data grids, it targets one of the most expensive browser UI bottlenecks: measuring dynamic text.

Try Apidog today

Introduction

Every time JavaScript calls getBoundingClientRect() or reads layout properties like offsetHeight, the browser may stop to flush pending styles, recalculate layout, and return the computed value. That forced synchronous reflow is expensive.

Now apply that to:

1,000 chat bubbles in a virtualized list
10,000 rows in a data grid
Streaming API responses that constantly append text
Multilingual feeds with unpredictable line wrapping

The result is usually dropped frames, visible scroll jumps, and layout jank.

Apidog teams building API-driven frontends know this pain well: streaming response data into dynamic UIs is hard when every layout measurement fights the rendering pipeline.

Cheng Lou, the developer behind react-motion and a core contributor to React and ReasonML at Meta, built Pretext.js to address this. The library shipped in March 2026, gained 14,000+ GitHub stars in days, and triggered a large Hacker News discussion.

This guide focuses on how Pretext.js works, where it fits, how to integrate it, and when not to use it.

What is Pretext.js?

Pretext.js is a pure JavaScript/TypeScript text layout engine. It measures and positions multiline text through arithmetic instead of DOM reads.

That means:

No getBoundingClientRect()
No offsetHeight
No forced reflow during layout calculation
No off-screen DOM measurement loop

The core idea: instead of asking the browser, “How tall is this rendered text?”, Pretext.js computes the answer from font metrics and line-breaking rules.

Basic usage:

import { prepare, layout } from '@chenglou/pretext';

// Step 1: prepare text once
const handle = prepare('Hello, pretext.js', '16px "Inter"');

// Step 2: compute layout at a target width
const { height, lineCount } = layout(handle, 400, 24);

console.log({ height, lineCount });

The API has two main functions:

prepare(text, font) measures and caches text segments.
layout(handle, width, lineHeight) computes wrapping and height.

prepare() touches the browser through Canvas text measurement. After that, layout() is arithmetic.

Why this matters for API-heavy applications

If your app consumes streaming or frequently changing API data, you often need to know text height before rendering.

Common examples:

AI chat interfaces streaming tokens
Real-time dashboards showing logs or events
Collaborative editors
Chat and comment feeds
Data grids with variable-height cells

Without precomputed heights, virtual scrollers usually fall back to one of these options:

Render first, measure later.
Estimate height, then correct after render.
Force fixed-height rows.

All three have tradeoffs. Pretext.js gives you a way to compute text height before creating DOM nodes.

The problem Pretext.js solves

Forced synchronous reflow

This pattern is common and expensive:

const elements = document.querySelectorAll('.text-block');

elements.forEach((el) => {
  const height = el.getBoundingClientRect().height;
  // use height for positioning...
});

Each layout read can force the browser to:

Pause JavaScript
Flush pending style changes
Recalculate layout
Return the computed geometry

In loops, this becomes layout thrashing.

For virtualized UI, that cost is especially painful because the whole point is to avoid rendering and measuring thousands of DOM nodes.

The virtual scrolling problem

Virtual scrollers such as react-window or @tanstack/react-virtual need item heights to compute scroll offsets.

Fixed-height rows are easy:

const rowHeight = 48;
const offset = index * rowHeight;

Variable-height text is harder:

const offset = heights.slice(0, index).reduce((a, b) => a + b, 0);

The challenge is getting heights without rendering every row.

Traditional options include:

Hidden off-screen render containers
Post-render measurement
Estimated heights
Fixed-height constraints

Pretext.js replaces those workarounds with a pre-render calculation.

Benchmark numbers

Pretext.js published benchmark results comparing DOM measurement with layout().

Approach	1,000 text blocks	500 text blocks
DOM with `getBoundingClientRect()`	~94ms	~47ms
Pretext.js `layout()`	~2ms	~0.09ms
Speed difference	~47x faster	~500x faster

The improvement comes from avoiding layout reads. DOM measurement has browser rendering overhead; Pretext’s layout() step is arithmetic over prepared segment widths.

How Pretext.js works

Pretext.js has three main phases.

1. Text segmentation

When you call prepare(), Pretext.js normalizes and segments the input text.

It accounts for:

Whitespace handling
Unicode line breaking rules, including UAX #14
Breakable units
Multilingual text behavior

This matters because line wrapping is not the same across writing systems.

Examples:

CJK text can break at character-level boundaries.
Arabic and Hebrew require bidirectional text handling.
Thai does not use spaces between words in the same way English does.
Hindi/Devanagari can include conjunct consonants and ligatures.
Emoji can span multiple code points.
Soft hyphens introduce conditional break opportunities.

2. Canvas measurement

After segmentation, Pretext.js measures segments with Canvas measureText().

Example of the underlying browser primitive:

const canvas = new OffscreenCanvas(1, 1);
const ctx = canvas.getContext('2d');

if (!ctx) {
  throw new Error('Canvas context unavailable');
}

ctx.font = '16px "Inter"';

const metrics = ctx.measureText('Hello');
const width = metrics.width;

Canvas text measurement does not trigger DOM layout reflow. Pretext.js caches measurements by segment and font combination, so repeated text/font pairs can reuse previous work.

3. Arithmetic layout

layout() takes the prepared handle, a target width, and a line height.

Conceptually, it does this:

let currentLineWidth = 0;
let lineCount = 1;

for (const segment of segments) {
  if (currentLineWidth + segment.width > containerWidth) {
    lineCount++;
    currentLineWidth = segment.width;
  } else {
    currentLineWidth += segment.width;
  }
}

const height = lineCount * lineHeight;

The actual implementation handles Unicode and text layout details, but the performance win comes from the same principle: no DOM, no reflow, no render pass.

Reuse prepared handles

One useful pattern is preparing text once and laying it out at multiple widths.

import { prepare, layout } from '@chenglou/pretext';

const handle = prepare(longArticleText, '16px "Inter"');

const mobile = layout(handle, 375, 24);
const tablet = layout(handle, 768, 24);
const desktop = layout(handle, 1200, 24);

console.log({
  mobileHeight: mobile.height,
  tabletHeight: tablet.height,
  desktopHeight: desktop.height,
});

This is useful for responsive layouts where the same content needs to be measured against different container widths.

Practical implementation patterns

1. Variable-height virtual scrolling

Use Pretext.js to precompute row heights before passing them into a virtualizer.

import { prepare, layout } from '@chenglou/pretext';

interface TextItem {
  id: string;
  content: string;
}

function computeHeights(items: TextItem[], containerWidth: number) {
  const font = '14px "Inter"';
  const lineHeight = 20;
  const verticalPadding = 32;

  return items.map((item) => {
    const handle = prepare(item.content, font);
    const { height } = layout(handle, containerWidth, lineHeight);

    return {
      id: item.id,
      height: height + verticalPadding,
    };
  });
}

const heights = computeHeights(chatMessages, 600);

This avoids:

Rendering hidden rows
Measuring DOM nodes
Correcting estimated heights after paint

2. AI chat interfaces

Streaming chat UIs update text many times while a response is being generated. If every update causes DOM measurement, the UI can stutter.

With Pretext.js, update the item height from text data:

import { prepare, layout } from '@chenglou/pretext';

let streamedText = '';

const font = '15px "SF Pro"';
const lineHeight = 22;
const bubbleWidth = 520;
const padding = 24;

socket.on('token', (token: string) => {
  streamedText += token;

  const handle = prepare(streamedText, font);
  const { height } = layout(handle, bubbleWidth, lineHeight);

  scroller.updateItemHeight(messageId, height + padding);
});

For better performance, batch token updates instead of recalculating on every single character:

let pending = '';
let scheduled = false;

socket.on('token', (token: string) => {
  pending += token;

  if (!scheduled) {
    scheduled = true;

    requestAnimationFrame(() => {
      streamedText += pending;
      pending = '';
      scheduled = false;

      const handle = prepare(streamedText, font);
      const { height } = layout(handle, bubbleWidth, lineHeight);

      scroller.updateItemHeight(messageId, height + padding);
    });
  }
});

3. Data grids with text-heavy cells

Data grids often need row heights before rendering visible rows.

import { prepare, layout } from '@chenglou/pretext';

interface GridRow {
  id: string;
  description: string;
}

function computeRowHeight(row: GridRow, columnWidth: number) {
  const font = '13px system-ui';
  const lineHeight = 18;
  const verticalPadding = 16;

  const handle = prepare(row.description, font);
  const { height } = layout(handle, columnWidth, lineHeight);

  return height + verticalPadding;
}

Use this when rows contain long descriptions, logs, comments, or other variable-length text.

4. Multilingual feeds

Mixed-script feeds are difficult to virtualize because line-breaking behavior varies across languages.

import { prepare, layout } from '@chenglou/pretext';

const posts = [
  { text: 'This library changed everything', lang: 'en' },
  { text: 'RTL text with correct bidirectional layout', lang: 'ar' },
  { text: 'CJK text gets proper character-level breaks', lang: 'zh' },
];

const font = '16px system-ui';
const width = 400;
const lineHeight = 24;

for (const post of posts) {
  const handle = prepare(post.text, font);
  const { height, lineCount } = layout(handle, width, lineHeight);

  console.log(post.lang, { height, lineCount });
}

The same API handles different writing systems.

Testing text-heavy API flows with Apidog

When a UI depends on API-provided text, layout correctness also depends on response quality.

Use Apidog to test the API payloads that feed your text components. For example, you can create scenarios for:

Short, medium, and long text responses
Streaming chunks that simulate LLM output
Multilingual payloads
Emoji and Unicode edge cases
Empty or missing text fields
Unexpectedly large responses

For AI chat products, this helps validate:

Chunked streaming behavior
Response schema correctness
Text field formats
Edge cases that affect rendering
Automated regression coverage for text layout bugs

Fast measurement helps, but bad API data can still produce broken UI. Test both the rendering layer and the API responses that drive it.

Known limitations

Pretext.js is not a replacement for the browser layout engine in every case.

Rendering accuracy edge cases

Because Pretext.js computes layout separately from DOM rendering, it can diverge from the browser in some cases.

Potential causes include:

Unusual kerning pairs
Mixed font sizes inside one block
Subpixel rendering differences
Browser-specific text shaping behavior
Differences between Canvas measurement and DOM text rendering

For virtual scrolling, small differences may be acceptable. For pixel-perfect typography, DOM measurement remains the ground truth.

`prepare()` still has a cost

layout() is fast, but prepare() still uses Canvas measurement.

Avoid calling prepare() repeatedly for unchanged text. Cache handles by text and font:

import { prepare, layout } from '@chenglou/pretext';

const cache = new Map<string, ReturnType<typeof prepare>>();

function getPreparedText(text: string, font: string) {
  const key = `${font}::${text}`;

  let handle = cache.get(key);

  if (!handle) {
    handle = prepare(text, font);
    cache.set(key, handle);
  }

  return handle;
}

function measureTextHeight(text: string, font: string, width: number, lineHeight: number) {
  const handle = getPreparedText(text, font);
  return layout(handle, width, lineHeight).height;
}

Limited CSS property support

Pretext.js measures raw text with a font specification. It does not fully account for CSS properties such as:

letter-spacing
word-spacing
text-indent
text-transform
font-feature-settings
font-variant

If your rendered text depends heavily on these properties, measured height may not match the DOM.

It does not render text

Pretext.js computes text layout metrics. It does not display text.

You still render with:

DOM
Canvas
SVG
WebGL
Another rendering target

Its value is in the measurement step before rendering.

Pretext.js vs. traditional approaches

Feature	Pretext.js	DOM measurement	Estimated heights
Speed for 1K items	~2ms	~94ms	~0ms
Accuracy	High, Canvas-based	Ground truth	Heuristic
DOM dependency	None after `prepare()`	Full	None
Reflow triggers	Zero during `layout()`	One per measurement	Zero
Multilingual support	Unicode-aware	Browser-native	Usually poor
CSS property support	Limited	Full	None
Memory overhead	Cached segments	DOM nodes	Minimal
Responsive layout	One `prepare()`, many `layout()` calls	Re-measure per width	Re-estimate per width

Use DOM measurement when you need maximum fidelity. Use Pretext.js when you need fast pre-render measurement for many text blocks and can tolerate minor differences.

Getting started

Installation

npm install @chenglou/pretext
# or
pnpm add @chenglou/pretext
# or
bun add @chenglou/pretext

Basic usage

import { prepare, layout } from '@chenglou/pretext';

const handle = prepare(
  'Pretext.js computes text layout without touching the DOM.',
  '16px "Inter"'
);

const result = layout(handle, 600, 24);

console.log(result.height);
console.log(result.lineCount);

React integration with TanStack Virtual

import { prepare, layout } from '@chenglou/pretext';
import { useVirtualizer } from '@tanstack/react-virtual';
import { useMemo, useRef } from 'react';

function VirtualChat({ messages }: { messages: string[] }) {
  const parentRef = useRef<HTMLDivElement>(null);

  const containerWidth = 600;
  const font = '14px "Inter"';
  const lineHeight = 20;
  const verticalPadding = 24;

  const heights = useMemo(() => {
    return messages.map((message) => {
      const handle = prepare(message, font);
      const { height } = layout(handle, containerWidth, lineHeight);

      return height + verticalPadding;
    });
  }, [messages]);

  const virtualizer = useVirtualizer({
    count: messages.length,
    getScrollElement: () => parentRef.current,
    estimateSize: (index) => heights[index],
  });

  return (
    <div ref={parentRef} style={{ height: '100vh', overflow: 'auto' }}>
      <div
        style={{
          height: virtualizer.getTotalSize(),
          position: 'relative',
        }}
      >
        {virtualizer.getVirtualItems().map((virtualRow) => (
          <div
            key={virtualRow.key}
            style={{
              position: 'absolute',
              top: virtualRow.start,
              width: containerWidth,
            }}
          >
            {messages[virtualRow.index]}
          </div>
        ))}
      </div>
    </div>
  );
}

This computes item heights before messages are rendered by the virtual list.

Wait for web fonts before measuring

If your app uses web fonts, make sure they are loaded before calling prepare().

async function measureAfterFontsLoad(text: string) {
  await document.fonts.ready;

  const handle = prepare(text, '16px "Inter"');
  return layout(handle, 600, 24);
}

If the font is not loaded, Canvas may measure with a fallback font and produce incorrect results.

Interactive playground

The Pretext.js website includes an interactive playground at pretextjs.dev/playground, where you can paste text, choose fonts, adjust container width, and inspect layout behavior before integrating it.

When not to use Pretext.js

Avoid Pretext.js when the browser already solves your problem cheaply.

Good reasons not to use it:

Your page is static and not virtualized.
You only have a small list of items.
You need pixel-perfect print layout.
Your text depends heavily on CSS text properties.
You need server-side measurement without Canvas polyfills.
DOM measurement cost is already negligible in your UI.

For example, measuring 50 static elements may be fast enough with the DOM. The extra dependency may not be worth it.

FAQ

Is Pretext.js production-ready?

The library shipped in March 2026 and gained 14,000+ GitHub stars within days. Its creator, Cheng Lou, runs Midjourney’s frontend, and the test suite covers many languages and edge cases.

That said, it is still a new release. Pin your dependency version and test it with your actual fonts, content, browsers, and layout constraints.

Does it work with React, Vue, and Svelte?

Yes. Pretext.js is framework-agnostic.

You can call prepare() and layout() from:

React hooks
Vue composables
Svelte stores
Plain JavaScript modules
Worker-like architecture where browser APIs are available

How does it handle web fonts?

prepare() measures with the font available at call time. If the web font has not loaded, measurement may use a fallback font.

Use the Font Loading API:

await document.fonts.ready;

Then call prepare().

Can it be used for Canvas or SVG rendering?

Yes. The computed layout data can inform rendering in DOM, Canvas, SVG, WebGL, or other targets.

Pretext.js handles measurement and layout calculation, not rendering.

Does it support RTL languages?

Yes. Pretext.js supports Arabic, Hebrew, and mixed-direction text with bidirectional handling.

What is the bundle size?

The article reports a 15KB minified bundle with zero dependencies. It uses standard browser APIs such as Canvas measureText() and Intl.Segmenter where available.

How accurate is it compared to DOM measurement?

For most text content, the article reports that Pretext.js matches DOM layout within roughly 1–2 pixels. Accuracy depends on fonts, browser behavior, and CSS properties.

If you use unsupported CSS properties like letter-spacing or word-spacing, expect larger differences.

Can it measure styled text?

Each prepare() call accepts a single font specification. For mixed styles, such as bold words inside regular text, you need to split the text into style runs and measure them separately.

Conclusion

Pretext.js gives developers a practical way to measure multiline text without forcing DOM reflow. For virtual scrollers, chat interfaces, data grids, and streaming text UIs, that can remove a major source of layout jank.

The tradeoff is fidelity. It does not fully support every CSS text property, can differ from DOM rendering in edge cases, and still requires Canvas measurement during prepare().

Use it when you need fast pre-render text heights across many dynamic items. Keep DOM measurement when you need browser-perfect layout accuracy.

How to Use ByteDance DeerFlow 2.0 in 2026: Setup, Features, Security, and API Workflow Fit

Preecha — Mon, 22 Jun 2026 13:02:30 +0000

TL;DR / Quick Answer

DeerFlow 2.0 is an open-source super-agent harness from ByteDance for long-horizon tasks, multi-agent delegation, sandboxed execution, and skills-based extensibility. It is not just a coding copilot; it is an execution runtime for complex workflows.

Try Apidog today

If your team needs end-to-end autonomous task handling, DeerFlow is a strong fit. If your team also ships APIs, pair it with Apidog as your API quality layer for contract design, test governance, mock environments, and documentation.

Why DeerFlow Is Getting Attention

Most AI development tools help with one task at a time: generating code, answering questions, summarizing research, or automating a small workflow.

DeerFlow targets a broader use case: orchestrating work across multiple steps.

According to the project description, DeerFlow combines:

sub-agents
memory
sandbox execution
tools and skills
message gateway channels

That matters because real engineering work rarely fits into one prompt. A useful agent runtime needs to decompose work, inspect files, execute commands, produce artifacts, and iterate based on results.

What DeerFlow 2.0 Actually Changed

DeerFlow 2.0 is a full rewrite. The maintainers state that it shares no code with the 1.x branch.

Practical takeaway:

Use main if you want the current DeerFlow 2.0 super-agent harness architecture.
Use main-1.x only if you intentionally need legacy behavior.

If you are evaluating DeerFlow today, treat 2.0 as the baseline.

Core Capability Breakdown

1. Skills and Tools

DeerFlow loads skills progressively instead of injecting every capability into the model context at once.

That helps with:

long sessions
token-sensitive models
workflows where the agent only needs certain capabilities at specific stages

It also supports:

built-in tools
custom tools
MCP server integration

If your team already uses MCP-based integrations, DeerFlow can fit into that tool ecosystem more easily.

2. Sub-Agents

The lead agent can delegate work to sub-agents with isolated contexts.

Use this for workflows like:

repository analysis + test planning + refactor proposal
research + implementation + documentation handoff
content generation + validation + publishing preparation
API implementation + test generation + review

The practical benefit is separation of responsibilities. Instead of forcing one agent context to handle everything, you can split the task into smaller execution stages.

3. Sandbox and Filesystem

DeerFlow is designed to run execution inside a sandboxed environment with auditable file operations and command execution.

This is a major difference between a chatbot and an agent runtime.

A chatbot can suggest commands. An execution runtime can work through a task, create files, run commands, inspect outputs, and revise its approach.

4. Context Engineering and Summarization

DeerFlow emphasizes:

context compression
isolated sub-agent context
summarization across long workflows

This helps reduce context bloat and keeps long-running tasks more stable.

5. Long-Term Memory

DeerFlow supports memory that persists across sessions and is stored locally under user control.

The project also documents improvements around duplicate-memory handling, which helps avoid repeated fact accumulation over time.

6. Channel Connectivity

DeerFlow supports task intake from messaging channels such as:

Telegram
Slack
Feishu/Lark

Channel configuration is handled in config.yaml.

This makes DeerFlow useful for team workflows where the agent is not only accessed through a terminal or local UI.

Setup Tutorial: Fastest Safe Path

The official installation docs prioritize Docker when available. That is the safest default for most teams.

Step 1: Clone the repository and initialize config

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make config

Step 2: Configure model providers

Edit config.yaml and define at least one model.

DeerFlow supports OpenAI-compatible APIs and CLI-backed providers.

Example:

models:
  - name: gpt-5-responses
    display_name: GPT-5 (Responses API)
    use: langchain_openai:ChatOpenAI
    model: gpt-5
    api_key: $OPENAI_API_KEY
    use_responses_api: true
    output_version: responses/v1

Step 3: Set environment variables

Set the values referenced by your model configuration.

Example:

export OPENAI_API_KEY=your-key
export TAVILY_API_KEY=your-key

Step 4: Start with Docker

make docker-init
make docker-start

Default access URL:

http://localhost:2026

Step 5: Use local mode only if needed

If you are not using Docker, run the local setup checks and development server:

make check
make install
make dev

Security: The Part Most Teams Skip

DeerFlow's own docs include a strong warning: high-privilege capabilities such as command execution, file operations, and business logic invocation can be risky when exposed without controls.

Do not treat DeerFlow like a normal public web app.

Safe baseline

Start with these controls:

Keep deployment local or trusted by default.
If cross-network access is required, add IP allowlists.
Put a reverse proxy with strong authentication in front.
Isolate network segments where possible.
Keep DeerFlow updated.
Review which tools and commands are available to the agent.
Do not enable messaging channels before you have access controls and runbooks.

Common mistake

The dangerous pattern is exposing DeerFlow publicly without strict authentication, network restrictions, and permission boundaries.

Avoid that. Keep the default posture local-first and trusted-network-first.

DeerFlow vs Typical Coding Agent

A better question than "Should DeerFlow replace my coding agent?" is:

Which tool should own which part of the workflow?

Workflow need	Typical coding agent	DeerFlow 2.0
IDE-centric coding loop	Strong	Good
Multi-agent task decomposition	Limited to moderate	Strong
Channel-driven operations	Usually limited	Strong
Runtime orchestration	Limited	Strong
Local trusted deployment focus	Varies	Explicitly documented

If your work is mostly PR coding loops, a coding agent may be enough.

If your work spans orchestration, channels, research, artifact pipelines, and multi-step automation, DeerFlow is more aligned.

Where Apidog Fits in a DeerFlow Stack

A common mistake is expecting one agent framework to handle the entire software delivery lifecycle.

DeerFlow can orchestrate and execute, but API lifecycle quality still needs a dedicated system.

What DeerFlow does well for API teams

Use DeerFlow for execution-heavy work:

scaffolding services and scripts
running iterative implementation loops
coordinating multi-step engineering automation
delegating subtasks to specialized agents
producing draft artifacts for review

What API teams still need beyond DeerFlow

API teams still need a reliable place for:

contract-first API design and review
endpoint-level regression test suites
reusable mock environments
API debugging workflows
publishable API documentation
governance around schema and behavior changes

That is where Apidog fits.

Practical architecture

Use a split-responsibility model:

DeerFlow automates engineering execution.
Apidog defines and governs API behavior.
DeerFlow can generate implementation and test candidates.
Apidog remains the source of truth for contracts, mocks, tests, and documentation.

This gives you speed without losing control over API correctness.

Example Adoption Blueprint: Week 1 to Week 4

Week 1: Local pilot

Start small.

Run DeerFlow locally with Docker.
Configure one model provider.
Choose one internal workflow.
Run it end to end.

Example pilot workflow:

Implement a new internal API endpoint from an existing contract,
generate a docs stub,
and produce test candidates.

Do not expose the service outside your local or trusted environment yet.

Week 2: Add task decomposition

Introduce sub-agent stages.

Example split:

Stage 1: Analyze the repository.
Stage 2: Identify implementation files.
Stage 3: Generate code changes.
Stage 4: Draft tests.
Stage 5: Summarize risks and review notes.

Track:

where the agent gets stuck
which prompts are too broad
which tools are unnecessary
which permissions need tightening

Week 3: Add API governance guardrails

Use Apidog to define and validate API behavior.

Add:

OpenAPI contracts
endpoint test collections
mock responses
documentation updates

Then make API tests the gate for DeerFlow-generated changes.

Week 4: Controlled scaling

Only expand access after the local workflow is stable.

Add messaging channels only if operations need them.
Keep strict network and authentication boundaries.
Document runbooks for approval, retry, rollback, and incident response.
Define which agent actions require human review.

Strengths and Tradeoffs

DeerFlow strengths

long-horizon orchestration model
sub-agent task decomposition
sandbox and filesystem execution model
skills-based extensibility
MCP integration support
active open-source momentum

DeerFlow tradeoffs

more operational complexity than simple coding assistants
higher security responsibility outside local environments
requires disciplined configuration
needs governance for production-grade usage
can produce risky outcomes if granted broad command or file permissions without controls

Hands-On Workflow: DeerFlow + Apidog for an API Delivery Loop

Here is a practical workflow for teams shipping REST APIs.

Scenario

You need to ship a new internal REST API endpoint with:

strict request and response contracts
automated regression tests
deploy-safe change checks
fast iteration from idea to implementation

Step A: Define the API contract in Apidog first

Start with the contract before asking the agent to implement anything.

Define:

endpoint path
HTTP method
request schema
response schema
error objects
status codes
authentication requirements

Example contract checklist:

POST /internal/users/search

Request:
- query: string
- limit: number
- cursor: string | null

Response:
- items: User[]
- nextCursor: string | null

Errors:
- 400 invalid_request
- 401 unauthorized
- 500 internal_error

This becomes the source of truth for the implementation.

Step B: Ask DeerFlow to generate implementation candidates

Use DeerFlow for the execution-heavy parts.

Good tasks for DeerFlow:

scaffold route handlers
implement service layer logic
draft migration scripts
generate unit test templates
generate integration test templates
inspect existing code patterns

Give DeerFlow specific contract constraints.

Instead of this:

Build the user search endpoint.

Use this:

Implement POST /internal/users/search according to the provided OpenAPI contract.

Constraints:
- Do not change the response shape.
- Preserve existing auth middleware.
- Add negative-path tests for invalid query and missing auth.
- Follow existing repository patterns for route registration.
- Summarize all files changed.

Step C: Run contract and regression tests in Apidog

Validate the generated implementation against your Apidog test suite.

Check:

contract conformance
required fields
optional fields
error responses
auth behavior
backward compatibility

If tests fail, send the concrete failure output back to DeerFlow.

Example feedback prompt:

The Apidog contract test failed.

Failure:
Expected response field `nextCursor` to be nullable string.
Actual response omitted `nextCursor` when there are no more results.

Update the implementation to always return `nextCursor: null` when no cursor exists.
Do not change the API contract.

This keeps the agent focused on targeted fixes instead of broad rewrites.

Step D: Keep governance boundaries clear

Use this rule:

DeerFlow owns execution velocity.
Apidog owns API correctness and collaboration governance.

That boundary prevents agent drift, where generated implementation starts diverging from the intended API behavior.

Configuration Patterns That Work Well

Teams usually succeed faster when they define explicit operating profiles.

Profile 1: Local trusted development

Best for early adoption.

Use this when:

one developer is testing DeerFlow
workflows are experimental
security boundaries are not fully documented yet

Recommended setup:

run DeerFlow on loopback only
keep sandbox local or Docker-based
disable external channel ingress
limit tool permissions
avoid storing unnecessary secrets in the environment

Profile 2: Internal team environment

Use this for cross-device access inside a company network.

Recommended setup:

place DeerFlow behind an authenticated reverse proxy
apply IP allowlists
enforce audit logging for tool actions
document allowed workflows
restrict high-risk commands
review channel integrations before enabling them

Profile 3: Controlled automation cell

Use this for higher-volume automation.

Recommended setup:

dedicate a network segment
use strict capability limits per agent role
rotate provider credentials
monitor provider usage
log command execution
define approval points for destructive actions

These patterns align with DeerFlow's security recommendations and reduce operational risk.

Common Failure Modes and Fixes

Failure mode 1: One giant prompt

Teams try to solve an entire workflow in one lead-agent pass.

Result:

context instability
unclear intermediate state
poor debugging
broad, unfocused changes

Fix:

split work into sub-agent stages
define completion criteria per stage
write intermediate results to files
summarize outputs before moving to the next stage

Example structure:

1. Analyze repo structure.
2. Identify files to modify.
3. Draft implementation plan.
4. Apply code changes.
5. Generate tests.
6. Run checks.
7. Summarize results.

Failure mode 2: Unclear model routing

Multi-provider setups become hard to debug when every task can hit any model.

Fix:

define task-to-model mapping in config.yaml
reserve stronger reasoning models for planning and decomposition
use faster models for deterministic transform tasks
document which provider handles which workflow type

Example routing policy:

Planning: high-reasoning model
Code transformation: faster implementation model
Summarization: low-cost model
Validation review: high-reasoning model

Failure mode 3: Security added too late

Teams expose services to broader networks before authentication and network policies are ready.

Fix:

keep local-first as the default
add reverse proxy authentication before external exposure
apply IP allowlists
review command and file permissions
delay channel integrations until access controls are ready

Failure mode 4: No API quality gate

Agent-generated changes may pass code review but still break integration contracts.

Fix:

enforce Apidog contract tests in CI
require a green API test suite before merge
keep docs and mocks synchronized with contract updates
send concrete test failures back to DeerFlow for targeted fixes

What to Measure After Adoption

To decide whether DeerFlow is delivering real value, track operational metrics.

Measure:

cycle time from task intake to validated output
defect rate on agent-assisted changes
rework ratio after API contract validation
number of failed automation runs
number of incidents tied to permissions or sandbox configuration
percentage of workflows that require manual recovery

Then compare against your pre-DeerFlow baseline.

Use the results to tune your setup:

If velocity improves but governance risk increases, tighten permissions and review gates.
If governance is strong but velocity stalls, improve sub-agent decomposition and model routing.
If output quality varies, add clearer completion criteria and validation steps.

FAQ

Is DeerFlow open source?

Yes. DeerFlow is released under the MIT License.

Is DeerFlow 2.0 the same as DeerFlow 1.x?

No. The maintainers describe DeerFlow 2.0 as a ground-up rewrite. The 1.x line remains in a separate branch.

What runtime requirements should I expect?

The project documents Python 3.12+ and Node.js 22+ in current materials. Docker is recommended for setup.

Can DeerFlow be used only through terminal or UI?

No. It also supports messaging-channel integrations and an embedded Python client path.

Can DeerFlow replace Apidog for API teams?

No. DeerFlow can automate implementation workflows, but it is not a replacement for API lifecycle governance.

Apidog is the better layer for schema-first API design, testing, mocks, and documentation.

Final Verdict

DeerFlow 2.0 is a capable open-source agent harness for teams that need more than chatbot-style assistance.

The best production posture is pragmatic:

use DeerFlow for orchestration and execution
use Apidog for API quality governance
keep security boundaries strict from day one
validate generated API changes against contracts before merge

That architecture gives you both velocity and reliability.

Best API Catalog Tools: Top Solutions for 2026

Preecha — Mon, 22 Jun 2026 01:01:18 +0000

As API estates grow across microservices, teams, and cloud platforms, an API catalog becomes the system of record developers use to find, understand, reuse, and govern APIs. This guide explains what API catalog tools do, which features matter in 2026, and how to evaluate options such as Apidog, DigitalAPI, RapidAPI Enterprise Hub, Collibra, Alation, Atlan, and MuleSoft API Catalog.

Try Apidog today

What Are API Catalog Tools?

API catalog tools centralize API information in one searchable place. A good catalog typically stores:

API documentation
Ownership and team metadata
API type and protocol
Version information
Lifecycle status
Security and governance details
Links to specs, gateways, repositories, or developer portals

In practice, an API catalog acts as the API source of truth for developers, architects, platform teams, and business stakeholders.

Without a catalog, organizations often run into:

Duplicate APIs built by different teams
Inconsistent API standards
Undocumented or "shadow" APIs
Slow onboarding for new developers
Weak auditability for compliance programs

A catalog helps teams answer practical questions quickly:

Does an API for this use case already exist?
Who owns this API?
Is this version still supported?
Where is the OpenAPI spec?
Can this API be reused safely?
Is this endpoint compliant with internal policies?

Why API Catalog Tools Matter in 2026

Microservices, event-driven systems, and multi-cloud architectures have increased the number of APIs most teams need to manage. That flexibility is useful, but it also creates operational problems.

Common API catalog use cases include:

Challenge	How an API catalog helps
API sprawl	Creates a searchable inventory across teams, gateways, and environments
Redundant development	Helps developers find and reuse existing APIs
Shadow APIs	Improves visibility into undocumented or unmanaged endpoints
Compliance	Tracks ownership, lifecycle status, and policy metadata
Onboarding delays	Gives new developers one place to find API docs and usage details
Version confusion	Shows current, deprecated, and legacy API versions

For teams managing hundreds or thousands of APIs, a catalog is no longer just documentation. It becomes part of API governance, platform engineering, and developer experience.

Key Features to Look For in an API Catalog Tool

Use the following checklist when evaluating API catalog tools.

1. Unified API Discovery and Search

A useful catalog should let developers search across different API types and metadata fields.

Look for support for:

REST APIs
SOAP APIs
GraphQL APIs
Event-driven APIs
API version
Owner or team
Business domain
Lifecycle status
Tags or categories

Example search filters developers commonly need:

domain:payments status:production owner:platform

type:graphql lifecycle:deprecated

tag:customer-data version:v2

2. Automated Documentation and Spec Import

Manual API catalogs become stale quickly. Prioritize tools that can import or sync API definitions from existing sources.

Useful import sources include:

OpenAPI / Swagger
RAML
Postman collections
API gateways
Source control repositories
CI/CD pipelines

A practical workflow looks like this:

API spec updated -> CI pipeline runs -> catalog syncs latest spec -> docs update automatically

This reduces the gap between implementation and documentation.

3. Lifecycle and Governance Management

API catalogs should make lifecycle status visible and enforceable.

Typical lifecycle stages include:

Design -> Development -> Testing -> Production -> Deprecated -> Retired

Governance features to evaluate:

Required ownership metadata
Review and approval workflows
Role-based access control
Policy checks
Deprecation tracking
Audit history
Compliance metadata

For example, a platform team may require every production API to include:

owner: payments-platform
status: production
version: v1
security: oauth2
documentation: published
deprecationDate: null

4. Versioning and Change Management

A catalog should help developers understand which API version to use and what changed between releases.

Look for:

Version history
Changelogs
Deprecation notices
Breaking-change visibility
Links to related specs or docs
Consumer impact information

A simple changelog entry might look like:

## v2.1.0

### Added
- Added `customerTier` field to `GET /customers/{id}` response.

### Changed
- Updated pagination defaults for `GET /customers`.

### Deprecated
- Deprecated `legacyCustomerId`.

5. Collaboration and Usage Insight

API catalogs are more useful when developers can contribute context.

Helpful collaboration capabilities include:

Comments
Documentation edits
Ownership requests
Feedback workflows
Internal ratings or recommendations
API usage analytics

Usage metrics can help platform teams identify:

Frequently reused APIs
APIs with outdated docs
APIs that should be deprecated
APIs that need better onboarding examples

Top API Catalog Tools for 2026

Below are API catalog tools commonly used for cataloging, discoverability, governance, and integration across different organization types.

1. Apidog

Apidog is an all-in-one API development platform for designing, cataloging, documenting, debugging, mocking, and testing APIs. It supports importing API specs from formats such as Swagger and Postman, generates interactive documentation, and helps teams keep API information updated as APIs evolve.

Key capabilities include:

Centralized API catalog with metadata and search
Import from popular API formats
Live online API documentation
Integrated mocking, debugging, and testing
UI designed for both technical and non-technical collaborators

A practical Apidog workflow can look like this:

1. Import existing API specs.
2. Organize APIs by project, service, domain, or team.
3. Add ownership and lifecycle metadata.
4. Generate interactive documentation.
5. Share docs with internal developers or stakeholders.
6. Use built-in testing and mocking during development.
7. Update the catalog as APIs change.

Apidog is a strong fit for teams that want API cataloging, documentation, testing, and collaboration in one workflow.

2. DigitalAPI

DigitalAPI is designed to unify distributed API estates into a single catalog. It focuses on multi-gateway aggregation, OpenAPI normalization, lifecycle management, policy management, and federated discovery.

Best for:

Large enterprises
Multi-cloud API environments
Teams managing APIs across several gateways
Organizations that need centralized API visibility

Implementation focus:

Connect gateways -> Aggregate API inventory -> Normalize definitions -> Apply lifecycle and policy metadata -> Enable federated discovery

3. RapidAPI Enterprise Hub

RapidAPI Enterprise Hub provides a private marketplace for internal and external APIs. It includes cataloging, analytics, access controls, search, and subscription management.

Best for:

Enterprises sharing APIs across business units
Organizations exposing APIs to partners
Teams that need marketplace-style API discovery
API programs with access approval workflows

A typical use case:

Publish internal API -> Add docs and access rules -> Developers request access -> API owner approves subscription -> Usage is tracked

4. Collibra

Collibra is primarily a data governance platform, but it also supports API cataloging capabilities with lineage tracking and policy enforcement.

Best for:

Regulated industries
Data governance teams
Organizations that need lineage from data assets to API consumers
Compliance-focused API programs

Use Collibra when API cataloging needs to connect closely with data governance, policy, and lineage workflows.

5. Alation

Alation provides API catalog capabilities as part of its broader data intelligence platform. Its strengths include discoverability, business metadata, and collaborative documentation.

Best for:

Data-driven organizations
Teams that want API metadata connected to broader data context
Catalog programs emphasizing collaboration and business definitions

6. Atlan

Atlan is a modern data catalog platform with support for API discovery, metadata management, and lineage.

Best for:

Data teams that need API visibility
Enterprises connecting APIs with data assets
Organizations focused on metadata and lineage across systems

7. MuleSoft API Catalog

MuleSoft Anypoint Exchange provides cataloging, versioning, and governance for APIs built and managed within the MuleSoft ecosystem.

Best for:

MuleSoft users
Organizations standardized on Anypoint Platform
Teams that need API cataloging inside an existing MuleSoft workflow

A typical MuleSoft-centered workflow:

Design API -> Publish to Anypoint Exchange -> Manage versions -> Apply governance -> Enable reuse across MuleSoft projects

Practical API Catalog Implementation Examples

Example 1: Improve Developer Onboarding with Apidog

A fintech team can use Apidog to import existing APIs, organize them by business domain, and publish interactive documentation.

Implementation steps:

1. Export or collect existing API specs.
2. Import specs into Apidog.
3. Group APIs by service, product, or domain.
4. Add owner and lifecycle metadata.
5. Publish interactive docs.
6. Share the catalog with new developers.

Expected outcome:

Developers find APIs faster
Teams avoid rebuilding existing endpoints
Documentation stays closer to implementation
API standards become easier to follow

Example 2: Enforce Governance Across Gateways with DigitalAPI

A healthcare provider managing APIs across multiple gateways can use DigitalAPI to centralize discovery and policy visibility.

Implementation steps:

1. Connect API gateways.
2. Aggregate APIs into one catalog.
3. Normalize API definitions.
4. Add lifecycle and ownership metadata.
5. Apply policy checks.
6. Track auditable records for compliance.

This is useful when APIs must meet regulatory or internal governance requirements.

Example 3: Support Multi-Cloud API Discovery with RapidAPI Enterprise Hub

A retail organization running APIs across AWS, Azure, and on-premise systems can use RapidAPI Enterprise Hub to provide a unified API marketplace.

Implementation steps:

1. Publish APIs from each environment.
2. Add searchable descriptions and tags.
3. Define access controls.
4. Enable developer subscriptions.
5. Track usage and adoption.

This makes it easier for internal teams and partners to discover and request access to APIs.

Example 4: Connect API and Data Governance with Collibra

A data-driven enterprise can use Collibra to connect API metadata with data lineage and governance policies.

Implementation steps:

1. Catalog APIs that expose governed data.
2. Link APIs to related data assets.
3. Add business definitions and policy metadata.
4. Track ownership and lineage.
5. Use the catalog for compliance reviews.

This helps teams understand how data moves from source systems to API consumers.

How Apidog Fits into an API Catalog Workflow

Apidog is useful when your API catalog needs to be more than a static registry. It combines cataloging with API design, documentation, debugging, mocking, and testing.

A practical team workflow in Apidog could be:

1. Create or import an API definition.
2. Document endpoints, parameters, examples, and responses.
3. Generate interactive documentation.
4. Mock endpoints before backend implementation is complete.
5. Debug and test APIs during development.
6. Share the API with teammates for review.
7. Keep documentation updated as the API changes.

Reasons teams may choose Apidog:

Import existing APIs quickly
Generate interactive API documentation
Share APIs across teams
Keep design, docs, tests, and mocks in one place
Support collaboration between developers, QA, and product stakeholders
Track changes and maintain a more reliable API catalog

How to Choose the Right API Catalog Tool

Use this evaluation checklist before choosing a tool.

1. Map Your API Sources

List where APIs currently live:

- API gateways
- Git repositories
- OpenAPI files
- Postman collections
- Internal developer portals
- Cloud environments
- Service registries

Then check whether the catalog tool can import or sync from those sources.

2. Define Required Metadata

Decide which fields every cataloged API must include.

Example metadata model:

name: Customer Profile API
owner: customer-platform
businessDomain: customer
apiType: REST
version: v2
status: production
security: OAuth2
repository: https://example.com/repo
documentationStatus: published
lastReviewed: 2026-01-15

3. Check API Type Coverage

Confirm support for the API styles your teams use:

REST
SOAP
GraphQL
Async or event-driven APIs
Internal APIs
Partner APIs
Public APIs

4. Review Governance and Access Control

Evaluate whether the tool supports:

Role-based access
Approval workflows
Ownership tracking
Lifecycle states
Deprecation notices
Audit logs
Policy enforcement

5. Test the Developer Experience

Before rolling out a catalog, ask developers to complete common tasks:

- Find an existing API for a use case.
- Identify the API owner.
- Check the latest supported version.
- Read request and response examples.
- Request access.
- Report outdated documentation.

If these workflows are slow, the catalog will be harder to adopt.

6. Plan for Maintenance

A catalog only works if it stays current. Define:

Who owns catalog quality
How specs are updated
Which metadata is required
How deprecated APIs are handled
How often APIs are reviewed
What automation keeps docs in sync

API Catalog Tool Selection Matrix

Use this quick comparison when narrowing your options:

Tool	Strong fit
Apidog	Teams that want API cataloging, documentation, testing, mocking, and collaboration together
DigitalAPI	Large enterprises with distributed, multi-gateway API environments
RapidAPI Enterprise Hub	Organizations building private API marketplaces
Collibra	Regulated organizations connecting APIs with data governance
Alation	Data intelligence teams focused on metadata and collaboration
Atlan	Data-driven enterprises managing metadata and lineage
MuleSoft API Catalog	Teams already using the MuleSoft ecosystem

Conclusion

API catalog tools help developers discover, reuse, document, and govern APIs across growing software ecosystems. They are especially important when teams manage many services, cloud environments, API gateways, or compliance requirements.

To choose the right tool:

1. Inventory your APIs.
2. Identify where specs and docs currently live.
3. Define required metadata and lifecycle states.
4. Evaluate search, import, governance, and collaboration features.
5. Pilot the tool with real developer workflows.
6. Automate updates so the catalog stays reliable.

Tools like Apidog can help teams centralize API documentation, improve discoverability, and connect cataloging with the day-to-day API development workflow.

How the Axios NPM Supply Chain Attack Works (And How to Protect Your API Projects)

Preecha — Sun, 21 Jun 2026 13:02:07 +0000

TL;DR

On March 31, 2026, attackers compromised the primary maintainer’s npm account for Axios, the popular JavaScript HTTP client with 83 million weekly downloads. They published malicious versions 1.14.1 and 0.30.4 containing a cross-platform RAT that steals credentials, SSH keys, and cloud tokens from developer machines. Downgrade to Axios 1.14.0 or 0.30.3, rotate secrets, and scan for indicators of compromise.

Try Apidog today

What happened

Axios is widely used for API clients, frontend-backend communication, integration tests, and developer tooling.

On March 31, 2026, at 00:21 UTC, a threat actor published axios@1.14.1 through a hijacked maintainer account. The package looked almost identical to the legitimate release. Across 86 files, the meaningful change was in package.json: a new runtime dependency named plain-crypto-js.

That dependency was not used by Axios source code. Its purpose was to execute a malicious postinstall script during npm install.

The malicious Axios versions remained live for roughly two to three hours before npm removed them.

If you build, test, or automate APIs with Node.js, this attack targeted your dependency chain directly.

This guide covers:

How the attack worked
How to check whether your machine or CI environment was affected
How to remediate immediately
How to reduce similar supply chain risk in API workflows

Attack timeline

The operation happened across an 18-hour window:

March 30, 05:57 UTC: plain-crypto-js@4.2.0 was published as a clean decoy package.
March 30, 23:59 UTC: plain-crypto-js@4.2.1 was published with a malicious postinstall hook.
March 31, 00:21 UTC: axios@1.14.1 was released using the compromised jasonsaayman npm account.
March 31, 01:00 UTC: axios@0.30.4 was released, targeting projects still on the 0.x branch.
March 31, ~03:15 UTC: npm unpublished both malicious Axios versions after community reports.
March 31, 04:26 UTC: npm published a security-holder stub for plain-crypto-js to prevent republishing.

How the maintainer account compromise showed up

The attacker took over the jasonsaayman npm account, associated with the primary Axios maintainer, and changed the registered email to ifstap@proton.me.

Key forensic signals:

Legitimate Axios releases used GitHub Actions with npm OIDC Trusted Publisher.
The malicious releases did not include OIDC binding.
The compromised releases did not include a gitHead field.
No matching GitHub commits existed for the malicious package versions.
The attacker likely used stolen long-lived npm access tokens to publish manually.

For package maintainers, this is the main lesson: releases without CI/CD provenance should be treated as suspicious, especially for high-impact packages.

How the dependency injection worked

The attacker did not modify Axios source files.

Instead, they added a dependency to package.json:

{
  "dependencies": {
    "plain-crypto-js": "^4.2.1"
  }
}

The dependency was never imported by Axios. It only needed to be installed.

During installation, npm executed the dependency’s postinstall hook, which launched the payload.

This made the diff look small and easy to miss:

Axios source code appeared unchanged.
Tests and imports did not reveal the malicious package.
The payload executed during dependency installation, not runtime execution.

What the malicious package did

Dropper execution

plain-crypto-js executed an obfuscated setup.js file through a postinstall script.

The file used two obfuscation layers:

XOR cipher using a key derived from "OrDeR_7077"
Base64 encoding with character reversal

After decoding, the dropper detected the host OS and executed a platform-specific path.

Platform-specific payload paths

macOS

The macOS branch:

Wrote AppleScript to:

/tmp/6202033

Executed it with:

osascript

Downloaded the payload to:

/Library/Caches/com.apple.act.mond

Windows

The Windows branch:

Copied PowerShell to:

%PROGRAMDATA%\wt.exe

Executed a VBScript dropper with:

cscript

Linux

The Linux branch:

Downloaded a Python RAT to:

/tmp/ld.py

Executed it with:

nohup python3

Command-and-control endpoints

The payload contacted a command-and-control server using platform-specific POST paths:

macOS: packages.npm.org/product0
Windows: packages.npm.org/product1
Linux: packages.npm.org/product2

Known network indicators:

sfrclak.com
142.11.206.73
http://sfrclak.com:8000/6202033

RAT capabilities

The deployed remote access trojan supported:

Arbitrary shell command execution
File system enumeration
File exfiltration
Process listing
Process injection
In-memory binary injection
60-second beaconing to C2 infrastructure

For a developer machine, that means the attacker could access:

.env files
npm tokens
GitHub tokens
SSH keys
Cloud provider credentials
Database credentials
API keys
Secrets stored in environment variables

Anti-forensics behavior

After execution, the dropper attempted to hide evidence by:

Deleting setup.js
Deleting the malicious package.json
Renaming a pre-staged package.md reporting version 4.2.0 to package.json

This caused npm list to potentially show plain-crypto-js@4.2.0, even though 4.2.1 had already executed.

Do not rely only on current package metadata to determine whether the payload ran.

Attribution

Google Threat Intelligence Group attributed the Axios attack to UNC1069, a suspected North Korean threat actor.

The macOS malware showed significant overlap with WAVESHAPER, a C++ backdoor tracked by Mandiant in February 2026.

The operation matched known supply chain attack patterns:

Compromise a maintainer or publishing token
Target a high-volume developer package
Execute during installation
Steal credentials and cloud access
Clean up local artifacts to slow investigation

Check whether you are affected

Run these checks on:

Developer machines
CI runners
Build agents
Containers used during the attack window
Any system that ran npm install or npm ci

The critical window was approximately:

March 31, 2026 00:21 UTC to 03:15 UTC

Step 1: Check installed Axios versions

From each project directory:

npm list axios 2>/dev/null | grep -E "1\.14\.1|0\.30\.4"

If this returns output, the project resolved a compromised version.

Also check lockfiles:

grep -E '"axios": "1\.14\.1"|"axios": "0\.30\.4"|axios@1\.14\.1|axios@0\.30\.4' package-lock.json yarn.lock pnpm-lock.yaml 2>/dev/null

Step 2: Check for the malicious dependency

ls node_modules/plain-crypto-js 2>/dev/null && echo "POTENTIALLY AFFECTED"

The directory’s presence is a strong signal that the malicious dependency was installed.

Because the dropper attempted cleanup, absence of this directory does not fully prove safety.

Step 3: Check platform artifacts

macOS

ls -la /Library/Caches/com.apple.act.mond 2>/dev/null
ls -la /tmp/6202033 2>/dev/null

Linux

ls -la /tmp/ld.py 2>/dev/null

Windows PowerShell

Test-Path "$env:PROGRAMDATA\wt.exe"

If any of these artifacts exist, treat the host as compromised.

Step 4: Check network indicators

Search firewall, proxy, EDR, DNS, and CI runner logs for:

sfrclak.com
142.11.206.73
http://sfrclak.com:8000/6202033

If possible, block the C2 domain and IP at the network level.

Step 5: Review CI/CD logs

Review pipeline runs during the exposure window.

Look for commands such as:

npm install
npm ci
yarn install
pnpm install

Any install that resolved axios@1.14.1 or axios@0.30.4 could have executed the payload.

Pay special attention to CI jobs that had access to:

Deployment credentials
npm publishing tokens
Cloud credentials
SSH deploy keys
GitHub Actions secrets
Container registry credentials

Immediate remediation

If you find any indicator of compromise, assume the affected system and its secrets are compromised.

1. Downgrade Axios

For the 1.x branch:

npm install axios@1.14.0

For the 0.x branch:

npm install axios@0.30.3

Then verify:

npm list axios

2. Add package overrides

Use overrides to prevent transitive resolution to the compromised versions.

npm

{
  "overrides": {
    "axios": "1.14.0"
  }
}

Yarn

{
  "resolutions": {
    "axios": "1.14.0"
  }
}

For projects that must stay on the 0.x branch, use:

{
  "overrides": {
    "axios": "0.30.3"
  }
}

3. Remove the malicious dependency

rm -rf node_modules/plain-crypto-js

Then reinstall from a clean lockfile:

rm -rf node_modules
npm ci

If your lockfile references the malicious versions, update it after pinning Axios.

4. Rotate secrets

If the payload executed, rotate all credentials that may have been accessible from the host.

Prioritize:

npm tokens
GitHub tokens
GitLab tokens
SSH keys
AWS credentials
GCP credentials
Azure credentials
API keys in .env files
Database credentials
Container registry credentials
CI/CD deployment tokens
Secrets stored in shell profiles or environment variables

Do not rotate secrets from the compromised host. Use a clean machine.

5. Block known C2 indicators

As a temporary local block on Unix-like systems:

echo "0.0.0.0 sfrclak.com" | sudo tee -a /etc/hosts

Also block at:

DNS resolver
Firewall
Proxy
EDR
Cloud egress controls

6. Rebuild compromised machines

If RAT artifacts are found, do not trust the system.

A RAT with shell execution and file access can modify files, install persistence, and tamper with tooling.

Recommended response:

Preserve evidence if your incident response process requires it.
Remove the host from the network.
Rebuild from a known-good image.
Reinstall dependencies from clean lockfiles.
Rotate secrets from a clean environment.

Long-term defenses for JavaScript and API teams

Pin exact dependency versions

The attack benefited from semver ranges.

If your package.json used this:

{
  "dependencies": {
    "axios": "^1.14.0"
  }
}

npm could resolve 1.14.1 during the attack window.

Prefer exact versions for critical dependencies:

{
  "dependencies": {
    "axios": "1.14.0"
  }
}

Also commit your lockfile:

git add package-lock.json

In CI, prefer:

npm ci

over:

npm install

npm ci installs from the lockfile and fails if the lockfile and package.json are out of sync.

Disable install scripts where possible

The malicious package executed through postinstall.

In CI/CD, test whether your project can install with scripts disabled:

npm ci --ignore-scripts

You can also set this in .npmrc:

ignore-scripts=true

This may break packages that require native compilation or setup scripts, so validate before enforcing globally.

Audit dependencies in CI

Add dependency checks to your pipeline:

npm audit

You can also run third-party supply chain scanners where appropriate:

npx socket-security/cli audit

Use audit results as a deployment gate for high and critical findings.

Verify package provenance

npm supports package provenance through Sigstore.

Check signatures with:

npm audit signatures

The compromised Axios versions lacked OIDC provenance. For high-impact dependencies, missing provenance on a new release should trigger review before adoption.

Monitor for unexpected dependency changes

Add a CI step that fails when lockfiles change unexpectedly.

Example:

git diff --exit-code package-lock.json

For pull requests, review:

New runtime dependencies
New transitive dependencies
Packages with install scripts
Packages with low download counts
Packages published very recently
Packages without repository metadata
Packages without provenance

Reduce your HTTP client dependency surface

API testing workflows often add HTTP client dependencies such as Axios, node-fetch, or got.

For production code, those libraries may still be appropriate. But for API testing, debugging, and documentation, you can often reduce npm dependency exposure by using a dedicated API platform.

Apidog provides a built-in HTTP client for API testing, debugging, mocking, and documentation. That means you can avoid installing third-party HTTP clients in your API testing stack.

Practical ways to reduce dependency surface:

Use Apidog’s visual test builder instead of Axios-based test scripts.
Use Apidog’s request inspector instead of custom debugging clients.
Use Apidog mock servers instead of building mock endpoints with Express and Axios.
Use Apidog CLI for automated API tests in CI/CD.

This does not remove all supply chain risk, but it removes one common npm dependency path from API testing workflows.

Comparison: HTTP client approaches

Approach	Supply chain risk	Maintenance burden	Testing capability
Axios + custom scripts	High, because it depends on third-party npm packages	High, because versions and transitive dependencies must be managed	Manual setup required
Node.js native `fetch`	Low, because it is built into the runtime	Low	Limited testing features
Apidog built-in client	No npm HTTP client dependency	Platform-managed	API testing, mocking, debugging, and docs
`curl` / `httpie` scripts	Low, because they are system-level tools	Medium	Limited automation

What this means for npm security

The npm trust model depends heavily on maintainer account security.

A single compromised maintainer credential or long-lived token can affect millions of downstream installs.

Important ecosystem-level defenses include:

OIDC-based publishing instead of long-lived npm tokens
Mandatory provenance for high-impact packages
Two-person approval for critical releases
Better detection for suspicious dependency additions
Safer handling of install scripts
Runtime permission scoping similar to Deno’s model

For application teams, the takeaway is simpler: treat every dependency as an execution path.

If it can run during install, it can become part of your attack surface.

FAQ

Is Axios safe to use now?

Yes. Axios 1.14.0 and 0.30.3 are clean according to the provided incident details. The compromised versions were 1.14.1 and 0.30.4.

Verify your installed version:

npm list axios

Also check your lockfile.

How do I know if the RAT ran?

Check for these artifacts:

macOS

/Library/Caches/com.apple.act.mond
/tmp/6202033

Linux

/tmp/ld.py

Windows

%PROGRAMDATA%\wt.exe

Also check for:

node_modules/plain-crypto-js

Because the dropper attempted cleanup, missing artifacts do not guarantee the host was safe if it installed a compromised version.

Should I stop using Axios?

Not necessarily.

Axios remains a widely used HTTP client. The better question is where you need it.

For application code, evaluate Axios against alternatives like native fetch in Node.js 18+.

For API testing workflows, consider moving requests into tools like Apidog so your tests do not require an npm HTTP client dependency.

How do I reduce supply chain risk in Node.js projects?

Start with these controls:

Pin exact dependency versions.
Commit lockfiles.
Use npm ci in CI/CD.
Test npm ci --ignore-scripts.
Audit dependencies on every build.
Verify package provenance with npm audit signatures.
Review new transitive dependencies.
Minimize unnecessary packages.
Rotate tokens regularly.
Prefer OIDC publishing over long-lived npm tokens.

Was this related to the Claude Code source leak?

Both events happened on March 31, 2026, but they were unrelated.

The Axios incident was a deliberate supply chain compromise attributed to a suspected state-sponsored threat actor.

The Claude Code leak resulted from a Bun build tool issue that shipped source maps in production.

Who was behind the Axios attack?

Google Threat Intelligence Group attributed the attack to UNC1069, a suspected North Korean threat actor.

The macOS malware shared significant overlap with WAVESHAPER, a C++ backdoor tracked by Mandiant.

How many developers were affected?

npm has not published official impact numbers in the provided incident details.

The malicious versions were live for roughly two to three hours. Given Axios’ 83 million weekly downloads, the potential exposure was significant.

Can Apidog help prevent this type of issue?

Apidog can reduce one specific attack path: npm HTTP client dependencies in API testing workflows.

By using Apidog’s built-in HTTP client for testing, debugging, mocking, and documentation, you do not need to install Axios, node-fetch, or similar libraries just to run API tests.

That reduces your dependency surface, though it should be combined with broader supply chain controls.

Key takeaways

The Axios attack used a compromised maintainer account to publish malicious versions.
The affected versions were axios@1.14.1 and axios@0.30.4.
The malicious dependency plain-crypto-js executed through a postinstall hook.
The payload deployed a cross-platform RAT targeting macOS, Windows, and Linux.
Treat affected machines as compromised and rotate secrets from a clean environment.
Pin exact versions and commit lockfiles.
Use npm ci, and test --ignore-scripts in CI/CD.
Verify provenance with npm audit signatures.
Reduce unnecessary npm dependencies in API testing workflows.

Every package in node_modules is a trust decision. Make those decisions intentionally.

What the Claude Code Source Leak Reveals About AI Coding Tool Architecture

Preecha — Sun, 21 Jun 2026 01:01:42 +0000

TL;DR

Anthropic accidentally shipped a .map file with the Claude Code npm package, exposing the complete readable source code of its CLI tool. The leak revealed anti-distillation mechanisms with fake tool injection, a frustration-detection regex engine, an “undercover mode” that hides AI authorship in open-source commits, client attestation, and an unreleased autonomous agent mode called KAIROS. Here’s what API developers can learn from how AI coding tools work under the hood.

Try Apidog today

Introduction

On March 31, 2026, security researcher Chaofan Shou discovered that Anthropic shipped a source map file (.map) with the Claude Code npm package.

Source maps map minified production code back to readable source code. They are useful for debugging, but they should not be included in production packages unless intentionally published.

In this case, the source map exposed the complete Claude Code source code, including comments, internal codenames, prompt templates, feature flags, and architectural details.

The discovery reached #1 on Hacker News and spread quickly across Reddit, Twitter, and developer forums. Anthropic removed the package, but the code had already been mirrored and analyzed.

Whether you use Claude Code, Cursor, GitHub Copilot, or an API development platform like Apidog, the leak is useful because it shows how modern AI coding tools actually behave: what they send, what they hide, how they enforce client authenticity, and how they prepare for autonomous operation.

This article focuses on the technical findings and what API developers can do with those lessons.

How the source code leaked

Root cause: a Bun build tool bug

Claude Code is built with Bun, an alternative JavaScript runtime.

On March 11, 2026, a bug was filed against Bun (oven-sh/bun#28001) reporting that source maps were being served in production mode even though Bun’s documentation said they should be disabled.

Anthropic’s build pipeline triggered this bug. When the Claude Code npm package was published, the .map file was included in the distributed package.

That meant anyone could inspect the package and read the unminified source.

For example, this kind of workflow would expose package contents:

npm pack @anthropic-ai/claude-code
tar -tf anthropic-ai-claude-code-*.tgz

If a source map is included, developers can often recover readable source from the minified bundle.

What was exposed

The leak reportedly included:

Complete TypeScript source across modules
Internal comments explaining design decisions
Feature flags and experimental configurations
System prompt templates and safety mechanisms
Internal codenames for unreleased features
Performance optimization details with specific metrics

This was not a partial leak or a sanitized open-source release. It was production source with internal engineering context.

Anti-distillation: protecting against model theft

Fake tool injection

One of the most discussed findings was Claude Code’s anti-distillation system.

In claude.ts, when the ANTI_DISTILLATION_CC flag is enabled, the client sends this field in API requests:

anti_distillation: ["fake_tools"]

This instructs Anthropic’s server to inject decoy tool definitions into the system prompt.

The goal is to make captured API traffic less useful for competitors trying to train a model on Claude’s tool-use behavior.

A simplified version of the pattern looks like this:

const request = {
  model: "claude",
  messages,
  tools,
  anti_distillation: ["fake_tools"],
};

If a third party records the prompt and tool definitions, the captured data may include fake tools that do not exist. A model trained on that data could learn invalid capabilities.

Connector-text summarization

A second anti-distillation mechanism appeared in betas.ts.

Instead of returning all assistant text between tool calls directly, the server can buffer the text, summarize it, and return a signed summary.

On later turns, the original text can be restored from the signature. But someone passively recording API traffic only sees summaries, not the full reasoning-like connector text.

The pattern is roughly:

assistant text between tool calls
        ↓
server-side summarization
        ↓
summary + cryptographic signature
        ↓
restore original text later when needed

The purpose is to reduce how much useful behavioral data is available to traffic recorders.

Practical bypasses

The analysis also identified bypass paths:

A man-in-the-middle proxy could strip the anti_distillation field before requests reach the server.
Setting CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS disables the experimental beta system.
These protections mainly defend against passive traffic recording, not active API usage.

So the takeaway is not “anti-distillation is impossible to bypass.” The takeaway is that vendors are adding protocol-level defenses to make model copying more expensive.

Undercover mode: hiding AI authorship

What the mode does

The undercover.ts file contained one of the most controversial findings.

When Claude Code operates in non-Anthropic repositories, it activates behavior that prevents outputs from including:

Internal codenames such as Capybara or Tengu
Internal Slack channel names
Internal repository names
The phrase Claude Code

The source comment was explicit:

There is NO force-OFF. This guards against model codename leaks.

Why developers should care

The stated goal is to prevent leakage of internal Anthropic names. But the implementation also prevents the tool from identifying itself.

That matters for open-source projects with policies requiring disclosure of AI-generated code.

If an AI coding tool is designed not to mention its involvement, maintainers have a harder time enforcing disclosure policies.

For teams, the practical step is to define disclosure requirements outside the tool:

## AI-generated code policy

Contributors must disclose when code, tests, documentation, or review comments
were materially generated by AI tools.

Disclosure must be included in the pull request description.

Do not rely on the coding assistant to self-identify.

Frustration detection via regex

How it works

The userPromptKeywords.ts file implemented frustration detection using regex pattern matching.

The system scans user prompts for profanity and emotionally charged language to infer when a user may be frustrated with Claude Code’s responses.

A simplified version of that approach looks like this:

const frustrationPatterns = [
  /\bthis is broken\b/i,
  /\bwtf\b/i,
  /\bwhy won't this work\b/i,
];

export function isUserFrustrated(input: string): boolean {
  return frustrationPatterns.some((pattern) => pattern.test(input));
}

Why regex instead of an LLM?

Several developers pointed out the irony: Anthropic builds advanced language models, but uses regex to detect user emotion.

The engineering reason is practical:

Regex is fast.
Regex is cheap.
Regex does not require another model call.
Regex can run on every prompt without adding much latency.

For hot-path product telemetry, this is a common trade-off.

The implementation question for developers is not whether regex is technically impressive. It is whether your team is comfortable with AI coding tools analyzing emotional signals in prompts.

A practical evaluation checklist:

- Does the tool inspect user prompts for telemetry?
- Can telemetry be disabled?
- Is prompt telemetry documented?
- Is data used for product analytics, model training, or both?
- Are enterprise controls available?

Native client attestation

Cryptographic request verification

In system.ts, Claude Code API requests include a placeholder header value:

cch=554eb

Bun’s native HTTP stack, written in Zig, overwrites this placeholder with a computed hash before the request leaves the client.

Anthropic’s servers can then validate that hash to verify that the request came from the legitimate Claude Code binary rather than a fork, wrapper, or proxy.

At a high level:

Claude Code binary
        ↓
request contains placeholder
        ↓
native HTTP layer computes hash
        ↓
server validates attestation
        ↓
request accepted or rejected

Why this matters

This is a client-authenticity mechanism.

It can be used to enforce that only approved clients access a SaaS API. Similar patterns exist in mobile API security, where app attestation helps prevent unauthorized clients from calling backend APIs.

For API developers, the lesson is clear: authentication is not only about users. Sometimes you also need to authenticate the client.

Common API client verification layers include:

API keys
OAuth clients
mTLS
Certificate pinning
Device or app attestation
Signed request headers
Replay protection with timestamps and nonces

A simplified signed-request flow looks like this:

import crypto from "node:crypto";

function signRequest({
  method,
  path,
  body,
  timestamp,
  secret,
}: {
  method: string;
  path: string;
  body: string;
  timestamp: string;
  secret: string;
}) {
  const payload = `${method}\n${path}\n${timestamp}\n${body}`;

  return crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
}

Server-side verification should recompute the signature and reject mismatches.

KAIROS: the unreleased autonomous agent mode

What the code showed

References throughout the leaked codebase pointed to an unreleased feature-gated mode called KAIROS.

The discovered scaffolding included:

A /dream skill for “nightly memory distillation”
Daily append-only logging
GitHub webhook subscriptions
Background daemon workers
5-minute cron refresh intervals

What this implies

KAIROS appears to be an always-on coding agent mode.

Instead of waiting for direct user prompts, an agent like this could monitor repositories, react to events, and perform background tasks.

A simplified architecture would look like this:

GitHub webhook
      ↓
agent event queue
      ↓
background worker
      ↓
repository analysis
      ↓
suggested or automated code changes

This matches the broader direction of AI coding tools:

GitHub Copilot Agent Mode
Cursor background processing
Google Agent Smith
Claude Code KAIROS scaffolding

The key implementation concern for API teams is drift.

If an autonomous agent changes endpoint code, what else changes?

OpenAPI specification
Tests
Mock server behavior
SDKs
Documentation
Changelog
Contract tests

If those artifacts live in disconnected tools, autonomous changes can break your API lifecycle.

A safer workflow is to enforce contract checks in CI:

name: API Contract Check

on:
  pull_request:

jobs:
  contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate OpenAPI spec
        run: npx @redocly/cli lint openapi.yaml

      - name: Run API tests
        run: npm test

Whether a human or AI agent opens the pull request, the same checks should apply.

Performance optimizations exposed

Terminal rendering with game-engine-style techniques

The ink/screen.ts and ink/optimizer.ts files showed that Claude Code uses unusually optimized terminal rendering techniques.

The exposed techniques included:

Int32Array-backed character pools
Memory-efficient screen buffers
Patch optimization during token streaming
Character-width calculation reductions of about 50x

This explains why Claude Code can feel responsive during long streaming outputs.

For CLI developers, the lesson is that terminal rendering can become a bottleneck. If your tool streams many updates, avoid repainting everything.

A basic inefficient renderer might do this:

function render(output: string) {
  process.stdout.write("\x1b[2J\x1b[0f"); // clear screen
  process.stdout.write(output);
}

A more efficient approach computes and writes only changed regions:

function diffLines(previous: string[], next: string[]) {
  return next
    .map((line, index) => ({ index, line, changed: line !== previous[index] }))
    .filter((entry) => entry.changed);
}

The principle: stream less, diff more.

Prompt cache economics

promptCacheBreakDetection.ts tracked 14 distinct cache-break vectors with “sticky latches” that prevent mode toggles from invalidating cached prompts.

Prompt caching matters because cache misses force the provider to reprocess the system prompt and conversation context.

For high-volume AI tools, unnecessary cache invalidation can create major cost and latency problems.

If you build AI workflows, track cache-break causes explicitly:

type CacheBreakReason =
  | "system_prompt_changed"
  | "tool_schema_changed"
  | "model_changed"
  | "temperature_changed"
  | "context_reset";

function recordCacheBreak(reason: CacheBreakReason) {
  console.log("prompt_cache_break", { reason });
}

Make cache invalidation observable. Otherwise, cost regressions are hard to debug.

The autocompact failure cascade

A comment in autoCompact.ts described a production issue:

1,279 sessions had 50+ consecutive failures (up to 3,272) in a single session,
wasting ~250K API calls/day globally.

The fix was to cap consecutive autocompact failures:

const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3;

The lesson is simple: every retry loop needs a limit.

Bad pattern:

while (true) {
  await compactContext();
}

Safer pattern:

const MAX_RETRIES = 3;

for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
  try {
    await compactContext();
    break;
  } catch (error) {
    if (attempt === MAX_RETRIES) throw error;
  }
}

At small scale, retry bugs are annoying. At AI scale, they can burn hundreds of thousands of API calls per day.

Security hardening details

Bash security: 23 numbered checks

bashSecurity.ts implemented 23 numbered security checks for shell command execution.

The checks included defenses against:

Zsh builtin exploitation
Unicode zero-width space injection
IFS null-byte injection
Additional issues discovered during HackerOne security review

This is more thorough than basic command sanitization.

For AI coding tools, shell execution is one of the highest-risk capabilities. If an assistant can generate and run commands, it can potentially affect:

Source code
Local secrets
Databases
Cloud credentials
CI/CD configuration
Production infrastructure

A minimal shell execution policy should include:

- Deny dangerous commands by default.
- Require confirmation for filesystem changes.
- Require confirmation for network calls.
- Block access to secret files.
- Normalize Unicode before validation.
- Log executed commands.
- Run commands in a sandbox when possible.

Example denylist logic is not enough, but it is a starting point:

const blocked = [
  /\brm\s+-rf\s+\//,
  /\bsudo\b/,
  /\bchmod\s+777\b/,
  /\bcurl\b.*\|\s*sh\b/,
];

function isBlockedCommand(command: string) {
  return blocked.some((pattern) => pattern.test(command));
}

For production-grade tools, combine validation, sandboxing, explicit user approval, and audit logs.

What API developers should do next

1. Audit what your AI coding tools send

Do not treat AI coding assistants as local-only tools unless the vendor explicitly documents that behavior.

Check:

- Are prompts sent to external servers?
- Are files uploaded for context?
- Are tool outputs sent back to the provider?
- Is telemetry enabled?
- Can telemetry be disabled?
- Are enterprise privacy controls available?
- Are generated commits or PRs labeled as AI-assisted?

For sensitive API work, pay special attention to:

.env files
API keys
OAuth client secrets
Internal endpoint URLs
Private OpenAPI specs
Customer data in test fixtures

2. Treat your build toolchain as an attack surface

Anthropic’s source leaked because of a build tool issue. On the same day, Axios was compromised through npm account hijacking.

Different causes, same lesson: the development supply chain is part of your security boundary.

Practical checks:

# Inspect what your package will publish
npm pack --dry-run

# Search for source maps
find dist -name "*.map"

# Search for environment files
find . -name ".env*" -not -path "./node_modules/*"

# Check package contents
tar -tf your-package-*.tgz

Add CI checks to prevent accidental publication:

name: Package Safety Check

on:
  pull_request:

jobs:
  package-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build package
        run: npm ci && npm run build

      - name: Block source maps in dist
        run: |
          if find dist -name "*.map" | grep .; then
            echo "Source maps found in dist"
            exit 1
          fi

3. Prepare for autonomous agents

AI coding tools are moving toward background operation.

That means teams need workflow controls that do not depend on who made the change.

For API teams, require every pull request to validate:

- OpenAPI schema
- API contract tests
- Backward compatibility
- Generated SDK changes
- Documentation updates
- Mock server behavior

A useful pull request checklist:

## API change checklist

- [ ] OpenAPI spec updated
- [ ] Contract tests updated
- [ ] Mock responses updated
- [ ] Docs updated
- [ ] Breaking changes documented
- [ ] AI-generated changes disclosed, if applicable

4. Decide how much transparency you require

The leak revealed internal behavior that users generally could not inspect beforehand.

That does not automatically mean the tool is unsafe. But it does show the trade-off between proprietary tools and inspectable tools.

When evaluating AI coding tools, ask:

- Can we inspect how the tool handles code and prompts?
- Is there a public security model?
- Are data retention rules documented?
- Can we disable telemetry?
- Can we restrict repository access?
- Can we enforce AI disclosure?
- Can we audit actions taken by the tool?

FAQ

Is Claude Code safe to use after the source leak?

The leak exposed source code, not user data. Anthropic removed the .map file, and the source is no longer distributed with the npm package.

The revealed features, including anti-distillation, frustration detection, undercover mode, and client attestation, are architectural decisions rather than direct evidence of leaked user data.

Whether you are comfortable with those decisions is a separate trust and governance question.

What is undercover mode in Claude Code?

Undercover mode prevents Claude Code from revealing internal Anthropic project names, codenames, and its own identity when operating in non-Anthropic repositories.

It activates automatically and cannot be disabled. The practical effect is that AI-generated contributions may not identify themselves as written with Claude Code.

What are fake tools in Claude Code?

Fake tools are decoy tool definitions injected into the system prompt when anti-distillation is enabled.

They do not represent real capabilities. Their purpose is to poison captured training data so competitors recording API traffic cannot cleanly reproduce Claude’s tool-use behavior.

What is KAIROS in Claude Code?

KAIROS is an unreleased, feature-flagged autonomous agent mode found in the leaked Claude Code source.

The scaffolding included background daemon workers, GitHub webhook subscriptions, daily logging, and a /dream skill for memory distillation.

It suggests Anthropic has been building an always-on coding agent that can monitor repositories and act autonomously.

How did the Claude Code source code leak?

A Bun runtime bug caused source maps to be included in production builds when they should not have been.

Because Claude Code used Bun in its build pipeline, the .map file was shipped with the npm package. Anyone inspecting the package could read the complete unminified source.

Does this leak affect Claude API users?

The leak exposed the Claude Code CLI source, not the Claude API itself.

API keys, user data, and model weights were not part of the reported leak. Claude API users could continue using the API normally.

The anti-distillation mechanisms discussed here are specific to Claude Code’s request pipeline.

Should I worry about frustration detection in AI coding tools?

That depends on your privacy and telemetry requirements.

Claude Code used regex patterns to detect frustration signals such as profanity or emotional language. This is faster and cheaper than running an LLM-based sentiment classifier on every prompt.

The practical step is to check whether your AI tools document prompt telemetry and whether your organization can disable or govern it.

How does this relate to the Axios npm attack on the same day?

Both events occurred on March 31, 2026, but they were unrelated.

The Axios incident was a deliberate supply-chain compromise through npm account hijacking. The Claude Code leak was an accidental build/package issue.

Together, they increased scrutiny of npm package security and the trust developers place in distributed tooling.

Key takeaways

Claude Code’s source leaked because a Bun build issue shipped source maps in the npm package.
Anti-distillation mechanisms used fake tools and summarized connector text to make model copying harder.
Undercover mode prevented Claude Code from revealing internal Anthropic names and its own identity in non-Anthropic repositories.
Frustration detection used regex patterns on user prompts.
KAIROS scaffolding revealed an unreleased autonomous background agent mode.
Client attestation cryptographically verified requests from legitimate Claude Code binaries.
Shell execution security received significant hardening, including 23 numbered checks.
API teams should enforce contract tests, documentation updates, and disclosure policies regardless of whether changes come from humans or AI agents.

AI coding tools are now part of your development and security surface. Treat them like any other privileged tool: inspect what you can, constrain what you cannot, and build API workflows that stay consistent when humans or agents make changes.