# Claude Code
Source: https://docs.dreamtunelabs.com/agents/claude-code
Connect Claude Code to Dreamtune MCP and install scoped workflow skills.
![Claude Code official logo]()
## Before you connect
Create a Dreamtune workspace API key with only the permissions you need.
Hosted HTTP setup needs no Dreamtune package installation. Local stdio setup
requires Node.js 22.20 or later and the published CLI.
## Configure
Merge this server entry into project .mcp.json. Preserve any other servers or settings.
```json theme={null}
{
"mcpServers": {
"dreamtune": {
"type": "http",
"url": "https://mcp.dreamtunelabs.com/mcp",
"headers": {
"X-Dreamtune-API-Key": "${DREAMTUNE_API_KEY}"
}
}
}
}
```
Set DREAMTUNE\_API\_KEY before launching Claude Code. Approve the project server when prompted and inspect /mcp. Explicit type http selects the correct transport.
## Verify the connection
Restart the client after changing settings or its environment. Open its MCP
server/tool status view and check that Dreamtune tools are listed. Ask it:
> Use Dreamtune to read model request limits. Do not execute a model, tool or GPU.
Confirm model\_limits returns limits before authorizing paid work. Then inspect a
catalog schema and use one explicitly approved operation. Keep client approval
controls enabled. Never put the key in a chat message, URL or repository.
## Add workflow instructions
Install the [Dreamtune skills](/connect/skills-install) into the skills directory
supported by your client, or copy the platform skill into a user instruction
workflow. A skill guides the agent; MCP provides execution. Neither grants extra
key permissions. See [troubleshooting](/errors) for 401, missing scopes, timeouts
and key/environment problems.
Configuration verified against [the official client documentation](https://code.claude.com/docs/en/mcp).
# Cline
Source: https://docs.dreamtunelabs.com/agents/cline
Connect Cline to Dreamtune MCP and install scoped workflow skills.
![Cline official logo]()
## Before you connect
Create a Dreamtune workspace API key with only the permissions you need.
Hosted HTTP setup needs no Dreamtune package installation. Local stdio setup
requires Node.js 22.20 or later and the published CLI.
## Configure
Merge this server entry into the configuration opened from Cline's MCP Servers settings. Preserve any other servers or settings.
```json theme={null}
{
"mcpServers": {
"dreamtune": {
"type": "streamableHttp",
"url": "https://mcp.dreamtunelabs.com/mcp",
"headers": {
"X-Dreamtune-API-Key": "YOUR_DREAMTUNE_KEY"
}
}
}
}
```
Replace the key in private settings. Explicit streamableHttp selects Streamable HTTP; omitting the type can select legacy SSE. Do not enable blanket auto-approval for paid operations.
## Verify the connection
Restart the client after changing settings or its environment. Open its MCP
server/tool status view and check that Dreamtune tools are listed. Ask it:
> Use Dreamtune to read model request limits. Do not execute a model, tool or GPU.
Confirm model\_limits returns limits before authorizing paid work. Then inspect a
catalog schema and use one explicitly approved operation. Keep client approval
controls enabled. Never put the key in a chat message, URL or repository.
## Add workflow instructions
Install the [Dreamtune skills](/connect/skills-install) into the skills directory
supported by your client, or copy the platform skill into a user instruction
workflow. A skill guides the agent; MCP provides execution. Neither grants extra
key permissions. See [troubleshooting](/errors) for 401, missing scopes, timeouts
and key/environment problems.
Configuration verified against [the official client documentation](https://docs.cline.bot/mcp/mcp-overview).
# Codex
Source: https://docs.dreamtunelabs.com/agents/codex
Connect Codex to Dreamtune MCP and install scoped workflow skills.
![Codex official logo]()
## Before you connect
Create a Dreamtune workspace API key with only the permissions you need.
Hosted HTTP setup needs no Dreamtune package installation. Local stdio setup
requires Node.js 22.20 or later and the published CLI.
## Configure
Merge this server entry into \~/.codex/config.toml (or trusted project .codex/config.toml). Preserve any other servers or settings.
```toml theme={null}
[mcp_servers.dreamtune]
url = "https://mcp.dreamtunelabs.com/mcp"
env_http_headers = { "X-Dreamtune-API-Key" = "DREAMTUNE_API_KEY" }
```
Set DREAMTUNE\_API\_KEY in the environment that launches Codex. The value on the right is an environment-variable name, not the key itself. Use codex mcp list or /mcp to inspect status.
## Verify the connection
Restart the client after changing settings or its environment. Open its MCP
server/tool status view and check that Dreamtune tools are listed. Ask it:
> Use Dreamtune to read model request limits. Do not execute a model, tool or GPU.
Confirm model\_limits returns limits before authorizing paid work. Then inspect a
catalog schema and use one explicitly approved operation. Keep client approval
controls enabled. Never put the key in a chat message, URL or repository.
## Add workflow instructions
Install the [Dreamtune skills](/connect/skills-install) into the skills directory
supported by your client, or copy the platform skill into a user instruction
workflow. A skill guides the agent; MCP provides execution. Neither grants extra
key permissions. See [troubleshooting](/errors) for 401, missing scopes, timeouts
and key/environment problems.
Configuration verified against [the official client documentation](https://developers.openai.com/codex/mcp).
# Continue
Source: https://docs.dreamtunelabs.com/agents/continue
Connect Continue to Dreamtune MCP and install scoped workflow skills.
![Continue official logo]()
## Before you connect
Create a Dreamtune workspace API key with only the permissions you need.
Hosted HTTP setup needs no Dreamtune package installation. Local stdio setup
requires Node.js 22.20 or later and the published CLI.
## Configure
Merge this server entry into .continue/mcpServers/dreamtune.yaml. Preserve any other servers or settings.
```yaml theme={null}
name: Dreamtune
version: 1.0.0
schema: v1
mcpServers:
- name: Dreamtune
type: stdio
command: dreamtune
args: [mcp]
env:
DREAMTUNE_API_KEY: ${{ secrets.DREAMTUNE_API_KEY }}
DREAMTUNE_API_ORIGIN: https://dreamtune-api.fly.dev
DREAMTUNE_REQUEST_TIMEOUT_MS: "135000"
```
Install @dreamtune/sdk globally, then supply DREAMTUNE\_API\_KEY through Continue's secrets configuration. Keep name, version and schema in the standalone file. This guide uses the documented local stdio form. Restart the agent after changing server settings.
## Verify the connection
Restart the client after changing settings or its environment. Open its MCP
server/tool status view and check that Dreamtune tools are listed. Ask it:
> Use Dreamtune to read model request limits. Do not execute a model, tool or GPU.
Confirm model\_limits returns limits before authorizing paid work. Then inspect a
catalog schema and use one explicitly approved operation. Keep client approval
controls enabled. Never put the key in a chat message, URL or repository.
## Add workflow instructions
Install the [Dreamtune skills](/connect/skills-install) into the skills directory
supported by your client, or copy the platform skill into a user instruction
workflow. A skill guides the agent; MCP provides execution. Neither grants extra
key permissions. See [troubleshooting](/errors) for 401, missing scopes, timeouts
and key/environment problems.
Configuration verified against [the official client documentation](https://docs.continue.dev/customize/deep-dives/mcp).
# Cursor
Source: https://docs.dreamtunelabs.com/agents/cursor
Connect Cursor to Dreamtune MCP and install scoped workflow skills.
![Cursor official logo]()
## Before you connect
Create a Dreamtune workspace API key with only the permissions you need.
Hosted HTTP setup needs no Dreamtune package installation. Local stdio setup
requires Node.js 22.20 or later and the published CLI.
## Configure
Merge this server entry into .cursor/mcp.json for the project, or \~/.cursor/mcp.json for your account. Preserve any other servers or settings.
```json theme={null}
{
"mcpServers": {
"dreamtune": {
"url": "https://mcp.dreamtunelabs.com/mcp",
"headers": {
"X-Dreamtune-API-Key": "${env:DREAMTUNE_API_KEY}"
}
}
}
}
```
Set DREAMTUNE\_API\_KEY in Cursor's process environment. A terminal environment changed after the editor started may not reach the MCP connection. Open Cursor's MCP settings to check tools.
## Verify the connection
Restart the client after changing settings or its environment. Open its MCP
server/tool status view and check that Dreamtune tools are listed. Ask it:
> Use Dreamtune to read model request limits. Do not execute a model, tool or GPU.
Confirm model\_limits returns limits before authorizing paid work. Then inspect a
catalog schema and use one explicitly approved operation. Keep client approval
controls enabled. Never put the key in a chat message, URL or repository.
## Add workflow instructions
Install the [Dreamtune skills](/connect/skills-install) into the skills directory
supported by your client, or copy the platform skill into a user instruction
workflow. A skill guides the agent; MCP provides execution. Neither grants extra
key permissions. See [troubleshooting](/errors) for 401, missing scopes, timeouts
and key/environment problems.
Configuration verified against [the official client documentation](https://cursor.com/docs/mcp).
# Gemini CLI
Source: https://docs.dreamtunelabs.com/agents/gemini-cli
Connect Gemini CLI to Dreamtune MCP and install scoped workflow skills.
![Gemini CLI official logo]()
## Before you connect
Create a Dreamtune workspace API key with only the permissions you need.
Hosted HTTP setup needs no Dreamtune package installation. Local stdio setup
requires Node.js 22.20 or later and the published CLI.
## Configure
Merge this server entry into \~/.gemini/settings.json. Preserve any other servers or settings.
```json theme={null}
{
"mcpServers": {
"dreamtune": {
"httpUrl": "https://mcp.dreamtunelabs.com/mcp",
"headers": {
"X-Dreamtune-API-Key": "${DREAMTUNE_API_KEY}"
}
}
}
}
```
Set DREAMTUNE\_API\_KEY before launching Gemini CLI. httpUrl selects Streamable HTTP; url selects the legacy SSE transport and is not interchangeable. Inspect /mcp after restarting.
## Verify the connection
Restart the client after changing settings or its environment. Open its MCP
server/tool status view and check that Dreamtune tools are listed. Ask it:
> Use Dreamtune to read model request limits. Do not execute a model, tool or GPU.
Confirm model\_limits returns limits before authorizing paid work. Then inspect a
catalog schema and use one explicitly approved operation. Keep client approval
controls enabled. Never put the key in a chat message, URL or repository.
## Add workflow instructions
Install the [Dreamtune skills](/connect/skills-install) into the skills directory
supported by your client, or copy the platform skill into a user instruction
workflow. A skill guides the agent; MCP provides execution. Neither grants extra
key permissions. See [troubleshooting](/errors) for 401, missing scopes, timeouts
and key/environment problems.
Configuration verified against [the official client documentation](https://geminicli.com/docs/tools/mcp-server/).
# Kiro
Source: https://docs.dreamtunelabs.com/agents/kiro
Connect Kiro to Dreamtune MCP and install scoped workflow skills.
![Kiro official logo]()
## Before you connect
Create a Dreamtune workspace API key with only the permissions you need.
Hosted HTTP setup needs no Dreamtune package installation. Local stdio setup
requires Node.js 22.20 or later and the published CLI.
## Configure
Merge this server entry into the configuration opened from Kiro's MCP panel. Preserve any other servers or settings.
```json theme={null}
{
"mcpServers": {
"dreamtune": {
"url": "https://mcp.dreamtunelabs.com/mcp",
"headers": {
"X-Dreamtune-API-Key": "${DREAMTUNE_API_KEY}"
}
}
}
}
```
Set DREAMTUNE\_API\_KEY in the process environment, then restart the client. Retain approval for spending and mutating tools instead of adding every tool to autoApprove.
## Verify the connection
Restart the client after changing settings or its environment. Open its MCP
server/tool status view and check that Dreamtune tools are listed. Ask it:
> Use Dreamtune to read model request limits. Do not execute a model, tool or GPU.
Confirm model\_limits returns limits before authorizing paid work. Then inspect a
catalog schema and use one explicitly approved operation. Keep client approval
controls enabled. Never put the key in a chat message, URL or repository.
## Add workflow instructions
Install the [Dreamtune skills](/connect/skills-install) into the skills directory
supported by your client, or copy the platform skill into a user instruction
workflow. A skill guides the agent; MCP provides execution. Neither grants extra
key permissions. See [troubleshooting](/errors) for 401, missing scopes, timeouts
and key/environment problems.
Configuration verified against [the official client documentation](https://kiro.dev/docs/mcp/configuration/).
# OpenCode
Source: https://docs.dreamtunelabs.com/agents/opencode
Connect OpenCode to Dreamtune MCP and install scoped workflow skills.
![OpenCode official logo]()
## Before you connect
Create a Dreamtune workspace API key with only the permissions you need.
Hosted HTTP setup needs no Dreamtune package installation. Local stdio setup
requires Node.js 22.20 or later and the published CLI.
## Configure
Merge this server entry into opencode.json. Preserve any other servers or settings.
```json theme={null}
{
"mcp": {
"dreamtune": {
"type": "remote",
"url": "https://mcp.dreamtunelabs.com/mcp",
"oauth": false,
"headers": {
"X-Dreamtune-API-Key": "{env:DREAMTUNE_API_KEY}"
}
}
}
}
```
Set DREAMTUNE\_API\_KEY in OpenCode's process environment. oauth false selects direct header authentication; Dreamtune execution MCP does not require an OAuth browser login. The outer property is mcp.
## Verify the connection
Restart the client after changing settings or its environment. Open its MCP
server/tool status view and check that Dreamtune tools are listed. Ask it:
> Use Dreamtune to read model request limits. Do not execute a model, tool or GPU.
Confirm model\_limits returns limits before authorizing paid work. Then inspect a
catalog schema and use one explicitly approved operation. Keep client approval
controls enabled. Never put the key in a chat message, URL or repository.
## Add workflow instructions
Install the [Dreamtune skills](/connect/skills-install) into the skills directory
supported by your client, or copy the platform skill into a user instruction
workflow. A skill guides the agent; MCP provides execution. Neither grants extra
key permissions. See [troubleshooting](/errors) for 401, missing scopes, timeouts
and key/environment problems.
Configuration verified against [the official client documentation](https://opencode.ai/docs/mcp-servers/).
# Connect your coding agent
Source: https://docs.dreamtunelabs.com/agents/overview
Choose a coding client, connect hosted or local MCP, and add Dreamtune skills.
Connect your agent to tools, models, compute and observability using a scoped
Dreamtune API key. Hosted MCP requires no local Dreamtune server. Local stdio
lets your client launch the published package and manage local GPU SSH access.
## Choose your client
![Codex official logo]()
![Claude Code official logo]()
![Cursor official logo]()
![VS Code and GitHub Copilot official logo]()
![Gemini CLI official logo]()
![Windsurf / Cascade official logo]()
![Cline official logo]()
![Roo Code (legacy) official logo]()
![OpenCode official logo]()
![Continue official logo]()
![Zed official logo]()
![Kiro official logo]()
Client formats differ. Copy the guide for your installed client instead of
renaming fields from another client's JSON. Roo Code is documented as a legacy
client because its official repository reports its shutdown.
## Choose the connection
| Need | Use |
| - | - |
| Execute Dreamtune operations without installing a local server | [Hosted HTTP MCP](/connect/mcp) |
| Local CLI, stdio or automatic SSH key handling | [Local MCP](/connect/local-mcp) |
| Search this documentation without executing paid work | [Documentation MCP](/connect/documentation-mcp) |
| Give your agent repeatable workflow instructions | [Dreamtune skills](/connect/skills-install) |
| Build an application | [TypeScript SDK](/sdk) |
An MCP server exposes tools; your coding agent's selected model decides when to
request them. The Dreamtune key authorizes execution and billing. Adding MCP
does not replace your editor's own subscription or model connection.
## Verify before paid work
First discover tools and read model\_limits or a catalog. Then inspect a selected
tool schema. Authorize a small, bounded execution only after confirming the
workspace, permissions and wallet. Save returned identifiers for recovery.
Review [security](/guides/security), [billing](/billing) and
[reliability](/guides/reliability) before granting broader access.
# Roo Code (legacy)
Source: https://docs.dreamtunelabs.com/agents/roo-code
Connect Roo Code (legacy) to Dreamtune MCP and install scoped workflow skills.
![Roo Code (legacy) official logo]()
## Before you connect
Create a Dreamtune workspace API key with only the permissions you need.
Hosted HTTP setup needs no Dreamtune package installation. Local stdio setup
requires Node.js 22.20 or later and the published CLI.
## Configure
Merge this server entry into the configuration opened from Roo's MCP settings. Preserve any other servers or settings.
```json theme={null}
{
"mcpServers": {
"dreamtune": {
"type": "streamable-http",
"url": "https://mcp.dreamtunelabs.com/mcp",
"headers": {
"X-Dreamtune-API-Key": "YOUR_DREAMTUNE_KEY"
}
}
}
}
```
Roo Code's official repository reports that its extension shut down on May 15. This configuration is retained for existing compatible installations, not as a recommendation to install an unsupported client. Consider an actively maintained client such as Cline. Replace the key privately; Roo's transport spelling differs from Cline's.
## Verify the connection
Restart the client after changing settings or its environment. Open its MCP
server/tool status view and check that Dreamtune tools are listed. Ask it:
> Use Dreamtune to read model request limits. Do not execute a model, tool or GPU.
Confirm model\_limits returns limits before authorizing paid work. Then inspect a
catalog schema and use one explicitly approved operation. Keep client approval
controls enabled. Never put the key in a chat message, URL or repository.
## Add workflow instructions
Install the [Dreamtune skills](/connect/skills-install) into the skills directory
supported by your client, or copy the platform skill into a user instruction
workflow. A skill guides the agent; MCP provides execution. Neither grants extra
key permissions. See [troubleshooting](/errors) for 401, missing scopes, timeouts
and key/environment problems.
Configuration verified against [the official client documentation](https://docs.roocode.com/features/mcp/using-mcp-in-roo).
# VS Code and GitHub Copilot
Source: https://docs.dreamtunelabs.com/agents/vscode
Connect VS Code and GitHub Copilot to Dreamtune MCP and install scoped workflow skills.
![VS Code and GitHub Copilot official logo]()
## Before you connect
Create a Dreamtune workspace API key with only the permissions you need.
Hosted HTTP setup needs no Dreamtune package installation. Local stdio setup
requires Node.js 22.20 or later and the published CLI.
## Configure
Merge this server entry into .vscode/mcp.json. Preserve any other servers or settings.
```json theme={null}
{
"servers": {
"dreamtune": {
"type": "http",
"url": "https://mcp.dreamtunelabs.com/mcp",
"headers": {
"X-Dreamtune-API-Key": "${input:dreamtune-key}"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "dreamtune-key",
"description": "Dreamtune API key",
"password": true
}
]
}
```
Use the protected input prompt when VS Code requests the key. The outer property is servers, not mcpServers. Use MCP: List Servers from the Command Palette and review the server trust prompt.
## Verify the connection
Restart the client after changing settings or its environment. Open its MCP
server/tool status view and check that Dreamtune tools are listed. Ask it:
> Use Dreamtune to read model request limits. Do not execute a model, tool or GPU.
Confirm model\_limits returns limits before authorizing paid work. Then inspect a
catalog schema and use one explicitly approved operation. Keep client approval
controls enabled. Never put the key in a chat message, URL or repository.
## Add workflow instructions
Install the [Dreamtune skills](/connect/skills-install) into the skills directory
supported by your client, or copy the platform skill into a user instruction
workflow. A skill guides the agent; MCP provides execution. Neither grants extra
key permissions. See [troubleshooting](/errors) for 401, missing scopes, timeouts
and key/environment problems.
Configuration verified against [the official client documentation](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).
# Windsurf / Cascade
Source: https://docs.dreamtunelabs.com/agents/windsurf
Connect Windsurf / Cascade to Dreamtune MCP and install scoped workflow skills.
![Windsurf / Cascade official logo]()
## Before you connect
Create a Dreamtune workspace API key with only the permissions you need.
Hosted HTTP setup needs no Dreamtune package installation. Local stdio setup
requires Node.js 22.20 or later and the published CLI.
## Configure
Merge this server entry into the file opened by Cascade's Open MCP config file action. Preserve any other servers or settings.
```json theme={null}
{
"mcpServers": {
"dreamtune": {
"command": "dreamtune",
"args": ["mcp"],
"env": {
"DREAMTUNE_API_KEY": "YOUR_DREAMTUNE_KEY",
"DREAMTUNE_API_ORIGIN": "https://dreamtune-api.fly.dev",
"DREAMTUNE_REQUEST_TIMEOUT_MS": "135000"
}
}
}
}
```
Install @dreamtune/sdk globally first. Replace YOUR\_DREAMTUNE\_KEY only in your private client settings. The current vendor documentation redirects to Devin Desktop; configuration paths vary by installed generation. Use the editor's config action instead of assuming an old path. This guide uses its documented local stdio format.
## Verify the connection
Restart the client after changing settings or its environment. Open its MCP
server/tool status view and check that Dreamtune tools are listed. Ask it:
> Use Dreamtune to read model request limits. Do not execute a model, tool or GPU.
Confirm model\_limits returns limits before authorizing paid work. Then inspect a
catalog schema and use one explicitly approved operation. Keep client approval
controls enabled. Never put the key in a chat message, URL or repository.
## Add workflow instructions
Install the [Dreamtune skills](/connect/skills-install) into the skills directory
supported by your client, or copy the platform skill into a user instruction
workflow. A skill guides the agent; MCP provides execution. Neither grants extra
key permissions. See [troubleshooting](/errors) for 401, missing scopes, timeouts
and key/environment problems.
Configuration verified against [the official client documentation](https://docs.devin.ai/desktop/cascade/mcp).
# Zed
Source: https://docs.dreamtunelabs.com/agents/zed
Connect Zed to Dreamtune MCP and install scoped workflow skills.
![Zed official logo]()
## Before you connect
Create a Dreamtune workspace API key with only the permissions you need.
Hosted HTTP setup needs no Dreamtune package installation. Local stdio setup
requires Node.js 22.20 or later and the published CLI.
## Configure
Merge this server entry into your private Zed settings. Preserve any other servers or settings.
```json theme={null}
{
"context_servers": {
"dreamtune": {
"url": "https://mcp.dreamtunelabs.com/mcp",
"headers": {
"X-Dreamtune-API-Key": "YOUR_DREAMTUNE_KEY"
}
}
}
}
```
Replace the key in private settings. Zed uses context\_servers rather than mcpServers. Open the Agent Panel's MCP controls to inspect availability; do not assume another editor's environment-variable interpolation works in Zed.
## Verify the connection
Restart the client after changing settings or its environment. Open its MCP
server/tool status view and check that Dreamtune tools are listed. Ask it:
> Use Dreamtune to read model request limits. Do not execute a model, tool or GPU.
Confirm model\_limits returns limits before authorizing paid work. Then inspect a
catalog schema and use one explicitly approved operation. Keep client approval
controls enabled. Never put the key in a chat message, URL or repository.
## Add workflow instructions
Install the [Dreamtune skills](/connect/skills-install) into the skills directory
supported by your client, or copy the platform skill into a user instruction
workflow. A skill guides the agent; MCP provides execution. Neither grants extra
key permissions. See [troubleshooting](/errors) for 401, missing scopes, timeouts
and key/environment problems.
Configuration verified against [the official client documentation](https://zed.dev/docs/ai/mcp).
# Compute API
Source: https://docs.dreamtunelabs.com/api/compute
Read GPU capacity, create workspace rentals, retrieve access and terminate paid machines.
Prefix: /v1/developer/compute-jobs. Reads need compute:read; creation and
termination need the corresponding compute execution access.
| Method | Path after prefix | Input | Purpose |
| - | - | - | - |
| GET | /catalog | None | Types, regions, specifications and hourly rates |
| POST | Empty | Creation JSON, Idempotency-Key | Launch one rental |
| GET | Empty | limit required, cursor optional | Paginated owned jobs |
| GET | / | Owned job ID | Reconcile status and usage |
| POST | //cancel | No request body | Stop and settle |
| GET | //notebook | Owned job ID | Private notebook URL |
## Catalog and launch
Read the live catalog rather than hardcoding GPU availability. Types contain
name, description, GPU, architecture, hourlyCents, regions and specs. Region
entries contain a name and description. specs describes vCPUs, memory, storage
and GPU count.
```json theme={null}
{
"instanceType": "YOUR_CATALOG_TYPE",
"region": "YOUR_CATALOG_REGION",
"publicKey": "YOUR_SSH_PUBLIC_KEY"
}
```
Supply a valid SSH public key, never a private key. Instance type is at most 100
letters/digits/underscores/hyphens; region is at most 60 lowercase letters,
digits/hyphens. publicKey is bounded to 4096 characters and accepts the supported
SSH key formats.
Persist the idempotency key before creation. Availability can change between
catalog inspection and launch. Do not launch a second machine to resolve an
ambiguous response.
## Pagination and state
List limit is 1–100. Pass nextCursor unchanged for the next page. The response
contains jobs, pageSize, total, hasMore and nextCursor; a final page has a null
nextCursor.
States include queued, registering\_key, key\_registered, launching,
needs\_reconciliation, running, terminating, terminated and failed. Read the
saved job to confirm its actual state. A local timeout does not terminate it.
Returned fields may include providerStatus, ip, activeAt, billingStoppedAt,
billedMinutes, terminationReason and receipt values. Billing metadata is
available only when the corresponding lifecycle event has occurred.
## Access and termination
Notebook URLs contain private access material; do not log or share them.
For SSH, use your corresponding private key and validate the host identity.
The hosted API cannot recover a lost private key. The CLI can prepare and store
local access before launch; see [GPU access](/guides/gpu-access).
Call cancel, then verify terminated status and final usage. Closing SSH,
ending an agent or revoking a local shell session is not a stop request.
There is no automatic persistent-volume service implied by included machine
disk. Copy required files before terminating the machine.
# API conventions
Source: https://docs.dreamtunelabs.com/api/conventions
HTTP status, idempotency, identifiers, pagination, money and operation states.
## Authentication and scopes
Send Authorization: Bearer on API requests. The hosted execution MCP instead
uses X-Dreamtune-API-Key. Neither key is a Clerk dashboard session. A session
label or end-user ID annotates an execution; it cannot select another tenant.
Use models:read/models:run, tools:read/tools:run and compute:read/compute:run
as selected in your key. Missing access fails explicitly.
## Creation and replay
Billable creation requires Idempotency-Key with 16–128 characters using ASCII
letters, numbers, underscores or hyphens. Persist it before submission.
Identical replay recovers the same operation. Changed input or attribution with
the same key conflicts. A fresh key means a new operation and possible charge.
A timeout leaves the execution outcome uncertain. Do not automatically repeat
paid execution with another key. Read the saved operation, then reconcile its
status. There is no automatic provider, model or credential substitution.
## HTTP versus execution state
| HTTP outcome | Interpretation |
| - | - |
| 200 | Read succeeded, or model submission returned a terminal result; inspect state |
| 201 | Prompt version created |
| 202 | Accepted/pending; feedback and tool submission also use this status |
| 400 | Invalid input |
| 401 / 403 | Invalid identity or insufficient access |
| 402 | Wallet or key spending restriction |
| 404 | Resource unavailable to this workspace |
| 409 | Conflicting replay or active-operation constraint |
| 429 | Rate limited |
| 5xx | Service/upstream failure; outcome may require reconciliation |
Do not treat an HTTP 200 containing state failed as successful generation.
See [errors](/errors) for recovery by symptom.
## Money and receipts
Currency is USD and scale is 6 for execution receipts. Amounts are decimal
integer strings, measured in millionths of a dollar. For example, "250000"
means USD 0.25. Use BigInt rather than floating-point arithmetic.
Final receipts can contain cost, discountAmount, fee and total. Use the recorded
receipt, including any discount, rather than recomputing from an advertised
price. Pending chargedAmount of zero is not proof that work is free.
Key category caps are cumulative optional limits. Blank means wallet-funded
execution, not unlimited free usage. Admission is checked before work; final
successful cost can cross the remaining allowance. See [billing](/billing).
## Identifiers and pagination
Model, tool and compute IDs use 64 lowercase hexadecimal characters. Treat
identifiers as opaque ownership-bound references, not credentials.
Pagination differs by endpoint: tool discovery uses an opaque cursor; compute
requires a limit and uses a job cursor; observability lists use page numbers,
while traces and captured content use cursors. Follow each returned next cursor
unchanged. Do not invent offsets or assume every list has the same envelope.
Dates use YYYY-MM-DD for trace filters; timestamps use the returned UTC time.
End-user and session labels must meet [context limits](/reference/environment).
# Model API
Source: https://docs.dreamtunelabs.com/api/models
Submit model conversations and function calls, recover requests and read usage receipts.
Prefix: /v1/developer/model-runs. Reads need models:read; creation needs
models:run and eligible wallet/key credit.
| Method | Path after prefix | Input | Result |
| - | - | - | - |
| GET | /limits | None | maxPromptChars, maxOutputTokens, configured feeBasisPoints |
| POST | Empty | JSON below, Idempotency-Key header | Saved run; 200 terminal or 202 pending |
| GET | Empty | None | Owned runs envelope |
| GET | / | Owned run ID | Saved/reconciled run |
## Create a conversation turn
```json theme={null}
{
"model": "YOUR_EXACT_MODEL_ID",
"messages": [
{ "role": "system", "content": "Answer concisely." },
{ "role": "user", "content": "Explain idempotency in one sentence." }
],
"maxOutputTokens": 300
}
```
```sh theme={null}
curl --fail-with-body \
"$DREAMTUNE_API_ORIGIN/v1/developer/model-runs" \
-H "Authorization: Bearer $DREAMTUNE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $DREAMTUNE_REQUEST_ID" \
--data-binary @request.json
```
The model must be an exact supported identifier, not a display name. Read limits
before choosing conversation/output bounds. Required maxOutputTokens must be a
positive integer within the deployment limit.
## Function calling
Optional fields are tools, tool\_choice and parallel\_tool\_calls. tools uses
function definitions with a name, description and JSON object parameters.
tool\_choice accepts auto, none, required or a named function selector.
Assistant messages may include content, tool\_calls and reasoning\_details.
Tool messages include tool\_call\_id and content. Return all results for the
preceding calls before continuing ordinary conversation; call identifiers and
function names must be consistent. The final input is a user message or a
completed set of tool results. See [the full flow](/guides/function-calling).
## Read the result
A run contains id, model, createdAt, state, currency and scale. Completed runs can
include text, message, finishReason, usage.promptTokens, usage.completionTokens
and final money fields. Missing upstream metrics must not be invented.
States include reserved, queued, submitting, received, completed, failed and
needs\_reconciliation. Pending work must be recovered through GET by saved ID.
A failed run can be returned successfully at the HTTP layer; inspect state and
error. Never infer that a free catalog listing guarantees available capacity.
Session, end-user and prompt attribution can be attached by the SDK/CLI context.
See [sessions](/guides/sessions) and [managed prompts](/guides/prompts).
# Observability API
Source: https://docs.dreamtunelabs.com/api/observability
Read scoped request stages, sessions, users, captured content, media, scores and feedback.
Prefix: /v1/developer/observability. Requests are scoped to the key's workspace.
End-user labels are attribution; they cannot expand ownership.
| Method | Path after prefix | Input | Purpose |
| - | - | - | - |
| GET | /traces | category, from, to; cursor?, requestId? | Paginated request stages |
| GET | /executions | page, sessionId?, accountId? | Conversation request list |
| GET | /sessions | page | Related sessions |
| GET | /users | page | Attributed account list |
| GET | /prompts | page | Prompt list |
| GET | /requests//content | cursor? | Captured stage input/output and media |
| GET | /requests//scores | None | Available evaluations |
| POST | /requests//feedback | value, comment | Explicit helpfulness feedback, HTTP 202 |
## Trace query
category must be model, tool, compute or all. from and to are UTC calendar dates
formatted YYYY-MM-DD. The interval is limited to 93 calendar days inclusive.
When requestId is supplied, category must be a specific category rather than
all. Request IDs use 64 lowercase hexadecimal characters. Cursors are opaque,
bounded values.
```sh theme={null}
curl --fail-with-body \
"$DREAMTUNE_API_ORIGIN/v1/developer/observability/traces?category=model&from=2026-10-01&to=2026-10-16" \
-H "Authorization: Bearer $DREAMTUNE_API_KEY"
```
The key needs read access to the selected category. category all requires all
three category read scopes. Follow returned pagination; one page is not a
complete export.
## Sessions and users
Page numbers are 1–9999. Use returned session/account identifiers for the
execution filters. A caller-supplied endUserId is not the same as a verified
platform account identity. See [sessions and attribution](/guides/sessions).
Sessions group captured executions; they do not automatically import customer
history that was never sent through Dreamtune. Only retained content is replayable.
## Captured content and media
The content response includes requestId, sessionId, data, media and nextCursor.
Stage data includes id, stage, startTime, input and output, with prompt name and
version when captured. Media entries include id, contentType, size, url and
expiresAt. Use the content cursor until all required pages have been read.
Signed media URLs expire. Refresh authorized content access instead of treating
a URL as permanent public storage. Historical traces may lack capture or media
that was not archived. See [media](/guides/media).
## Feedback and assessments
```json theme={null}
{
"value": 0,
"comment": "The answer cited a page that did not support its claim."
}
```
value is 0 or 1; comment is bounded to 500 characters. Feedback is one
account/request assessment, not an editable chat message. Repeating it does not
replace an existing assessment.
Your application must provide a feedback button or another explicit collection
flow. Langfuse does not know whether the user liked a response unless feedback
is submitted or a configured evaluator assesses it. Scores are judgments with
specific criteria; they are not proof of factual accuracy or agreement violation.
Some requests may have no assessment yet.
Prompt creation and selection are documented separately in [prompt API](/api/prompts).
# API overview
Source: https://docs.dreamtunelabs.com/api/overview
Production endpoint, authentication, request lifecycle and resource references.
## Connection
| Setting | Value |
| - | - |
| Base origin | [https://dreamtune-api.fly.dev](https://dreamtune-api.fly.dev) |
| Authentication | Authorization: Bearer YOUR\_DREAMTUNE\_API\_KEY |
| Request body | application/json |
| Creation replay | Idempotency-Key for billable model/tool/compute creation |
| Ownership | Active key's workspace |
Create a key from the [API keys dashboard](https://dreamtunelabs.com/dashboard/api-keys/).
Select only the required categories. Read scopes permit discovery/status; run
scopes permit execution. Keep the key outside browser bundles and source control.
## Resource map
| Resource | Prefix | Reference |
| - | - | - |
| Models | /v1/developer/model-runs | [Model API](/api/models) |
| Tools | /v1/developer/tool-runs | [Tool API](/api/tools) |
| Compute | /v1/developer/compute-jobs | [Compute API](/api/compute) |
| Observability | /v1/developer/observability | [Observability API](/api/observability) |
| Prompts | /v1/developer/observability/prompts | [Prompt API](/api/prompts) |
The API is not an OpenAI-compatible chat/completions endpoint. Use the documented
resource contracts or the published [SDK](/sdk). Model streaming and a managed
hosted agent runtime are not provided by these routes.
## First read-only request
```sh theme={null}
curl --fail-with-body \
"$DREAMTUNE_API_ORIGIN/v1/developer/model-runs/limits" \
-H "Authorization: Bearer $DREAMTUNE_API_KEY"
```
Set the origin explicitly to the production origin above. This reads limits
without creating a paid operation.
## Execution lifecycle
Read limits and schemas, save a unique request key, submit once, then inspect the
returned state. HTTP acceptance is not provider completion. Poll the saved
resource rather than submitting new work. Preserve its identifier for support,
billing and trace correlation.
See [conventions](/api/conventions), [errors](/errors) and
[recovery](/guides/reliability) before building retry logic.
# Prompt API
Source: https://docs.dreamtunelabs.com/api/prompts
Create versioned text or chat prompts, compile variables and placeholders, and manage deployment labels.
Prefix: /v1/developer/observability/prompts. Reading/compiling requires model
read access; creation/label changes require model execution access.
| Method | Path after prefix | Input | Purpose |
| - | - | - | - |
| GET | Empty | page | List owned prompts |
| POST | Empty | Prompt definition | Create a new version, HTTP 201 |
| GET | / | Exactly one query: version or label | Read selected definition |
| POST | //compile | Selector and inputs | Compile messages without a model call |
| PATCH | //labels | version and labels | Assign deployment labels |
URL-encode the entire prompt name when constructing its path.
## Create a chat prompt
```json theme={null}
{
"name": "support/answer",
"type": "chat",
"messages": [
{
"role": "system",
"content": "Answer for {{product}} using verified information."
},
{ "type": "placeholder", "name": "history" },
{ "role": "user", "content": "{{question}}" }
],
"labels": ["staging"],
"tags": ["support"],
"config": { "purpose": "customer-support" },
"commitMessage": "Initial support instructions"
}
```
A text prompt instead sets type text and text to a string. A chat definition
uses messages. Do not supply incompatible text and chat fields.
Creating again creates a version; it is not an idempotent operation. The response
identifies name and version. Read that version before promoting a label.
## Compile
```json theme={null}
{
"version": 1,
"variables": {
"product": "Dreamtune",
"question": "How do I recover a timed-out request?"
},
"placeholders": {
"history": [
{ "role": "user", "content": "I submitted a model request." },
{ "role": "assistant", "content": "Keep its saved request identifier." }
]
}
}
```
Use either version or label, never both. Supply required variables and message
placeholders explicitly. Missing or malformed inputs fail instead of silently
producing an incomplete conversation. Compilation is read-only and does not
spend model credits.
Definitions can compose supported same-workspace text dependencies. Keep names
and versions deliberate; cross-workspace prompt access is not supported.
See [prompt workflows](/guides/prompts) for linking a compiled prompt to execution.
## Promote an exact version
```json theme={null}
{ "version": 2, "labels": ["production"] }
```
A label selects one version. A request records the resolved exact version so a
later label move does not rewrite historical attribution. Review compilation
and output before moving a production label.
## Input limits
| Field | Limit |
| - | - |
| Name | 128 characters; slash-separated safe segments; no . or .. segments |
| Chat messages / placeholder messages | Up to 20 |
| Chat message content | 8000 characters each |
| Text prompt | 16000 characters |
| Variable value | String, up to 8000 characters |
| Variable/placeholder name | Letter/underscore first, then letters/digits/underscores; up to 64 |
| Labels/tags | Up to 20 unique values, each up to 64 safe characters |
| Commit message | 500 characters |
| Serialized definition / compile inputs | 16000 characters |
config is a JSON record. Prototype-sensitive names and unsupported fields are
rejected. Keep credentials out of templates, variables, tags and commit messages.
# Tool API
Source: https://docs.dreamtunelabs.com/api/tools
Discover and inspect catalog tools, execute their input envelopes and refresh saved jobs.
Prefix: /v1/developer/tool-runs. Reads need tools:read; execution needs
tools:run and eligible credit.
| Method | Path after prefix | Input | Purpose |
| - | - | - | - |
| GET | /tools | q?, cursor?, limit? | Catalog discovery |
| POST | /inspect | provider, endpoint | Read selected schema |
| POST | Empty | provider, endpoint, input; Idempotency-Key | Create run, HTTP 202 |
| GET | Empty | None | Recent runs and limit |
| GET | / | Owned run ID | Saved status/result |
| POST | //refresh | No request body | Refresh existing upstream job |
## Discovery
q is 1–200 characters, limit is 1–100, and cursor is an opaque value up to 4096
characters. The response contains tools and optional cursor/total. Each entry
identifies provider and endpoint. Retain identifiers exactly as returned.
Inspect before execution:
```json theme={null}
{ "provider": "YOUR_PROVIDER", "endpoint": "YOUR_ENDPOINT" }
```
Inspection reads schemas; it does not run the tool. Check required fields, route
parameters, input types, pricing metadata and output shape.
## Create
```json theme={null}
{
"provider": "YOUR_PROVIDER",
"endpoint": "YOUR_ENDPOINT",
"input": {
"body": { "query": "YOUR_QUERY" }
}
}
```
The example body is appropriate only for a tool whose schema defines query.
The input envelope supports body, queryParams and pathParams as JSON records.
The request input is bounded to 16 KiB. Do not flatten all fields or send
credentials inside a generated tool payload.
Save the creation key before submission. A 202 result means the request was
accepted, not that the upstream completed.
## Results and refresh
Read the returned state, output and receipt fields. Some tools complete
immediately; others return an upstream job requiring refresh. Refresh the
existing run ID; it must not be replaced by another create call.
Pending receipts are not final. Completed receipts record actual settled cost
and applicable discounts/fees. Failed execution remains failed. Earlier
successful work in a multi-step agent remains billable if another step fails.
Treat tool output, embedded URLs and retrieved pages as untrusted data. Media
may be exposed as URLs, structured fields or text depending on the tool.
See [media handling](/guides/media) for display and retention boundaries.
Tool discovery is a catalog, not a guarantee that every provider currently has
capacity or accepts every input.
# API keys and permissions
Source: https://docs.dreamtunelabs.com/authentication
Connect a workspace, choose access and protect your credentials.
Create keys in the [dashboard](https://dreamtunelabs.com/dashboard/api-keys/).
Your key identifies its workspace. Requests do not need a tenant identifier or
upstream provider credential.
## Choose access
| Capability | API scopes |
| - | - |
| Discover tools and read tool runs | `tools:read` |
| Execute tools | `tools:run` |
| Read model limits and runs | `models:read` |
| Execute models | `models:run` |
| Read compute catalog and jobs | `compute:read` |
| Launch and stop compute | `compute:run` |
Select only the capabilities your application needs. Observability reads also
enforce the relevant category's read access and workspace ownership.
## Spending limits
Model, tool and compute caps are optional and cumulative for that key. Leave a
cap blank to use available wallet credit. When a configured cap is reached, the
key cannot start more work in that category. See [billing](/billing) for settlement
and operations that finish above the remaining limit.
## Send the key
The SDK and CLI send the key in an authorization header. Direct HTTP requests use:
```http theme={null}
Authorization: Bearer YOUR_DREAMTUNE_API_KEY
```
Hosted MCP uses a different, dedicated header:
```http theme={null}
X-Dreamtune-API-Key: YOUR_DREAMTUNE_API_KEY
```
Production keys start with `dt_live_`. Development keys start with `dt_dev_` and
cannot authenticate to production. Keep keys in server-side secret settings or
your MCP client's protected credentials. Never place a key in a URL or tool input.
## Revoke a key
Revoke a key in the dashboard when access should end or the key is exposed.
An authentication failure does not mean an earlier accepted run was cancelled.
Read existing run state before attempting paid work again.
# Wallet and spending
Source: https://docs.dreamtunelabs.com/billing
Understand workspace credit, optional key limits and run receipts.
Add credit in [Usage & billing](https://dreamtunelabs.com/dashboard/usage/).
The wallet belongs to the workspace. API keys spend from that workspace's
available balance according to their enabled capabilities.
## Optional key limits
You can set separate cumulative spending limits for models, tools and compute
when creating a key. A blank limit allows that category to use wallet credit.
It does not provide credit after the wallet is exhausted.
New paid work requires a positive balance and remaining applicable key budget.
One billable operation can be active per workspace across these categories.
## Model and tool settlement
Successful operations settle using confirmed actual cost and the saved server
billing policy. A final receipt can include:
| Field | Meaning |
| - | - |
| `cost` | Recorded execution cost |
| `discountAmount` | Server-applied discount |
| `fee` | Recorded platform fee |
| `total` | Final charge |
| `chargedAmount` | Committed charge for the run |
Amounts are integer strings in USD millionths: `"1000000"` means USD 1.00.
For a final receipt, `cost - discountAmount + fee = total`.
Pending runs do not contain a final cost breakdown. Failed new model/tool runs
have a zero final charge.
An operation that completes successfully can cost more than the remaining key
budget or wallet balance. Its confirmed cost still settles, and further work is
blocked until the admission requirements are met. Key limits are not guaranteed
maximum prices for a single upstream operation.
## Compute
Compute charges recorded runtime at the selected rate and billing policy.
Stop a rental explicitly when finished and confirm termination. See
[compute](/compute) for the full workflow.
## Payment confirmation
The platform funding fee is charged when you add credit. There is no additional
platform usage markup on model, tool or compute calls. Check current checkout
and pricing for the active fee and offers; gateway/network fees may also apply.
See [payment steps and troubleshooting](/guides/payments).
A checkout return page is not itself proof that wallet credit was posted.
Check the dashboard's payment status and balance. Fund the owning workspace
before retrying a balance error.
# Terminal CLI
Source: https://docs.dreamtunelabs.com/cli
Discover services, run requests and read results from your terminal.
## Install and configure
```sh theme={null}
npm install --global @dreamtune/sdk
dreamtune --help
```
Configure `DREAMTUNE_API_KEY`, `DREAMTUNE_API_ORIGIN` and
`DREAMTUNE_REQUEST_TIMEOUT_MS` using the [quickstart](/quickstart). Help and skill
installation work without a key. API commands require those settings.
## Discover and read
```sh theme={null}
dreamtune tools list --q search
dreamtune models limits
dreamtune models runs
dreamtune compute catalog
dreamtune observability list --page 1
```
Use each command group's `--help` for its options:
```sh theme={null}
dreamtune tools --help
dreamtune models --help
dreamtune compute --help
dreamtune observability --help
```
## Submit a request
Tool and model commands read a JSON payload from a file. The idempotency key is a
separate argument. Persist it before submission and reuse it only for identical
input.
```sh theme={null}
dreamtune models run --file model-request.json --idempotency-key YOUR_PERSISTED_REQUEST_KEY
dreamtune models get YOUR_RUN_ID
```
See [models](/models) and [tools](/tools) for file contents. Execution may spend
wallet credit. Reading a returned run ID lets you recover its saved result.
## Command output
Successful API commands print JSON to stdout. Failures print redacted errors to
stderr and exit nonzero. Commands do not automatically choose another provider,
retry failed work or poll indefinitely.
`dreamtune research` and `dreamtune agent` run local workflows through MCP. Consult
their `--help` and the published SDK README before preparing their explicit model,
tool bindings, persisted request keys and operation budgets.
# GPU compute
Source: https://docs.dreamtunelabs.com/compute
Discover available GPUs, connect with SSH and stop a rental.
Use `compute:read` and `compute:run` access. GPU rentals consume wallet credit
while running. Disconnecting an SSH session does not stop the machine.
## Discover capacity
```sh theme={null}
dreamtune compute catalog
```
Select an available instance type and region from the returned catalog.
## Configure local access
Install OpenSSH. Set a private state directory outside your repository and the
SSH username required by the selected GPU image. For an Ubuntu image in PowerShell:
```powershell theme={null}
$env:DREAMTUNE_COMPUTE_STATE_DIRECTORY = "$env:USERPROFILE\.dreamtune\compute"
$env:DREAMTUNE_SSH_USER = "ubuntu"
```
The CLI saves local launch references and SSH keys in that directory. Only the
public key is sent to Dreamtune. Protect and retain the directory to reconnect.
## Start a rental
```sh theme={null}
dreamtune compute start --name my-gpu-job --type YOUR_CATALOG_TYPE --region YOUR_CATALOG_REGION
```
This starts paid compute. Choose a stable name for that intended rental.
Repeating identical named input reuses its saved launch reference; use a new name
only when you intend to rent another machine.
## Check, connect and stop
```sh theme={null}
dreamtune compute get YOUR_JOB_ID
dreamtune compute ssh YOUR_JOB_ID
dreamtune compute stop YOUR_JOB_ID
```
Wait until the job is running with an IP before connecting. Stop explicitly when
finished and inspect the job until termination is confirmed. Wallet credit and
key limits also constrain the rental; do not rely on closing your terminal.
## SDK and hosted MCP
`client.compute.createJob` takes `instanceType`, `region`, `publicKey` and
`idempotencyKey`. It accepts an SSH public key, never a private key.
For hosted MCP, use `dreamtune compute prepare` with name, type and region to
prepare access without renting. Send those public launch inputs through
`create_compute_job`. Afterward, `dreamtune compute ssh YOUR_JOB_ID --name my-gpu-job`
links the returned job to its local access state.
Local SDK access management is available through `LocalComputeClient` from
`@dreamtune/sdk/node`. See the package types for the explicit configuration.
# Documentation for agents
Source: https://docs.dreamtunelabs.com/connect/documentation-mcp
Copy pages, read Markdown and connect the documentation-search MCP.
The documentation is available to people and coding agents. Each page's
context menu offers **Copy page** and **View as Markdown**, plus supported
agent actions. Code blocks have their own copy controls.
## Two different MCP connections
| Connection | Purpose | Credentials |
| - | - | - |
| Documentation search | Read and search this documentation | Public documentation access |
| Dreamtune execution | Run authorized tools/models/compute and inspect workspace records | Your Dreamtune platform key |
Mintlify hosts documentation search at `https://docs.dreamtunelabs.com/mcp`.
This is a machine endpoint. JSON or a protocol error in a browser is not the
human guide. Use [execution MCP setup](/connect/mcp) when you want to run services.
For a client that accepts an unauthenticated remote server definition:
```json theme={null}
{
"mcpServers": {
"dreamtune-docs": {
"url": "https://docs.dreamtunelabs.com/mcp"
}
}
}
```
Add a transport type or use your client's outer configuration format as required.
For example, Claude Code requires `"type": "http"` on an HTTP definition.
The page menu's Cursor and VS Code actions connect documentation search.
They do not install a paid execution key.
## Read without MCP
* [Documentation index](https://docs.dreamtunelabs.com/llms.txt)
* [Full documentation text](https://docs.dreamtunelabs.com/llms-full.txt)
* [Quickstart as Markdown](/quickstart.md)
* [Downloadable skills](/connect/skills-install)
Append `.md` to a page URL for Markdown. A copied page is context, not permission
to execute its example. Your agent still needs your selected scopes, credentials
and spending authorization before running services.
# Local MCP setup
Source: https://docs.dreamtunelabs.com/connect/local-mcp
Run the published stdio server with explicit credentials, deadlines and optional GPU access.
Local MCP runs `dreamtune mcp` as a child of your agent client. It opens no HTTP
listener. Standard output carries the protocol; diagnostics go to standard error.
## Install and configure
Install Node.js 22.20 or later, then:
```sh theme={null}
npm install --global @dreamtune/sdk
dreamtune --version
dreamtune mcp --help
```
Set `DREAMTUNE_API_KEY`, `DREAMTUNE_API_ORIGIN` and
`DREAMTUNE_REQUEST_TIMEOUT_MS` for the process your client launches. Use the
production API origin `https://dreamtune-api.fly.dev` with a production key.
The generic stdio definition is:
```json theme={null}
{
"mcpServers": {
"dreamtune": {
"command": "dreamtune",
"args": ["mcp"],
"env": {
"DREAMTUNE_API_ORIGIN": "https://dreamtune-api.fly.dev",
"DREAMTUNE_API_KEY": "YOUR_DREAMTUNE_API_KEY",
"DREAMTUNE_REQUEST_TIMEOUT_MS": "60000"
}
}
}
}
```
Keep the actual key in a private client configuration or use the client's
documented secret substitution. Do not commit a substituted key. Some clients
use a different outer object or require an explicit transport type; follow
[your client's guide](/agents/overview).
## Verify without paid execution
```sh theme={null}
dreamtune mcp tools
```
List the definitions, then ask the client to discover catalog tools. Do not
launch compute or run a generator merely to check whether the server starts.
Use [MCP tool reference](/reference/mcp-tools) to identify read and write operations.
## Windows and desktop environments
A desktop agent may not inherit the PATH or variables from your terminal.
Restart it after changing its environment. If `dreamtune` cannot be resolved,
use the absolute Node executable and installed package's `dist/cli.js` path,
with `mcp` as the final argument. Obtain your installation location with
`npm root --global`; do not copy another machine's path.
Do not start the stdio server in an unrelated background terminal: the client
must manage its input/output connection. Do not insert ordinary logging on stdout.
## Optional local compute
Set `DREAMTUNE_COMPUTE_STATE_DIRECTORY` to an absolute private directory to enable
the local compute-access tools. An invalid supplied directory is an error.
Without that optional local capability, the API compute tools remain available
with their explicit public-key contract. See [GPU access](/guides/gpu-access).
# Connect MCP
Source: https://docs.dreamtunelabs.com/connect/mcp
Give your agent scoped access through hosted HTTP or local stdio MCP.
## Hosted connection
This is the human setup guide. The server address below is a machine endpoint:
opening it in a browser may return JSON or a protocol error. Add it in your
agent's MCP settings instead. For client-specific instructions, use the
[coding-agent directory](/agents/overview).
Use an MCP client that supports Streamable HTTP and custom request headers:
| Setting | Value |
| - | - |
| Transport | Streamable HTTP |
| Server URL | `https://mcp.dreamtunelabs.com/mcp` |
| Header name | `X-Dreamtune-API-Key` |
| Header value | Your production Dreamtune API key |
Save the key in your client's protected credential settings. Configuration syntax
varies by client. Hosted MCP uses your key directly; it does not provide browser
OAuth login. Choose local MCP if your client cannot supply the required header.
## Local connection
See [the complete local setup](/connect/local-mcp) for environment configuration,
Windows command resolution, startup checks and GPU key management.
Install the CLI:
```sh theme={null}
npm install --global @dreamtune/sdk
```
A client that accepts this stdio configuration can launch Dreamtune with:
```json theme={null}
{
"mcpServers": {
"dreamtune": {
"command": "dreamtune",
"args": ["mcp"]
}
}
}
```
Supply `DREAMTUNE_API_KEY`, `DREAMTUNE_API_ORIGIN` and
`DREAMTUNE_REQUEST_TIMEOUT_MS` to that process through your client's environment
settings. Environment inheritance differs between clients. The package also
provides the `dreamtune-mcp` executable.
## What the agent can do
The server exposes catalog discovery and inspection, tool runs, model runs,
compute jobs and observability operations. Your key's scopes and workspace
ownership are checked for each operation.
List the local tool definitions without executing a paid operation:
```sh theme={null}
dreamtune mcp tools
```
A model choosing a tool does not grant additional permissions. Only authorize
the operations and spending your task requires.
## GPU access
Hosted compute creation requires an explicit SSH public key. Use the CLI's
`compute prepare` workflow to prepare local access first. The hosted server cannot
save a private key on your computer. See [compute](/compute).
# Skills catalog
Source: https://docs.dreamtunelabs.com/connect/skills-catalog
Choose the Dreamtune workflow instructions your application or agent needs.
The five skills below ship with `@dreamtune/sdk` 0.1.1. You can install them
individually or [download the archive](https://raw.githubusercontent.com/CheetahAI/dreamtune-docs/main/downloads/dreamtune-skills.zip).
## Platform
[Open or copy SKILL.md](/downloads/skills/dreamtune-platform/SKILL.md)
`dreamtune-platform` explains interface selection, key/environment setup,
workspace boundaries, explicit model/tool choices, request replay and spending.
Install this first when an agent needs an overview of the platform.
## Tools
[Open or copy SKILL.md](/downloads/skills/dreamtune-tools/SKILL.md)
`dreamtune-tools` covers catalog discovery, inspection, request construction,
execution, refreshing saved runs and interpreting final charges. It requires
tool permissions and does not assume every connector uses the same input shape.
## Models
[Open or copy SKILL.md](/downloads/skills/dreamtune-models/SKILL.md)
`dreamtune-models` covers explicit model selection, configured limits, text and
function-calling conversations, returned assistant messages and safe replay.
It also describes the local model-directed agent workflow.
## Compute
[Open or copy SKILL.md](/downloads/skills/dreamtune-compute/SKILL.md)
`dreamtune-compute` covers availability, local SSH preparation, named launch
recovery, connection, notebook access, billing and explicit termination.
It treats private SSH keys and notebook links as sensitive.
## Observability
[Open or copy SKILL.md](/downloads/skills/dreamtune-observability/SKILL.md)
`dreamtune-observability` covers request stages, paginated conversations,
sessions, users, captured content, media and managed prompt versions.
Resource ownership and category read permissions remain required.
## Copy a skill
Use the native discovery index linked in [installation](/connect/skills-install)
to fetch individual Markdown skill files, or extract the ZIP. To install one
from the CLI:
```sh theme={null}
dreamtune skills install dreamtune-observability --directory YOUR_AGENT_SKILLS_DIRECTORY
```
Skills are instructions, not background daemons. They do not need a separate
Dreamtune backend, database or provider account on your machine.
# Install or download skills
Source: https://docs.dreamtunelabs.com/connect/skills-install
Add the published Dreamtune skills to your coding agent or copy them manually.
Skills teach an agent the supported workflows. They contain no credentials and
do not execute services simply because they are installed.
## Install from the published package
```sh theme={null}
npm install --global @dreamtune/sdk
dreamtune skills list
dreamtune skills install all --directory YOUR_AGENT_SKILLS_DIRECTORY
```
Replace the directory with the one your agent loads. Examples include a
project's `.agents/skills` for compatible clients, `.claude/skills` for Claude
Code, or the skills location documented by your editor. Your client's current
documentation determines its search paths; do not assume every editor uses the
same global folder.
Install a single capability when that is all you need:
```sh theme={null}
dreamtune skills install dreamtune-models --directory YOUR_AGENT_SKILLS_DIRECTORY
```
The installer refuses to overwrite an existing named skill. Review an existing
installation before replacing it. Restart or reload the agent's skills as its
documentation requires.
## Download an archive
[Download all five Dreamtune skills](https://raw.githubusercontent.com/CheetahAI/dreamtune-docs/main/downloads/dreamtune-skills.zip).
Extract each named directory into your agent's skills directory, preserving
`/SKILL.md`. The archive contains the published skill content and license.
For copy/paste installation, open the [skills catalog](/connect/skills-catalog),
choose a skill, and save its Markdown as `SKILL.md` inside a matching directory.
Do not paste a skill into a credential field or a JSON MCP configuration.
## Discover skills from the docs
Mintlify serves the root [skill.md](/skill.md) and native discovery endpoints:
```text theme={null}
https://docs.dreamtunelabs.com/.well-known/agent-skills/index.json
https://docs.dreamtunelabs.com/.well-known/skills/index.json
```
Clients supporting website skill discovery can use those endpoints. If multiple
skills are served, `/skill.md` can redirect to the discovery index. The package
installer and ZIP remain direct ways to obtain the same workflow instructions.
## Configure execution separately
Install [local or hosted MCP](/connect/mcp), or configure the [CLI](/cli).
A skill does not select an API key, add wallet credit or bypass approval prompts.
Ask your agent to discover tools first, and authorize paid execution explicitly.
# Errors and recovery
Source: https://docs.dreamtunelabs.com/errors
Handle authentication, spending limits, conflicts and interrupted requests.
The SDK throws `DreamtuneError` with a `status`. CLI failures exit nonzero and
print a redacted error. MCP tools report failures using `isError: true`.
| Status | Meaning | Next action |
| - | - | - |
| `0` | Transport failed or the request was interrupted | Inspect the existing run or recover with identical input and its saved idempotency key |
| `400` | Invalid input or configuration | Check the schema and explicit client settings |
| `401` | Invalid, expired or revoked key | Check the key and environment |
| `402` | Wallet or spending-limit admission failed | Check the owning wallet and applicable key cap |
| `403` | Missing scope or operation permission | Check the key's selected access |
| `404` | Resource unavailable in this workspace | Check the ID and workspace |
| `409` | Conflicting replay or active workspace operation | Inspect the existing operation and reuse its original input |
| `429` | Rate limit reached | Respect the service limit; avoid concurrent retries |
| `502` | Invalid upstream/API response | Inspect saved state before another paid submission |
| `503` | Required service unavailable | Check existing work before resubmitting |
## Persist before submission
Create and save a unique 16–128 character idempotency key for each intended
model, tool or compute operation before sending it. Keep the same key and input
when recovering an uncertain submission. Reusing a key for changed input is a
conflict; using a fresh key can start another paid operation.
## Timeouts
Aborting an HTTP request stops the client from waiting. It does not cancel an
accepted provider job or terminate a GPU. Retrieve the saved run, refresh a tool
receipt where appropriate, or stop compute explicitly.
## Unresolved execution
A run that needs reconciliation remains unresolved until its actual upstream
state can be verified. Do not treat an unresolved submission as a failed, free
operation or repeatedly submit replacements. Keep the saved request information
for investigation.
# Model function calling
Source: https://docs.dreamtunelabs.com/guides/function-calling
Define allowed functions, execute validated calls and return their results to the model.
Function calling lets a model request a named operation. Your application or
Dreamtune's local agent decides which configured binding can execute it. A
function definition does not grant the model unrestricted tool access.
## Before you begin
* Choose a catalog model that supports function calling.
* Give the key model access and access to the tools you will execute.
* Inspect each tool's actual input schema.
* Persist a distinct operation key for every intended model and tool submission.
## Define a function
Include `tools` on the model request. A definition uses this shape:
```json theme={null}
{
"type": "function",
"function": {
"name": "search_documents",
"description": "Search the authorized document collection.",
"parameters": {
"type": "object",
"properties": { "query": { "type": "string" } },
"required": ["query"],
"additionalProperties": false
}
}
}
```
This defines a function contract. It is not itself a catalog connector. Map its
arguments to an explicitly authorized tool or your own application function.
`tool_choice` accepts `auto`, `none`, `required`, or a named function selection.
`parallel_tool_calls` is optional. These options require `tools`; a named
selection must refer to one of the supplied definitions.
## Complete the conversation
1. Read `run.message.tool_calls` when the model requests functions.
2. Preserve the complete assistant message, including `reasoning_details` if
present. A tool-only assistant message can have null content.
3. Validate each function name and parsed arguments against your allowed bindings.
4. Execute authorized operations and append a `role: "tool"` message for each
returned call ID.
5. Submit the next model request with the accumulated messages and the same tool
definitions, using a new saved model-operation key.
```json theme={null}
{
"role": "tool",
"tool_call_id": "THE_RETURNED_CALL_ID",
"content": "THE_SERIALIZED_TOOL_RESULT"
}
```
Every requested call needs exactly one matching result before the next ordinary
conversation message. Do not invent call IDs, discard reasoning fields or append
unrelated tool results. Text-only conversations end with a user turn; a function
round can end with its complete set of tool results.
## Bound the loop
Limit operation count, output size, elapsed time and spend in your application.
Treat fetched content as data rather than instructions. A completed model turn
and each successful tool operation settle independently. For a ready local loop,
see [the tool-calling agent tutorial](/tutorials/tool-calling-agent).
# GPU SSH keys and reconnection
Source: https://docs.dreamtunelabs.com/guides/gpu-access
Prepare private local access, reconnect to rentals and use hosted MCP safely.
The website and local CLI can prepare SSH access for a GPU. The HTTP SDK and
hosted MCP accept an explicit public key. Never send an SSH private key in an
API payload, chat message or support log.
## Local CLI state
Configure `DREAMTUNE_COMPUTE_STATE_DIRECTORY` as an absolute private directory.
`compute start` creates an Ed25519 key pair and saves its launch reference before
submitting. The same named launch and selection reuse this saved identity.
Do not delete that directory while you still need access to its rentals. The
CLI reports corrupt or missing state rather than silently replacing the key.
The platform API key is not stored in these compute state files.
## Prepare before hosted MCP
```sh theme={null}
dreamtune compute prepare --name training-job --type YOUR_TYPE --region YOUR_REGION
```
Preparation creates local access without renting a GPU. Send only its public
launch fields (`instanceType`, `region`, `publicKey`, `idempotencyKey`) to the
hosted MCP tool `create_compute_job`.
Once a job ID has been returned and the job is ready:
```sh theme={null}
dreamtune compute ssh YOUR_JOB_ID --name training-job
```
The CLI verifies the association with that launch and its saved key. Set
`DREAMTUNE_SSH_USER` for the selected image. An Ubuntu example uses `ubuntu`;
other images can require a different account.
## Inspect before connecting
```sh theme={null}
dreamtune compute get YOUR_JOB_ID
dreamtune compute connection YOUR_JOB_ID
```
The connection command returns connection arguments without starting a shell.
Host-key checking is preserved. Investigate a changed-host warning before
accepting a new key; do not disable verification merely to make SSH connect.
Notebook URLs grant access to the machine. Retrieve them only when needed and
avoid storing them in public logs. Disconnecting SSH or closing a notebook does
not stop runtime billing.
## Finish a rental
```sh theme={null}
dreamtune compute stop YOUR_JOB_ID
dreamtune compute get YOUR_JOB_ID
```
Confirm a terminal job state. Preserve relevant output before stopping;
persistent storage is not provided by the current rental contract.
# Limits, budgets and concurrency
Source: https://docs.dreamtunelabs.com/guides/limits
Distinguish input limits, request deadlines, key spending caps and execution admission.
Different limits protect different parts of a request. Increasing a client
timeout does not increase provider capacity, model context or workspace credit.
| Limit | Where to find it | What it controls |
| - | - | - |
| Model prompt/output limits | `dreamtune models limits` | Accepted conversation and output size |
| Catalog pagination | Tool query and compute history contracts | Number of records per read |
| API key cap | API key settings | Admission after cumulative category spend |
| Wallet balance | Usage & billing | Workspace eligibility to start paid work |
| Client request deadline | `DREAMTUNE_REQUEST_TIMEOUT_MS` or AbortSignal | How long the client waits |
| Local agent operation budget | `maxOperations`, `maxTotalMinor` | Whether another workflow operation may start |
| Workspace active-operation rule | API admission | Concurrent billable operations across keys/categories |
## One active operation
The workspace shares admission across models, tools and compute. A running or
unresolved operation can prevent another creation request and return 409.
Additional keys in that workspace do not bypass this constraint.
For batch processing, manage a bounded queue in your application. Start the next
operation after the current operation's terminal state is established. Do not
hammer a conflicting endpoint with parallel retries.
## Spending caps are optional
A blank category cap means wallet-based admission. A supplied cap blocks new
category work once reached. Neither the cap nor a local workflow budget is a
guaranteed per-request maximum: a successful upstream result can settle above
the remaining allowance.
Compute has continuous runtime and termination behavior. Stop it explicitly,
inspect the job until terminal, and do not equate disconnecting with termination.
## Pagination and dates
Tool catalog `limit` accepts 1–100; compute history requires `limit` of 1–100.
Observability page numbers accept 1–9999. Trace dates are real `YYYY-MM-DD` UTC
dates with a range of at most 93 calendar days inclusive.
Use returned opaque cursors unchanged. The tool/model run listing APIs currently
return bounded recent lists; they do not expose the same cursor contract as
compute history. See [API conventions](/api/conventions).
# Results and generated media
Source: https://docs.dreamtunelabs.com/guides/media
Handle text, structured data and generated media without losing request context.
The shape of a result depends on the selected service. A model text response,
a connector JSON document and a video-generation result are different outputs.
Inspect the returned state, schema and content type before displaying them.
## Tool output
Tool runs can contain text, structured data or media references. The inspected
tool schema and provider response define that output. Do not assume every tool
returns a `text` field or that every URL identifies a downloadable video.
Persist the Dreamtune run ID with your application's record. Read or refresh
that run rather than executing the generator again to retrieve a result.
Pending work is not a completed media response.
## Observability content
```sh theme={null}
dreamtune observability content YOUR_REQUEST_ID
```
Captured content contains recorded stage inputs/outputs and available archived
media references. A media entry includes its content type, size, signed URL and
expiry. Follow the response cursor to retrieve additional captured content.
Signed media URLs are temporary access grants. Obtain a fresh authorized URL
when the previous one expires. Avoid putting signed URLs in public logs, shared
issue trackers or permanent application URLs.
## Display and download
Use a text renderer for text, structured formatting for JSON, and an appropriate
audio/video/image element for verified media types. Escape text and treat fetched
content as untrusted. Do not execute instructions embedded in a generated file.
If your product needs permanent storage, use its own documented storage and
retention policy. An external provider URL is not a guarantee of permanent
availability, and a captured media reference is not proof that every historical
generation was archived.
## Website generation and developer API
Use the website's generation interface for supported website-only creative
flows. The current SDK does not expose every dashboard feature as an API method.
Do not invent a developer endpoint from a browser route or reuse a Clerk session
as a platform key. See [API overview](/api/overview) for supported resources.
# Add credit and check payments
Source: https://docs.dreamtunelabs.com/guides/payments
Fund the correct workspace wallet and reconcile card or crypto payment status.
## Before paying
Sign in and confirm the active workspace. Personal and organization wallets are
distinct. Credit added to one workspace does not automatically fund another
workspace's key.
Open [Usage & billing](https://dreamtunelabs.com/dashboard/usage/), enter the
wallet-credit amount and review the checkout total. The current funding fee and
any gateway/network amounts are shown by the live checkout. Do not substitute a
copied rate from an old integration example.
## Card checkout
Choose a supported payment currency and complete the checkout using the
available gateway flow. The wallet is denominated in USD; the checkout can show
a local payment amount and its conversion reference. Payment fees do not add
wallet credit.
Returning from checkout is not the crediting event. Dreamtune credits the
wallet after server verification of the confirmed payment. Refresh the balance
and check the corresponding payment record.
## Crypto checkout
Select the intended coin and network carefully. Follow the checkout's exact
address, amount and expiry. Network confirmation and payment verification can
take time. Sending an unsupported asset or using a different network is not
equivalent to completing the requested payment.
Do not send a second payment merely because confirmation is pending.
Use the saved payment record and Check status.
## Payment history
[Payment history](https://dreamtunelabs.com/dashboard/payments/) lists card and
crypto top-ups, their payment/credit status, dates, amounts and available
actions. Use pagination to inspect older records.
Usage deductions are in Logs, not the top-up table. The wallet balance reflects
settled operations. A failed provider call and a failed top-up are different
events with different recovery paths.
## Troubleshoot missing credit
1. Confirm that you are viewing the workspace that initiated checkout.
2. Read the saved payment status and select Check status.
3. Distinguish pending gateway confirmation from a confirmed credit.
4. If confirmed payment still has no credit, contact support with the payment
reference and approximate UTC time. Never send card security codes, API keys
or private wallet keys.
Direct database edits and manually changed browser balances do not prove payment
verification. For execution spending rules, see [wallet and spending](/billing).
# Use Playground
Source: https://docs.dreamtunelabs.com/guides/playground
Find a supported model or tool, submit an authorized request and inspect text or generated media.
Playground is the dashboard interface for trying supported services with your
active workspace wallet. Sign in, select the intended workspace, and open
[Playground](https://dreamtunelabs.com/dashboard/playground/).
## Choose a service
Search by task, model or provider. Tools and Models are separate views with the
same workspace context. Catalog cards open the selected capability; a listing
does not guarantee upstream capacity or successful generation.
For a tool, read its description and generated input form. Required fields come
from the selected endpoint's schema. Model pages show supported modalities and
the provider's current rate. Do not send confidential data merely to inspect a
form or catalog entry.
## Submit and inspect
Complete required fields, review the selected service and submit once. Keep the
saved request ID. The Result panel shows progress, processing, failure or the
completed output. Refresh checks the saved job; it does not intentionally create
a second generation.
Text appears as readable output. Supported image results display inline; audio
and video results use players when the upstream supplies usable media.
Structured output can be expanded. Browser playback depends on the returned
content type, codec and URL access policy.
If a media tool returns a nested object or an inaccessible link, inspect the
structured result and recorded request before resubmitting. Some tools return
asynchronous jobs that need more time.
## Long-running work
Automatic refresh is bounded. Use Check result to resume checking the same saved
job after the automatic refresh window. Do not repeatedly click generation to
make the upstream finish faster: that can create distinct billable operations.
See Logs for completed/failed operations, Runs for aggregate usage, and
Conversations/Traces for captured content and request stages.
## Creative generation
Supported image/video services have schema-based forms and service-specific
options. Provide the required prompt, references and generation settings for the
selected service. Advanced options and presets depend on that capability.
Dashboard generation is authenticated through your signed-in workspace.
Do not assume a dashboard-only media operation has an equivalent published
SDK method. The [SDK reference](/reference/sdk) enumerates the exported methods.
## Keep outputs
Download required artifacts while you have authorized access. A provider URL may
expire. Captured observability media uses authorized expiring access, and does
not guarantee indefinite preservation of every historical output.
See [media retention boundaries](/guides/media).
# Ship your integration
Source: https://docs.dreamtunelabs.com/guides/production
Prepare credentials, request recovery, cost controls and observability for a production application.
## Separate environments
Use production keys with the production origin and development keys only with
their development environment. Set every required value explicitly.
Do not substitute a development endpoint or key when production fails.
Keep credentials in server-side secret settings. Frontend clients should call
your authenticated application server, which controls the allowed Dreamtune
operations. A browser bundle must not contain your workspace key.
## Define an operation boundary
Persist a unique request key before each intended paid operation. Save the
request input, returned Dreamtune identifier and final state in your application.
Do not create a new key for retries of the same uncertain submission.
Apply a deadline to waiting, while keeping a recovery path for accepted work.
Network failure is not proof of cancellation. Check saved status before deciding
whether another operation is necessary.
## Bound work and access
Select only required key categories and configure optional cumulative caps.
Limit output tokens, local agent rounds, retrieved source sizes and GPU lifetime.
A category cap is not a guaranteed hard price ceiling for one call.
One active billable operation per workspace can produce a conflict. Coordinate
your application's submissions instead of repeatedly retrying conflicts.
Do not run load tests against paid production endpoints without a separate,
explicitly bounded plan.
## Instrument the user journey
Choose stable application session and end-user labels that avoid unnecessary
personal information. Capture consent and retention obligations in your product.
Make feedback collection explicit rather than assuming an evaluator knows the
user's opinion.
Correlate your application operation with the Dreamtune request ID. Use
[observability](/observability) to distinguish admission, provider work,
settlement and delivery time. Missing metrics are unavailable, not zero.
## Release and recovery
Validate happy paths, bad input, missing scopes, revoked keys, isolated
workspaces, idempotent replay, pending/failed work and insufficient credit.
Verify text and media output in your actual user interface.
Monitor saved outcomes and wallet behavior after release. Have a human recovery
path for ambiguous paid work. Stop GPUs explicitly and verify termination.
Keep private notebook URLs and captured customer content out of public logs.
Review [security](/guides/security), [limits](/guides/limits) and
[reliability](/guides/reliability) before launch. These integration practices are
not a certification or uptime guarantee.
# Managed prompts and versions
Source: https://docs.dreamtunelabs.com/guides/prompts
Create, compile and label reusable chat or text prompts.
Managed prompts let you reuse a template while preserving the exact version
associated with a model request. Read access requires `models:read`; mutations
require `models:run` and applicable workspace permission.
## Create a chat prompt
```typescript theme={null}
const saved = await client.observability.createPrompt({
name: "support/answer",
type: "chat",
messages: [
{ role: "system", content: "Answer in {{language}}." },
{ role: "user", content: "{{question}}" },
],
labels: ["staging"],
tags: ["support"],
commitMessage: "Create the support answer template",
});
```
The result identifies the saved name and version. A new version preserves
version selection; changing a deployment label changes which version that label
selects for subsequent requests.
## Compile a selected version
```typescript theme={null}
const compiled = await client.observability.compilePrompt("support/answer", {
version: saved.version,
variables: {
language: "English",
question: "How do I read a saved run?",
},
});
console.log(compiled.messages);
```
Choose exactly one of `version` or `label`. Missing required template inputs
fail explicitly. Variables are strings. Message placeholders supply arrays of
system/user/assistant messages; they are not arbitrary raw objects.
## Promote with a label
```typescript theme={null}
await client.observability.labelPrompt("support/answer", {
version: saved.version,
labels: ["production"],
});
```
Read the selected prompt with `getPrompt(name, { label: "production" })`.
This label mutation assigns the supplied labels; inspect the result rather than
assuming an append-only operation.
## Link model observations
An SDK `observability.prompt` selection takes `name`, exactly one `version` or
`label`, and the required variables/placeholders. CLI/local MCP use
`DREAMTUNE_PROMPT_NAME`, one of `DREAMTUNE_PROMPT_VERSION` or
`DREAMTUNE_PROMPT_LABEL`, and optional JSON `DREAMTUNE_PROMPT_INPUTS`.
The resolved exact version is linked to the generation. Keep selection and
inputs unchanged when replaying an operation.
## Template and size rules
* Names are at most 128 characters, with slash-separated alphanumeric, underscore,
period or hyphen segments; `.` and `..` path segments are not accepted.
* Chat definitions contain 1–20 messages/placeholders; text definitions use `text`
and cannot also contain `messages`.
* String variables and message content are at most 8,000 characters. Template
inputs serialize to at most 16,000 characters.
* Labels and tags are unique arrays of at most 20 entries; label strings accept
letters, digits, underscores, periods and hyphens, up to 64 characters.
See [prompt API reference](/api/prompts) for the complete operation list.
# Request lifecycle and recovery
Source: https://docs.dreamtunelabs.com/guides/reliability
Recover safely from pending work, timeouts and uncertain submissions.
An HTTP response and a completed provider operation are different events.
A successful HTTP status can return a pending or failed run. Inspect the
returned `state` and retain the Dreamtune run or job ID.
## Before submitting
1. Validate the selected model, tool schema or compute capacity.
2. Save the exact payload and a unique idempotency key.
3. Check that the workspace has credit and the key has the required access.
4. Submit once and persist the returned record ID.
Idempotency keys accept 16–128 letters, digits, underscores or hyphens. A UUID
is a suitable saved identifier. Do not put secrets or personal information in it.
## Reuse a request safely
Replaying the same creation operation with the same key and identical input
recovers its existing record. Changing its input is a conflict. Giving the same
intended operation a new key can execute and charge it again.
SDK, CLI and MCP do not automatically switch providers, select another model or
blindly retry a paid creation call. Your application decides when another read
or an explicitly new operation is appropriate.
## When a request times out
A timeout means the client stopped waiting. It does not establish whether the
upstream accepted the work. Check the saved run; if no ID reached the client,
recover using the original creation key and identical input.
For tools, `refreshToolRun` checks the upstream receipt. For models, `getRun`
reads/reconciles the saved operation. For compute, inspect the existing job and
call stop when you want the rental to end. Cancelling an HTTP wait does not
terminate a machine.
## Reconciliation states
`needs_reconciliation` means acceptance, output or billing cannot yet be verified.
Do not convert it into success, assume a free failure or launch replacements.
The workspace can retain admission while potentially active work is unresolved.
Keep the run ID, saved key and non-secret timestamps for investigation.
## Workflow costs
Successful earlier operations remain billable if a later step fails. A local
agent's operation budget stops additional work after a settled result reaches
its allowance; one result can cross that amount. See [billing](/billing).
When implementing a polling loop, bound its duration and read frequency. Poll the
existing record rather than submitting new work. Handle terminal failure and
reconciliation explicitly instead of waiting indefinitely.
# Secure your integration
Source: https://docs.dreamtunelabs.com/guides/security
Protect workspace keys, restrict agent operations and handle captured content.
## Keep keys server-side
Store the platform key in your application's secret manager or your agent
client's protected credential settings. Do not place it in browser JavaScript,
public repositories, URLs, screenshots or tool arguments.
Use a dedicated named key per application, grant the required read/run categories
and set optional spending caps appropriate to the workload. Revoke exposed or
unused keys in the dashboard. Production and development keys are separate.
## Agent permissions
A skill teaches an agent a workflow; it does not grant authorization. MCP tool
annotations describe intended behavior, while the backend still checks scopes,
ownership, wallet admission and saved request state.
Keep your editor's approval prompts for paid or mutating operations. Do not
automatically approve every tool merely because a sample configuration supports
an allow-all setting. Explicitly bind model function names to approved tools.
## Untrusted results
Search pages, generated files and tool outputs can contain misleading content
or prompt injection. Treat them as task data. They must not change your agent's
credential access, spending authorization or workspace selection.
## Transport and local files
Use the HTTPS API and MCP origins. Local stdio requires a trusted executable and
an explicit environment. Do not disable certificate verification or SSH host-key
checks to bypass an error. Keep the compute state directory private.
## Captured conversations
Prompts, replies and generated artifacts can contain sensitive user information.
Apply your application's consent, disclosure and retention obligations before
submitting content. Use opaque end-user/session labels where possible and keep
signed media URLs private.
Workspace isolation is enforced by Dreamtune's resource checks. If your own app
serves multiple end users under one key, your app must still authorize which of
its users can view each result. An observability label is not an access token.
See the published [Privacy Policy](https://dreamtunelabs.com/privacy/) and
[Terms](https://dreamtunelabs.com/terms/) for the platform's applicable policies.
This guide does not promise an unlisted certification, SLA or enterprise SSO feature.
# Sessions and end users
Source: https://docs.dreamtunelabs.com/guides/sessions
Correlate conversation turns and inspect workspace-owned histories.
A session groups related requests. An end-user label attributes them inside your
workspace. Neither value changes authorization or grants access to another tenant.
## Choose identifiers
Use a stable session identifier for a conversation and a stable end-user identifier
for its participant. Start a new session for a distinct conversation. Prefer
opaque application IDs over email addresses or other personal information.
| Input | Accepted form |
| - | - |
| `sessionId` | 1–128 letters, digits, underscores or hyphens |
| `endUserId` | 1–128 letters, digits, underscores, periods, at signs or hyphens |
## Attach SDK context
```typescript theme={null}
const client = new DreamtuneClient({
apiKey,
baseUrl,
observability: {
sessionId: "conversation-42",
endUserId: "customer-17",
},
});
```
All operations submitted with this client carry the selected context. Create a
client with the appropriate context for each conversation boundary rather than
reusing one user's labels for unrelated users.
For CLI/local MCP, set `DREAMTUNE_SESSION_ID` and `DREAMTUNE_END_USER_ID` on the
process before submitting work. Hosted clients can supply the corresponding
context headers only where their configuration supports them.
## Retrieve history
```sh theme={null}
dreamtune observability sessions --page 1
dreamtune observability users --page 1
dreamtune observability list --session RETURNED_SESSION_ID --page 1
```
Use the opaque IDs returned by the listing APIs when filtering history. The
submitted label and the returned internal record ID are different interfaces.
Follow page/cursor fields until the needed history has been collected.
`content(requestId)` reads captured input/output and media references. It can
return only the data recorded under the selected capture/retention settings.
Missing content is not evidence that a request did not occur.
## Replays and isolation
Keep observability context unchanged when recovering an idempotent operation.
Conflicting context is rejected. All reads remain workspace-scoped and require
the category's applicable read permissions. Application user labels alone are
not a sufficient authorization boundary for your own end-user UI.
# Workspaces and project access
Source: https://docs.dreamtunelabs.com/guides/workspaces
Understand ownership, API keys, end-user attribution and shared execution limits.
A workspace owns its wallet, keys, requests, GPU jobs and observability records.
An API key identifies exactly one workspace. Your application supplies that key;
it does not select a workspace by adding a tenant ID to each request.
## Choose the owning workspace
Before creating a key or adding credit, check the workspace selected in the
dashboard. Credit in one workspace does not fund a key owned by another.
Production `dt_live_` and development `dt_dev_` credentials belong to their
respective environments and cannot be interchanged.
For organization workspaces, execution can also depend on current membership
and the operation permissions assigned to the member. Possessing an old session
does not bypass a changed membership or resource ownership check.
## Separate projects with named keys
Create one named key per application or project. Grant only the categories that
project uses and optionally attach cumulative category spending limits. This
makes project attribution clearer without creating a new wallet for every key.
Keys in the same workspace share its wallet and admission constraints. Creating
additional keys does not increase the number of simultaneously active billable
operations allowed by the workspace.
## End users and conversation sessions
`endUserId` and `sessionId` are application-provided observability labels. They
help correlate activity inside the key's workspace; they do not authenticate a
customer or change resource ownership. Use stable, non-sensitive identifiers.
For example, a support application can use one workspace key, a stable customer
label, and a distinct session label for each conversation. Keep the same session
label across its turns. See [sessions and users](/guides/sessions).
## Access failures
| Symptom | Check |
| - | - |
| An existing run returns 404 | The run ID and the workspace that owns the key |
| A request returns 403 | Category scopes and applicable organization permissions |
| A request returns 402 | Owning wallet credit and the category's key allowance |
| Another request returns 409 | An active operation or conflicting replay |
| A trace list is incomplete | Read scopes, date range, category and pagination |
Keep record IDs returned by the appropriate API. A provider's job ID, a Dreamtune
run ID and an observability request ID are not interchangeable.
# Build with Dreamtune
Source: https://docs.dreamtunelabs.com/index
One API key for models, tools, GPU compute and observability.
Connect your application or agent to Dreamtune with a workspace API key. Use the
TypeScript SDK, terminal CLI, or MCP connection to run supported operations and
inspect their progress and charges.
Create a key, install the SDK and discover tools.
Use the hosted MCP endpoint or a local stdio server.
Send model requests and connect function calls to tools you authorize.
Discover available machines, connect and stop a rental.
## Choose your connection
| You are building with | Use |
| - | - |
| The Dreamtune website | Your browser and dashboard |
| A Node.js application | [TypeScript SDK](/sdk) |
| A terminal | [Dreamtune CLI](/cli) |
| An MCP-compatible agent | [Hosted or local MCP](/connect/mcp) |
| An agent that loads skills | [Bundled skills](/skills) |
## Track the work
[Observability](/observability) connects requests to stages, sessions, captured
content and recorded usage. Access follows the workspace and scopes of your key.
[Billing](/billing) explains wallet credit, optional key limits and final receipts.
The SDK package is `@dreamtune/sdk`. Its local agent commands run on your own
computer; they do not create a hosted agent deployment. Use the documented
Dreamtune client methods rather than assuming OpenAI-compatible endpoints.
# Model requests
Source: https://docs.dreamtunelabs.com/models
Choose a model, submit a conversation and retrieve its saved result.
Choose an exact model ID from the [Models catalog](https://dreamtunelabs.com/models/).
Use a key with `models:read` and `models:run`, and a positive workspace wallet.
## Read limits
```sh theme={null}
dreamtune models limits
```
Keep prompt length and `maxOutputTokens` within the returned limits.
## Submit a conversation
Save this structure as `model-request.json`, replacing `provider/model-id` with
your selected catalog ID:
```json theme={null}
{
"model": "provider/model-id",
"messages": [
{ "role": "system", "content": "Answer clearly and concisely." },
{ "role": "user", "content": "Explain what an API key does." }
],
"maxOutputTokens": 256
}
```
Persist a unique 16–128 character idempotency key, then submit:
```sh theme={null}
dreamtune models run --file model-request.json --idempotency-key YOUR_PERSISTED_REQUEST_KEY
```
This can spend credit. A completed response includes its saved run ID, assistant
output and recorded usage. Pending states require checking the same run:
```sh theme={null}
dreamtune models get YOUR_RUN_ID
```
For the SDK, use `client.models.createRun` with the same payload plus
`idempotencyKey`. Use `client.models.getRun(id)` to read it.
## Function calling
Model requests accept function definitions in `tools`, with optional
`tool_choice` and `parallel_tool_calls`. When the model returns tool calls:
1. Preserve the returned assistant `message`, including tool calls and reasoning
details when present.
2. Execute only the tool bindings you authorized.
3. Append one `role: "tool"` result with the matching `tool_call_id` per call.
4. Send the next model turn with the same function definitions and a new persisted
operation key.
Calling a model does not automatically execute its requested tools. The CLI's
local `agent` command provides a separate model-directed MCP workflow.
## Recovery
Reuse the same idempotency key and identical input after an ambiguous submission.
Changing input with that key produces a conflict. A timeout does not prove the
provider stopped or that a successful result will be free. See [errors](/errors).
# Observability
Source: https://docs.dreamtunelabs.com/observability
Inspect request stages, conversation history, usage and prompt versions.
The dashboard and developer API expose observations for your workspace. Your
key's read scopes determine which model, tool and compute activity it can access.
An end-user identifier attaches context; it does not grant access to a workspace.
## Inspect requests
```sh theme={null}
dreamtune observability list --page 1
dreamtune observability sessions --page 1
dreamtune observability users --page 1
dreamtune observability content YOUR_REQUEST_ID
dreamtune observability scores YOUR_REQUEST_ID
```
Use the request ID returned by the observability listing for content and scores.
It is not interchangeable with every execution run or provider job identifier.
Content is paginated; media access uses expiring signed URLs.
## Trace stages
Save a query as `traces.json`:
```json theme={null}
{
"category": "model",
"from": "2026-10-01",
"to": "2026-10-16"
}
```
Choose your own UTC dates, up to 93 calendar days inclusive, then run:
```sh theme={null}
dreamtune observability traces --file traces.json
```
The response includes stage timing and available token/cost metrics. Use its
cursor to request subsequent pages. A missing measurement does not mean zero.
## Attach a conversation
For CLI and local MCP processes, set `DREAMTUNE_SESSION_ID` and optionally
`DREAMTUNE_END_USER_ID`. Use stable identifiers appropriate to your application.
SDK clients can attach the same context:
```typescript theme={null}
const client = new DreamtuneClient({
apiKey,
baseUrl,
observability: {
sessionId: "support-conversation-42",
endUserId: "customer-42",
},
});
```
Reusing a request key with conflicting context fails rather than changing the
original request's attribution. Session IDs accept letters, numbers, underscores
and hyphens, up to 128 characters.
## Prompts, feedback and assessments
`client.observability` supports creating, selecting, compiling and labeling managed
prompt versions. Templates accept string variables and message placeholders.
Select exactly one prompt version or deployment label when using a managed prompt.
```sh theme={null}
dreamtune observability prompts --page 1
dreamtune observability prompt-create --help
dreamtune observability feedback YOUR_REQUEST_ID --value 1 --comment "Helpful answer"
```
Scores may include a request assessment when that request has been evaluated.
These judgments support human review; they are not proof that an answer is
correct or that a user violated an agreement. Captured content depends on the
request and the platform's capture/retention settings.
# Quickstart
Source: https://docs.dreamtunelabs.com/quickstart
Create a workspace key and make your first read-only request.
## 1. Create a key
Sign in to [Dreamtune](https://dreamtunelabs.com/dashboard/) and open
[API keys](https://dreamtunelabs.com/dashboard/api-keys/). Select Tools access
for this guide and save the key when it appears.
For paid operations, add credit in
[Usage & billing](https://dreamtunelabs.com/dashboard/usage/). A key belongs to
the workspace that created it. See [authentication](/authentication).
## 2. Install
Use Node.js 22.20 or later. In your application:
```sh theme={null}
npm install @dreamtune/sdk
```
For terminal commands:
```sh theme={null}
npm install --global @dreamtune/sdk
```
## 3. Configure your connection
Supply your own production key through your application's secret settings.
The production API origin is `https://dreamtune-api.fly.dev`.
For a PowerShell terminal, set these process variables. Replace the example key:
```powershell theme={null}
$env:DREAMTUNE_API_ORIGIN = "https://dreamtune-api.fly.dev"
$env:DREAMTUNE_API_KEY = "YOUR_DREAMTUNE_API_KEY"
$env:DREAMTUNE_REQUEST_TIMEOUT_MS = "60000"
```
The timeout is your chosen request deadline in milliseconds. A deadline stops
waiting; accepted upstream work can continue. Keep credentials outside source
control and browser bundles.
## 4. Discover tools
```sh theme={null}
dreamtune tools list --q search
```
This lists matching tool identifiers. It does not execute a paid tool. Inspect a
selected tool's schema before running it; see [tools](/tools).
## Next steps
* [Use the SDK](/sdk) in a server-side application.
* [Connect MCP](/connect/mcp) to your agent.
* [Run a model](/models) with an explicit model choice.
* [Inspect requests and sessions](/observability).
# CLI command reference
Source: https://docs.dreamtunelabs.com/reference/cli
Commands, required arguments, request files and recovery for the Dreamtune CLI.
## Installation
```sh theme={null}
npm install --global @dreamtune/sdk
dreamtune --help
```
Configure the three required [environment variables](/reference/environment).
Commands print JSON. Save input files and idempotency keys. Use --help on each
command for your installed package's exact options.
## Tools
| Command after dreamtune | Input | Purpose |
| - | - | - |
| tools list | Optional --q, --cursor, --limit | Discover |
| tools inspect | --provider, --endpoint | Read schema |
| tools run | --file, --idempotency-key | Execute input envelope |
| tools runs | — | List recent runs |
| tools get | Run ID | Read saved run |
| tools refresh | Run ID | Refresh upstream status |
The run file contains provider, endpoint and input. input is the inspected body/queryParams/pathParams envelope.
## Models
| Command after dreamtune | Input | Purpose |
| - | - | - |
| models limits | — | Read request limits |
| models run | --file, --idempotency-key | Submit model/messages/maxOutputTokens and optional function settings |
| models runs | — | List runs |
| models get | Run ID | Recover state/output |
| models free-chat | --file | Separate development-only model/prompt API |
Use model runs in production. A timeout can follow successful execution; read
saved state before creating another request.
## Compute
| Command after dreamtune | Input | Purpose |
| - | - | - |
| compute catalog | — | Read availability |
| compute prepare | --name, --type, --region | Prepare SSH access without rental |
| compute start | --name, --type, --region | Start/resume named launch |
| compute jobs | --limit, optional --cursor | Paginated history |
| compute get | Job ID | Read status/usage |
| compute connection | Job ID, optional --name | Read SSH arguments |
| compute ssh | Job ID, optional --name, --command | Open SSH or run selected command |
| compute notebook | Job ID | Read private notebook URL |
| compute stop | Job ID | Terminate and settle |
Configure local state and SSH-user settings before local access. Closing the
terminal does not stop a rental. See [GPU access](/guides/gpu-access).
## Observability
| Command after dreamtune | Input |
| - | - |
| observability traces | --file with category/from/to and optional cursor/requestId |
| observability list | --page, optional --session, --account |
| observability sessions / users / prompts | --page |
| observability content | Request ID, optional --cursor |
| observability scores | Request ID |
| observability feedback | Request ID, --value 0 or 1, --comment |
| observability prompt-create | --file with definition |
| observability prompt-get | Name, --file with exact version or label |
| observability prompt-compile | Name, --file with selector/variables/placeholders |
| observability prompt-labels | Name, --file with version/labels |
Create-prompt makes a new version on each successful creation. Feedback is an
explicit application assessment, not automatically collected end-user feedback.
## MCP, skills and local workflows
```sh theme={null}
dreamtune mcp tools
dreamtune mcp call model_limits --file arguments.json
dreamtune skills list
dreamtune skills install all --directory ./agent-skills
dreamtune research --file research.json
dreamtune agent --file agent.json
```
Use in arguments.json for model\_limits. Bare dreamtune mcp starts stdio and
waits for protocol input; it is not an interactive chat.
See [research](/tutorials/research-agent), [tool agent](/tutorials/tool-calling-agent)
and [MCP tools](/reference/mcp-tools).
# Environment configuration
Source: https://docs.dreamtunelabs.com/reference/environment
Required and optional settings for the CLI, local MCP, observability and GPU access.
## Required for CLI and local MCP API operations
| Variable | Contract |
| - | - |
| `DREAMTUNE_API_KEY` | Your workspace key; production requires a production key |
| `DREAMTUNE_API_ORIGIN` | Explicit HTTPS origin without a path, query, fragment or embedded credentials; loopback HTTP is allowed for development |
| `DREAMTUNE_REQUEST_TIMEOUT_MS` | Positive integer milliseconds, at most 2147483647 |
Production uses `https://dreamtune-api.fly.dev`. These settings are read by the
process running the CLI/MCP server. A desktop client's environment can differ
from your shell. Missing or invalid required configuration fails explicitly.
The HTTP SDK instead takes `apiKey` and `baseUrl` in `DreamtuneClient` options.
Pass an `AbortSignal` for caller-managed deadlines.
## Local compute
| Variable | When required |
| - | - |
| `DREAMTUNE_COMPUTE_STATE_DIRECTORY` | Local prepare/start/connection workflows; absolute private directory |
| `DREAMTUNE_SSH_USER` | Connecting to the selected machine image over SSH |
The state directory stores launch references and SSH access, not the platform
key. Local MCP advertises its local access tools when that capability is
configured. Hosted MCP accepts public launch inputs and never writes a private
key onto the customer's computer.
## Observability context
| Variable | Meaning |
| - | - |
| `DREAMTUNE_SESSION_ID` | Application conversation label |
| `DREAMTUNE_END_USER_ID` | Application end-user label |
| `DREAMTUNE_PROMPT_NAME` | Managed prompt name |
| `DREAMTUNE_PROMPT_VERSION` | Exact managed prompt version; exclusive with label |
| `DREAMTUNE_PROMPT_LABEL` | Deployment label; exclusive with version |
| `DREAMTUNE_PROMPT_INPUTS` | JSON object containing optional `variables` and `placeholders` |
A prompt selection requires its name and exactly one version or label. Supply
the inputs required by its template. See [managed prompts](/guides/prompts).
## Secret handling
Keep actual keys out of committed JSON, shell history and URLs. Where supported,
use client-specific secret inputs or environment references. Do not copy one
editor's substitution syntax into another editor without checking its guide.
See [coding-agent setup](/agents/overview) for the different configuration shapes.
# MCP tool reference
Source: https://docs.dreamtunelabs.com/reference/mcp-tools
Tool names, arguments, effects and authorization for hosted and local Dreamtune MCP.
Connect through [hosted HTTP](/connect/mcp) or [local stdio](/connect/local-mcp).
Clients discover exact JSON schemas through tools/list. The local CLI prints
these definitions with dreamtune mcp tools. Clients may prefix tool names.
## Tools and models
| MCP tool | Arguments | Effect |
| - | - | - |
| list\_tools | q?, cursor?, limit? | Read catalog |
| inspect\_tool | provider, endpoint | Read schema |
| create\_run | provider, endpoint, input, idempotencyKey | Submit tool execution |
| list\_runs | None | Read tool runs |
| get\_run | id | Read saved run |
| refresh\_run | id | Refresh existing job |
| model\_limits | None | Read constraints |
| create\_model\_run | model, messages, maxOutputTokens, idempotencyKey; optional tools, tool\_choice, parallel\_tool\_calls | Submit model turn |
| list\_model\_runs | None | Read model runs |
| get\_model\_run | id | Recover result |
| free\_chat | model, prompt | Development-only text endpoint |
Read both MCP isError and the underlying operation state. A transported success
can describe a pending or failed operation. Never duplicate an uncertain paid
submission with a fresh idempotency key.
## Compute
| MCP tool | Arguments | Effect |
| - | - | - |
| compute\_catalog | None | Read capacity |
| create\_compute\_job | instanceType, region, publicKey, idempotencyKey | Start paid rental |
| list\_compute\_jobs | limit, cursor? | Read paginated jobs |
| get\_compute\_job | id | Reconcile usage/status |
| stop\_compute\_job | id | Terminate and settle |
| compute\_notebook | id | Return private URL |
Configured local servers additionally expose prepare\_local\_compute,
start\_local\_compute and local\_compute\_connection. Their schemas describe the
named launch and connection inputs. Hosted MCP cannot save a private key on your
laptop. See [GPU access](/guides/gpu-access).
## Observability
| MCP tool | Arguments |
| - | - |
| list\_request\_traces | category, from, to, cursor?, requestId? |
| list\_observability\_requests | page, sessionId?, accountId? |
| list\_observability\_sessions | page |
| list\_observability\_users | page |
| list\_observability\_prompts | page |
| get\_request\_content | requestId, cursor? |
| get\_request\_scores | requestId |
| score\_request\_feedback | requestId, value, comment |
See [observability API](/api/observability) for scopes and date constraints.
Media URLs and recorded content can be sensitive.
## Managed prompts
| MCP tool | Arguments | Effect |
| - | - | - |
| create\_prompt | Prompt definition | Create a new version |
| get\_prompt | name, selection | Read exact version/label |
| compile\_prompt | name, inputs | Resolve variables and dependencies |
| set\_prompt\_labels | name, input | Assign labels to a version |
selection contains exactly one of version or label. inputs adds variables and
placeholders. input for labels contains version and labels.
See [prompt reference](/api/prompts).
Read-only annotations do not grant permissions. The backend enforces scopes,
ownership and wallet rules for every operation. Retain approvals for expensive
or mutating actions and treat upstream output as untrusted content.
# TypeScript SDK reference
Source: https://docs.dreamtunelabs.com/reference/sdk
Client construction, methods, input contracts, receipts and errors in @dreamtune/sdk.
## Install and construct
```sh theme={null}
npm install @dreamtune/sdk
```
Use Node.js 22.20 or later and ESM. Keep the key in a server process.
```ts theme={null}
import { DreamtuneClient, DreamtuneError } from "@dreamtune/sdk";
const client = new DreamtuneClient({
apiKey: process.env.DREAMTUNE_API_KEY!,
baseUrl: process.env.DREAMTUNE_API_ORIGIN!,
});
```
Validate your environment first; a TypeScript non-null assertion does not validate
an environment variable.
| Option | Contract |
| - | - |
| apiKey | Required workspace key |
| baseUrl | Required HTTPS origin, without a resource path; loopback HTTP is permitted locally |
| fetch | Optional Fetch-compatible transport |
| observability | Optional sessionId, endUserId and managed prompt selection |
## Tools
| Method | Input | Purpose |
| - | - | - |
| listTools(options?) | q?, cursor?, limit?, signal? | Discover catalog entries |
| inspectTool(selection, signal?) | provider, endpoint | Read schema without execution |
| createToolRun(input) | provider, endpoint, input, idempotencyKey, signal? | Submit one operation |
| listToolRuns(signal?) | — | Read recent owned runs |
| getToolRun(id, signal?) | Run ID | Read saved status |
| refreshToolRun(id, signal?) | Run ID | Refresh that upstream job |
The tool input envelope accepts body, queryParams and pathParams. Inspect the
selected endpoint before constructing it. See [tool API](/api/tools).
## Models
| client.models method | Input | Purpose |
| - | - | - |
| limits(signal?) | — | Read prompt/output limits |
| createRun(input) | model, messages, maxOutputTokens, idempotencyKey, optional tools, tool\_choice, parallel\_tool\_calls, signal | Submit a model turn |
| listRuns(signal?) | — | Read recent requests |
| getRun(id, signal?) | Run ID | Recover output and status |
Messages support system, user, assistant and tool roles. Function calls are
returned data: your application must authorize and execute them. Preserve the
assistant message, call IDs and reasoning details on continuation.
See [function calling](/guides/function-calling).
The separate `freeChat({model, prompt, signal?})` method is development-only.
Use models.createRun in production, including for free models.
## Compute
| client.compute method | Input | Purpose |
| - | - | - |
| catalog(signal?) | — | Read types, rates and availability |
| createJob(input) | instanceType, region, publicKey, idempotencyKey, signal? | Launch a paid GPU |
| listJobs(options) | limit, cursor?, signal? | Read paginated jobs |
| getJob(id, signal?) | Job ID | Reconcile status/usage |
| stopJob(id, signal?) | Job ID | Stop and settle |
| notebook(id, signal?) | Job ID | Read private notebook URL |
LocalComputeClient is exported from @dreamtune/sdk/node. Its constructor takes
apiKey, baseUrl, stateDirectory and timeoutMs. Use prepare and start with
`{name, instanceType, region}`; connection takes id, sshUser, optional name and
signal. See [GPU access](/guides/gpu-access).
## Observability
| client.observability method | Arguments |
| - | - |
| traces | query, signal? |
| executions | page, sessionId?, signal?, accountId? |
| sessions / users / prompts | page, signal? |
| content | requestId, cursor?, signal? |
| scores | requestId, signal? |
| feedback | requestId, value (0 or 1), comment, signal? |
| createPrompt | definition, signal? |
| getPrompt | name, selection, signal? |
| compilePrompt | name, inputs, signal? |
| labelPrompt | name, version-and-labels object, signal? |
See [observability API](/api/observability) and [prompt API](/api/prompts).
## Cancellation and errors
Pass an AbortSignal to enforce your deadline. Aborting a request does not prove a
provider stopped or that a GPU terminated. Read the saved operation and stop
compute explicitly.
Catch DreamtuneError and inspect its status and message without
logging credentials or customer content. HTTP success can contain a failed or
pending operation. Check state before using output.
Amounts are integer strings; use BigInt and the returned scale. Pending zero
charges are not final receipts. See [conventions](/api/conventions).
# Versions and compatibility
Source: https://docs.dreamtunelabs.com/reference/versions
Published package requirements, supported interfaces and upgrade checks.
These docs describe the published `@dreamtune/sdk` 0.1.1 contract. The package
contains the TypeScript SDK, `dreamtune` CLI, local MCP executable and five
bundled skills. Hosted execution MCP is already deployed.
## Runtime
Use Node.js 22.20 or later. Local GPU access additionally requires OpenSSH.
The HTTP SDK is an ESM package; import it with standard ES module syntax.
```sh theme={null}
npm view @dreamtune/sdk version
dreamtune --version
```
The first command checks the published release; the second checks your installed
CLI. Use your application's lockfile to review and pin dependency changes.
Review the public types and release README before upgrading an integration.
## Package entry points
| Entry point | Purpose |
| - | - |
| `@dreamtune/sdk` | HTTP client and public operation types |
| `@dreamtune/sdk/node` | Local compute-access client |
| `@dreamtune/sdk/mcp` | MCP registration exports |
| `dreamtune` | CLI, local workflows and stdio MCP command |
| `dreamtune-mcp` | Direct stdio MCP executable |
## Scope of the interfaces
The current model API is non-streaming and uses Dreamtune's run contract.
An OpenAI-compatible chat endpoint and hosted managed-agent deployment are
not part of this package. Website checkout and key management remain dashboard
flows. The legacy free-chat interface is development-only.
Client configuration changes over time. Agent setup pages link to the official
client documentation checked for this publication. Matching the documented
configuration is distinct from installing and testing every editor locally.
Version 0.1.1 supports server-applied launch-discount receipts. Use that version
or later, and inspect saved run state before retrying an uncertain request.
# TypeScript SDK
Source: https://docs.dreamtunelabs.com/sdk
Connect a Node.js application with @dreamtune/sdk.
```sh theme={null}
npm install @dreamtune/sdk
```
Use Node.js 22.20 or later and keep your key server-side. The examples target the
published SDK contract in version 0.1.1.
## Create a client
```typescript theme={null}
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 your Dreamtune API key and origin.");
}
const client = new DreamtuneClient({ apiKey, baseUrl });
const catalog = await client.listTools({ q: "search", limit: 5 });
console.log(catalog);
```
Set the production origin to `https://dreamtune-api.fly.dev`. HTTPS is required
except for loopback development addresses.
## Available operations
| Feature | Methods |
| - | - |
| Tools | `listTools`, `inspectTool`, `createToolRun`, `listToolRuns`, `getToolRun`, `refreshToolRun` |
| Models | `models.limits`, `models.createRun`, `models.listRuns`, `models.getRun` |
| Compute | `compute.catalog`, `compute.createJob`, `compute.listJobs`, `compute.getJob`, `compute.stopJob`, `compute.notebook` |
| Observability | `observability.traces`, `executions`, `sessions`, `users`, `content`, `scores`, `feedback` |
| Managed prompts | `observability.prompts`, `createPrompt`, `getPrompt`, `compilePrompt`, `labelPrompt` |
The observability and prompt methods in this table are on
`client.observability`. Inputs and return types ship with the package.
## Deadlines and errors
Operations accept an optional `AbortSignal` as documented by their types. For a
read-only request:
```typescript theme={null}
const limits = await client.models.limits(AbortSignal.timeout(30000));
```
The SDK does not automatically retry paid requests or poll pending jobs. A
transport failure can happen after a request was accepted. Persist an idempotency
key before creation and reuse it with identical input to recover the original run.
Catch `DreamtuneError` and inspect its `status`. See [errors](/errors) and the
domain guides for recovery.
# Agent skills
Source: https://docs.dreamtunelabs.com/skills
Install Dreamtune instructions into an agent that loads skills.
Skills are instruction files that teach an agent how to use Dreamtune's CLI and
MCP operations. They do not contain API credentials or grant permissions.
## Install
```sh theme={null}
npm install --global @dreamtune/sdk
dreamtune skills list
dreamtune skills install all --directory YOUR_AGENT_SKILLS_DIRECTORY
```
Choose the actual directory your agent reads. Installation creates one named
directory per skill, each containing `SKILL.md`. It refuses to overwrite an
existing skill directory.
## Bundled skills
| Skill | Purpose |
| - | - |
| `dreamtune-platform` | Choose an interface and follow workspace and billing rules |
| `dreamtune-tools` | Discover, inspect and execute tools |
| `dreamtune-models` | Submit model requests and handle function calls |
| `dreamtune-compute` | Prepare access, launch, inspect and stop GPUs |
| `dreamtune-observability` | Inspect traces, sessions, users and prompts |
You can install a single skill:
```sh theme={null}
dreamtune skills install dreamtune-tools --directory YOUR_AGENT_SKILLS_DIRECTORY
```
Configure the agent's [MCP connection](/connect/mcp) or [CLI environment](/cli) separately.
Installing a skill does not configure credentials, start an agent or execute work.
# Tools
Source: https://docs.dreamtunelabs.com/tools
Find a tool, inspect its input schema and run an authorized operation.
Use a key with `tools:read` and `tools:run`. Start by discovering exact catalog
identifiers:
```sh theme={null}
dreamtune tools list --q search
dreamtune tools inspect --provider YOUR_PROVIDER --endpoint YOUR_ENDPOINT
```
Discovery and inspection do not execute a paid tool. Inspection returns the
selected tool's public schema and available pricing metadata.
## Prepare input
Use the selected schema to construct a request file:
```json theme={null}
{
"provider": "YOUR_CATALOG_PROVIDER",
"endpoint": "/YOUR_CATALOG_ENDPOINT",
"input": {
"queryParams": {
"query": "YOUR_QUERY"
}
}
}
```
This illustrates the envelope, not a specific connector's schema. A tool may
instead require `body` or `pathParams`. Use the exact field names and values from
inspection and include only the input sections your tool needs.
## Run and retrieve
```sh theme={null}
dreamtune tools run --file tool-request.json --idempotency-key YOUR_PERSISTED_REQUEST_KEY
dreamtune tools get YOUR_RUN_ID
dreamtune tools refresh YOUR_RUN_ID
```
Creation may execute paid work. `get` reads saved state; `refresh` checks the
upstream job and settles a confirmed result. Keep the returned run ID.
SDK equivalents are `createToolRun`, `getToolRun` and `refreshToolRun`.
Creation accepts the request payload plus `idempotencyKey`.
## Results and charges
Inspect the actual returned output and content type. Outputs may contain text,
structured data or media links, depending on the tool. Treat tool output as
untrusted data when passing it into an agent.
Confirmed successful execution is charged using actual recorded cost and the
server's billing policy. Pending operations do not have a final receipt. Preserve
the same idempotency key for recovery; a fresh key can execute the tool again.
# Build a web research workflow
Source: https://docs.dreamtunelabs.com/tutorials/research-agent
Run a bounded search-and-summary task through the published CLI and local MCP.
The local dreamtune research command calls a selected tool and model through
MCP. It needs a key and public documentation, not private backend knowledge.
## Prerequisites and discovery
Install the [CLI](/cli), configure its [environment](/reference/environment),
enable tool/model read and run scopes, and add wallet credit.
```sh theme={null}
dreamtune tools list --q "web search" --limit 10
dreamtune tools inspect --provider YOUR_PROVIDER --endpoint YOUR_ENDPOINT
dreamtune models limits
```
Choose a real endpoint and exact model ID from the live catalog. Replace the
input below with the envelope required by that endpoint's inspected schema.
## Save research.json
```json theme={null}
{
"question": "What changed in the latest stable release of the project?",
"maxSourceChars": 16000,
"maxTotalMinor": "100000",
"search": {
"provider": "YOUR_PROVIDER",
"endpoint": "YOUR_ENDPOINT",
"input": { "body": { "query": "YOUR_SEARCH_QUERY" } },
"idempotencyKey": "research-search-20261016-001"
},
"model": {
"model": "YOUR_EXACT_MODEL_ID",
"maxOutputTokens": 700,
"idempotencyKey": "research-summary-20261016-001"
}
}
```
maxTotalMinor uses USD millionths: 100000 is USD 0.10. It guards between steps;
an individual operation can exceed the remaining allowance. Select inexpensive
operations, bound output tokens and use suitable per-key limits.
## Execute and review
```sh theme={null}
dreamtune research --file research.json
```
The workflow checks model limits, inspects the tool, submits the search and reads
its result. Pending search work returns saved state rather than a fabricated
answer. Completed source material is passed to the model as untrusted content
for a cited summary, subject to the workflow's budget guard.
Read the returned stage and IDs. A later failure does not undo earlier billable
work. Review cited pages yourself; the output is not a guarantee of correctness.
## Recover safely
Keep the file and both keys unchanged. Read saved IDs with tools get and models
get. Reusing a key with changed input conflicts; using a new key creates new work.
For ongoing work, set session context and use [observability](/observability).
To allow multiple model/tool rounds, follow the [agent tutorial](/tutorials/tool-calling-agent).
# Build a function-calling agent
Source: https://docs.dreamtunelabs.com/tutorials/tool-calling-agent
Map approved function calls to catalog tools in a bounded local model/tool loop.
dreamtune agent runs a local model/tool loop through MCP. You explicitly map each
function to a catalog endpoint. A model cannot gain access by inventing a new
function name.
## Prepare
Configure the [CLI environment](/reference/environment), model/tool scopes and
wallet. Choose a model supporting function calls and inspect the tool schema.
The example is for a body-based search tool; adapt it to the endpoint you select.
## Save agent.json
```json theme={null}
{
"question": "Find official release notes and summarize the three main changes.",
"model": "YOUR_EXACT_MODEL_ID",
"maxOutputTokens": 800,
"maxOperations": 5,
"maxTotalMinor": "100000",
"maxToolOutputChars": 16000,
"idempotencyKey": "research-agent-20261016-001",
"tools": [
{
"definition": {
"type": "function",
"function": {
"name": "search_web",
"description": "Search public web pages.",
"parameters": {
"type": "object",
"properties": {
"body": {
"type": "object",
"properties": { "query": { "type": "string" } },
"required": ["query"],
"additionalProperties": false
}
},
"required": ["body"],
"additionalProperties": false
}
}
},
"provider": "YOUR_PROVIDER",
"endpoint": "YOUR_ENDPOINT"
}
]
}
```
## Run
```sh theme={null}
dreamtune agent --file agent.json
```
The runner submits a model turn, validates returned function arguments, executes
the mapped tool and returns a tool message with the matching call ID. It retains
assistant messages and provider reasoning details for continuation.
Operations run sequentially. Derived operation keys use the saved workflow key
and operation index. Preserve the root key and configuration during recovery.
## Interpret and bound execution
The response includes stage, totalMinor, trace and messages. Check stage for
completed, pending, failed or budget-stopped work. Earlier successful operations
remain billable if a later step fails.
maxOperations bounds the loop; maxToolOutputChars bounds source input.
maxTotalMinor checks between steps, so it is not a hard ceiling for the next
operation. Closing the process does not terminate a GPU.
Begin with one read-oriented tool. Check arguments, source citations and traces
before adding mutating endpoints. Never expose all tools or unrestricted shell
access to compensate for an unreliable prompt. For a custom implementation, see
[function calling](/guides/function-calling).