Configuration

stead.json is public, committable configuration. It contains no project credential or provider key. Unknown top-level fields are rejected.

Field	Type and behavior
apiUrl	Optional API URL; hosted value is https://api.getstead.dev. Overridden by STEAD_API_URL.
projectId	Optional UUID identifying the selected project for developer-session commands. Written by projects create/use.
dashboardUrl	Optional trace-view base URL for CLI output. Overridden by STEAD_DASHBOARD_URL.
bundle	Required path to a built JavaScript ESM file, relative to this config.
migrationsDir	Optional directory of numbered .sql files, relative to this config.
agents	Array of { name, config }; defaults to [].
exposures	Array of { table, columns, operations, isolation? }; defaults to [].

The generated starter is a complete configuration. This smaller one is also deployable, with a matching handlers.mjs:

{
  "apiUrl": "https://api.getstead.dev",
  "bundle": "handlers.mjs",
  "agents": [
    {
      "name": "echo-agent",
      "config": {
        "tools": { "echo": { "effect": "read" } },
        "endUserRuns": {
          "steps": [{ "tool": "echo", "input": "$input" }],
          "limits": { "runsPerHour": 30 }
        }
      }
    }
  ]
}

handlers.mjs

export async function echo(input) {
  return { text: String(input ?? '') };
}

Select the project with getstead projects use before deploying with a developer session. This example demonstrates a read-only tool and requires no model key for its tool execution. The quickstart adds model calls, SQL, approvals, and conversations.

Agent config

config is a JSON object. Two recognized fields control the public run behavior:

• tools: a map from exported handler names to { source?, effect?, requiresApproval? }. Source defaults to internal; effect defaults to write. Set read-only tools explicitly.
• endUserRuns: opt-in to customer starts. Without it, customers cannot start the agent.

endUserRuns accepts:

Field	Rules
steps	Required array, 1–100 tool/model steps.
budget	Optional { tokens?, usd? }. Positive integer token cap; USD at least 0.000001.
limits	Required { runsPerHour, usdPerDay? }. Hourly count 1–100000; daily USD requires budget.usd.
conversations	Optional { perHour, context: { maxMessages, maxTokens } }, all fields required. Creation 1–100000/hour; context 1–1000 messages and 1–1000000 approximate tokens.

Hosted request and runtime limits can be lower than a schema’s maximum accepted value. In particular, do not use a large maxTokens value as a way to bypass the model gateway’s output ceiling. See limits.

Step types

Tool step: { tool, name?, input? }. The optional name labels the completed result; otherwise the tool name identifies it.

Model step: { name, model: { model, messages, contextSteps?, maxTokens?, temperature? } }. messages is a nonempty array of { role, content }; role is system, user, or assistant. Model steps require a name. contextSteps contains 1–20 names, each identifying exactly one earlier step. See models.

Customer input replaces string values that are exactly "$input" in tool input or model message content. Other strings remain literal. Customers cannot change step definitions, budgets, or tool postures in their start request.

Agent/tool/step/conversation-key names must be nonempty, at most 200 characters, and contain no control characters. Use simple stable names such as support-agent, orders, and support-main.

Exposures and migrations

An exposure’s columns and operations are nonempty arrays. Operations are select, insert, update, and delete. Isolation is end_user by default, or project for deliberately shared project data. There is no public schema override. Exposure checks and the required SQL pattern are in SQL and data access.

The HTTP deployment contains base64 bundle, agents, exposures, and migrations: [{ name, sql }]. The CLI builds it from the local files; the path fields and project selector are not sent as deployment content.

Installation environment variables configure Stead’s own server, not a hosted customer’s stead.json. Hosted developers do not need database URLs, Fly credentials, signing keys, or the installation operator token.