Connect your application or agent.

Get ready to call the API

1. Start the local backend. Follow backend/README.md in your checkout to configure development OpenBao, MongoDB, and the OpenRouter provider credentials. Set DREAMTUNE_API_ORIGIN to its configured origin; the SDK requires HTTPS except for local loopback.
2. Create a key. In API keys, create a key for your server app. Copy it when shown; you cannot view it again. Enable the required tool, model or compute scopes and top up in Usage & billing.
3. Choose a free text model. Find an ID ending in :free in the Catalog. Replace provider/model:free in the examples with that exact ID. A catalog listing alone does not make a model callable through this API.

Install from the source checkout

Build the local package first, then install it into your own server project. Replace the example path with the absolute path to your checkout; quote it on Windows if it contains spaces. The package is not on npm, so npm install @dreamtune/sdk does not work yet.

# In your Dreamtune checkout
cd sdk/typescript
pnpm install --frozen-lockfile
pnpm build

# In your server application, use the absolute path to that folder
npm install /absolute/path/to/agent-router/sdk/typescript

Set DREAMTUNE_API_KEY and DREAMTUNE_API_ORIGIN in your server environment. Keep it out of browser code and source control.

import { DreamtuneClient } from "@dreamtune/sdk";

const apiKey = process.env.DREAMTUNE_API_KEY;
const baseUrl = process.env.DREAMTUNE_API_ORIGIN;
if (!apiKey || !baseUrl) throw new Error("Configure Dreamtune credentials and origin");

const client = new DreamtuneClient({
  apiKey,
  baseUrl,
});

const result = await client.freeChat({
  model: "provider/model:free", // Copy an exact free model ID from Catalog
  prompt: "Say hello in one sentence.",
});

console.log(result.text, result.usage);

Call the same endpoint directly

This example calls the separate free-text endpoint. The SDK also exposes tools, model runs and compute. Set the API key and origin first.

curl "$DREAMTUNE_API_ORIGIN/v1/developer/models/free-chat" \
  -H "Authorization: Bearer $DREAMTUNE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"provider/model:free","prompt":"Say hello."}'

A successful response contains model, text, and usage. Usage has prompt and completion token counts when the provider supplies them; it may be null. There is no streaming endpoint yet.

Credits, limits, and errors

Free models do not incur a charge. A workspace has ten attempts per UTC hour across all its keys. Keys expire after 30 days and stop working when revoked. Free-chat supports prompts up to 4,000 characters and 256 output tokens. Paid tool requests use your wallet. Successful tool and model runs charge confirmed usage; failed runs charge zero. Compute charges recorded usage until stopped or credit is exhausted. One completed charge may make the balance negative, blocking further work until recharge.

The SDK throws DreamtuneError with a status for API errors. A connection failure uses status 0. This is not an OpenAI-compatible chat completions API.

Choose your interface

• Website: use your browser.
• Node.js applications: use @dreamtune/sdk. Model requests use client.models; GPU jobs use client.compute.
• Terminal: install the built package globally from its local path, then use dreamtune --help.
• MCP agents: configure a stdio server with command dreamtuneand argument mcp. No separate HTTP server is needed.
• Agent skills: list bundled instructions with dreamtune skills listand install a named skill into your agent's skills directory.

npm install --global <absolute-path-to-sdk/typescript>
dreamtune tools list
dreamtune models limits
dreamtune compute catalog
dreamtune skills install dreamtune-tools --directory <agent-skills-directory>

CLI and MCP require the API key, origin and an explicit DREAMTUNE_REQUEST_TIMEOUT_MS deadline in their protected process environment. Never put credentials in command arguments. For paid submissions, persist an idempotency key before sending. A timeout does not prove failure or stop a GPU; inspect the existing request before retrying.

Read sdk/typescript/README.md for the complete command and SDK contracts. Skills provide instructions; backend scopes and billing still apply.