# murakumo.cloud

> Murakumo is a distributed inference and agent platform. This is the compact
> machine-readable connection guide. The website and storefront live at
> `https://murakumo.cloud`; the single public inference and agent API boundary
> is `https://api.murakumo.cloud`.

## Public API boundary

- Base URL for inference and agent clients: `https://api.murakumo.cloud`
- Do not call `infer.murakumo.cloud`. It is an authenticated Cloudflare Tunnel
  origin used only by the API Worker to reach private fleet services.
- Readiness: `GET https://api.murakumo.cloud/ready`
- Model discovery: `GET https://api.murakumo.cloud/v1/models`
- Agent capability discovery: `GET https://api.murakumo.cloud/v1/grok-bots`
- Treat model registration and readiness as different facts. A model in
  `/v1/models` is a routable selector; clients should use bounded timeouts and
  must not describe it as live-verified until a real generation succeeds.

## OpenAI-compatible inference

### Chat Completions

`POST https://api.murakumo.cloud/v1/chat/completions`

The public first-value route accepts the OpenAI Chat Completions request shape
and caps `max_tokens` at 2048. Always discover current model IDs first. The
stable alias is `murakumo-main`.

```sh
curl https://api.murakumo.cloud/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{
    "model":"murakumo-main",
    "messages":[{"role":"user","content":"Reply exactly: ok"}],
    "max_tokens":64,
    "temperature":0
  }'
```

### RTX 5090 selector

As observed from `/v1/models` on 2026-08-25, the registered selector is:

- `qwen3.8-27b-throughput-5090` — advertised context window 32768

This selector is live-verified through the public API. On 2026-08-25 a
scale-to-zero request returned HTTP 200 after 237.45 seconds, with response
`.model` exactly `qwen3.8-27b-throughput-5090`; a warm request completed in
3.35 seconds. The gateway reserves up to 360 seconds for this RunPod cold-start
path, so clients should allow at least 420 seconds end to end. Fall back
explicitly to `murakumo-main` if that bounded request fails.

```sh
curl --max-time 420 https://api.murakumo.cloud/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{
    "model":"qwen3.8-27b-throughput-5090",
    "messages":[{"role":"user","content":"Reply exactly: 5090-ok"}],
    "max_tokens":64,
    "temperature":0
  }'
```

## Tool calls

For model-emitted function calls, use Chat Completions or the authenticated
Anthropic Messages surface. Murakumo returns the requested tool call; the
client executes the tool and sends the tool result in a follow-up request.
Tool availability depends on the selected model and is not implied merely by
its presence in `/v1/models`.

```sh
curl --max-time 420 https://api.murakumo.cloud/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{
    "model":"qwen3.8-27b-throughput-5090",
    "messages":[{"role":"user","content":"Use get_weather for Tokyo."}],
    "tools":[{
      "type":"function",
      "function":{
        "name":"get_weather",
        "description":"Get current weather",
        "parameters":{
          "type":"object",
          "properties":{"location":{"type":"string"}},
          "required":["location"]
        }
      }
    }],
    "tool_choice":{"type":"function","function":{"name":"get_weather"}},
    "max_tokens":128,
    "temperature":0
  }'
```

A successful model tool decision has
`choices[0].finish_reason = "tool_calls"` and one or more entries under
`choices[0].message.tool_calls`.

## Anthropic-compatible inference

`POST https://api.murakumo.cloud/v1/messages`

This surface translates Anthropic `tool_use` / `tool_result` blocks and
streaming events to and from the fleet's OpenAI-compatible origins. It requires
an authorized bearer or `x-api-key` accepted by Murakumo.

```sh
export ANTHROPIC_BASE_URL=https://api.murakumo.cloud
export ANTHROPIC_AUTH_TOKEN="$MURAKUMO_API_KEY"
claude
```

Never put access tokens, operator signing secrets, or origin credentials in an
agent configuration file committed to a repository.

## Responses and resident agents

- Capability descriptor: `GET /v1/grok-bots`
- Stateless Responses-compatible request: `POST /v1/responses`
- Namespaced alias: `POST /v1/grok-bots/responses`
- Namespaced Chat Completions alias: `POST /v1/grok-bots/chat/completions`
- Resident runtime status: `GET /v1/grok-bots/runtime`
- Resident bot management: `/v1/grok-bots/bots/*`

The Responses-compatible transport is non-streaming and supports a portable
subset of the OpenAI Responses request shape. The resident runtime is a
bounded durable agent loop with persistent checkpoints and a capability
allowlist. Management calls require a valid Murakumo service bearer.

The live capability descriptor observed on 2026-08-25 advertises
`murakumo-main` for the resident agent runtime. It does **not** advertise the
5090 selector. Do not claim that the durable agent loop runs on RTX 5090 until
`GET /v1/grok-bots` lists that model and an end-to-end agent tick succeeds.

```sh
curl https://api.murakumo.cloud/v1/responses \
  -H 'content-type: application/json' \
  -d '{"model":"murakumo-main","input":"Explain Murakumo in one sentence."}'
```

The canonical stateful agent service is
`https://itonami.cloud/api/v1/grok-bots`; the
`https://api.murakumo.cloud/v1/grok-bots` routes are compatibility aliases.
Murakumo remains the inference provider.

## Authentication

- `POST /v1/chat/completions` is the intentionally limited public first-value
  route.
- `POST /v1/messages`, `POST /v1/embeddings`, slow jobs, and resident-agent
  management are authenticated surfaces.
- Depending on the route, present either
  `Authorization: Bearer $MURAKUMO_API_KEY` or
  `x-api-key: $MURAKUMO_API_KEY`.
- Tokens are capabilities. Use the shortest practical lifetime and scope; do
  not forward a client token to an origin or third-party tool.

## Generation and the website

Image, video, 3D, voice, and music generation remain a separate product
surface documented by the website:

- Catalogue: `GET https://murakumo.cloud/api/v1/generation/catalog`
- Human-readable catalogue: `https://murakumo.cloud/models`
- Execute generation: `POST https://murakumo.cloud/api/v1/generation`
- Connection guide: `https://murakumo.cloud/docs`
- Storefront and credits: `https://murakumo.cloud/#store`

Generation models are not returned by `api.murakumo.cloud/v1/models`; that
endpoint is the inference model catalogue.

## Operational rules for agents

1. Use only `api.murakumo.cloud` for inference and agent calls.
2. Discover models and capabilities instead of hard-coding undocumented IDs.
3. Check `/ready`, then perform a small real request before claiming a model is
   available.
4. Assert the returned `.model`; HTTP 200 alone does not prove the requested
   backend served the request.
5. Use bounded timeouts and explicit fallback. Do not silently relabel fallback
   output as RTX 5090 output.
6. Never call `infer.murakumo.cloud` or expose its origin credentials.