---
title: "Tanso agent guide"
canonical: https://tansohq.com/docs/agent-auth.md
description: "How an agent reads tansohq.com, runs the agent-ready CLI, contacts Tanso with permission, and integrates a self-hosted tanso-oss instance."
---

# Tanso agent guide

This guide distinguishes the public marketing site from a self-hosted tanso-oss instance.

## Read this website

Public product information needs no account. Use explicit .md links or request Accept: text/markdown. JSON site information is at https://tansohq.com/api/agent.

The demo is authored sample data. To check your own product, run the agent-ready CLI; see the next section. tansohq.com does not offer a hosted billing API, billing MCP server, OAuth server, or product signup. Agent signup exists in the open-source engine and runs on each self-hosted instance; see the section below.

## Evaluate a product with the agent-ready CLI

The agent-ready CLI (@tansohq/agent-ready, [source](https://github.com/tansohq/agent-ready-cli), MIT) is available now and free. It runs on the person's machine, not on tansohq.com. It needs Node 20.9 or later.

- The CLI needs no Tanso account, key, or signup, and sends nothing to Tanso.
- `npx @tansohq/agent-ready check yourproduct.com` reads public pages only (GET requests, at most 36 per run).
- `npx @tansohq/agent-ready test` has a real agent, the person's own signed-in Claude Code, try the task on their product. It creates a real account on that product, so run it only when the person asks. `npx @tansohq/agent-ready test --check` shows the plan for free.

Access and hosted runs: [auth.md](https://tansohq.com/auth.md). All steps: [quickstart](https://tansohq.com/quickstart.md). Hosted test runs are at https://app.tansohq.com. The hosted API is documented at https://app.tansohq.com/docs, with OpenAPI at https://app.tansohq.com/openapi.json. Hosted test runs: 5 free a month per workspace, then $5.00 per completed run. Inconclusive runs and runs that fail on Tanso's side are free. An agent can buy runs with POST /v1/purchases within a monthly cap ($50 by default, at most $200) that a person approves once through an approval link and Stripe Checkout. Free hosted runs need a workspace a person owns. A workspace an agent created through POST /v1/signup has none: its first hosted run answers 402 payment_required with an approval link, and the person who approves and pays takes ownership of the workspace. A person can also take ownership by signing in and entering the claim code on the Account page.

## Contact Tanso with permission

POST https://tansohq.com/api/evaluation-request accepts a contact request. Required JSON fields are requestId (UUID) and email (valid email). Optional fields: productUrl (http or https website, or a plain domain), task (up to 2,000 characters), and source (up to 80 letters, digits, underscores, or hyphens). Use source agent_evaluation.

Submit only with the person's permission. This does not create an account or authorize a purchase.

Success is HTTP 200 with {"success":true,"requestId":"..."}. Treat the request as received only after that response. Retry a timeout with the same requestId and identical payload. HTTP 400 means invalid input; 405 means unsupported method; 5xx means delivery was not confirmed. Keep the person's information available for retry. Email fallback: kat@tansohq.com.

## Integrate a self-hosted instance

Obtain the instance URL and appropriately scoped credentials from its operator. Follow the [deployment documentation](https://tanso.mintlify.app) and [repository instructions](https://github.com/tansohq/tanso-oss). Never send instance credentials to tansohq.com.

## Sign up an agent on a self-hosted instance

The engine, [tanso-oss](https://github.com/tansohq/tanso-oss), ships an opt-in agent signup endpoint. When the operator enables the public catalog for an account, POST {instance}/public/v1/catalog/{slug}/signup creates a customer on the free plan and returns a customer-scoped API key (ck_...) with read and purchase scopes in one call. No CAPTCHA and no email loop; the customer starts provisional and a completed Stripe payment claims it. Each instance serves the step-by-step runbook at {instance}/agent-signup.md and lists it in {instance}/.well-known/agent-skills/index.json. The instance URL and catalog slug come from the product you are buying from, not from tansohq.com.

The optional MCP server is enabled and configured by the operator. Review the current MCP documentation rather than assuming a hosted URL. Confirm the intended task, permitted actions, and necessary human approval. Check the resulting product state, not merely a successful status code.

- [agent-ready quickstart](https://tansohq.com/quickstart.md)
- [Open source](https://tansohq.com/product/agent-monetization.md)
- [MCP configuration](https://tanso.mintlify.app/mcp)
- [Quickstart](https://tanso.mintlify.app/quickstart)
- [Site index](https://tansohq.com/llms.txt)