Developer docs

Developers

Engineering-focused reference for provisioning, runtime operations, model selection, API behavior, and observability surfaces.

Launch App

Quickstart

1. Get access: create a workspace and collect runtime credentials.
2. Choose model mode: use Tomato model by default, or bring your own provider key.
3. Launch runtime: provision a private managed OpenClaw-first environment.
4. Call API: send a message payload and handle standard failure paths.

API Reference

Endpoint: POST https://api.tomatolabs.org/api/chat

Request

{
  "message": "..."
}

Response

{
  "text": "..."
}

Error handling notes

Timeouts: retry with bounded backoff and idempotent user message handling.
Non-200 responses: surface HTTP status and provider-specific response body if available.
Missing text: treat as partial failure and return a safe fallback message.

Architecture

TomatoAI is a layered system: provisioning, runtime, and model. Runtime bootstrap and routing are managed; workload instructions and operational policy remain user-defined.

System topology

Provisioning Layer

Private workspace + isolation boundary

Agent Runtime Layer

OpenClaw-first managed runtime

LLM Layer

Tomato model + BYO provider

Runtime bootstrap

Tomato provisions environment metadata, installs runtime dependencies, and initializes execution services required for agent tasks.

Environment isolation

Each deployment is scoped to a private workspace boundary. Runtime resources are separated by deployment context.

Model selection flow

Select Tomato model or BYO provider at configuration time. Route choices can reflect latency, capability, and cost constraints.

Operational ownership split

Users define goals, prompts, policies, and keys. Tomato manages runtime lifecycle, deployment, and infrastructure maintenance.

Area	User responsibility	Tomato manages
Configuration	Prompting, policy logic, provider selection	Runtime templates, deployment controls
Operations	Task-level monitoring and workflow tuning	Infrastructure updates and runtime maintenance
Model access	Own key lifecycle when BYO mode is selected	Tomato model availability and routing hooks

Security & Isolation

Each deployment runs in a private environment boundary rather than a shared runtime context.
Store provider tokens and API keys in runtime secrets, never in frontend source code.
Rotate credentials regularly and scope keys to the minimum required permissions.
This website and playground UI do not persist chat history by default; data persistence depends on the configured backend endpoint.

Observability

A production deployment should expose logs, metrics, and traces per runtime. The component below is a placeholder interface that can later connect to real providers.

Placeholder interface

Logs

[runtime] bootstrap started

[agent] tool call: success

[router] model route: tomato-1

Metrics

P95 latency

Token usage

Error rate by deployment

Traces

Provisioning -> bootstrap

Prompt -> tool -> response

Runtime events timeline

Glossary

Runtime: Managed execution environment where agent tasks run.
Workspace: Scoped deployment unit with private runtime boundaries.
Provisioning: Automated setup of infrastructure, runtime, and base services.
Routing: Selection logic for model/provider execution paths.
Guardrails: Policy constraints around tool use, prompts, and allowed actions.
Observability: Visibility into runtime behavior via logs, metrics, and traces.