Agent: Headless

Submit a one-shot prompt to the agent in an ephemeral, gateway-owned session and poll for the captured result. The default json/text form returns an async job that you poll through the gateway job endpoints; the stream-json form (or stream: true) returns the run live over SSE. Use this endpoint when you want the agent to drive the full loop once against a fresh session without maintaining interactive state.

Danger

Security risk. Reaching this surface grants arbitrary code execution on the bound container. Write-permission is hard-wired OFF and directory scope is home (no caller opt-in over this surface), but bash and exec are NOT write-gated, and every confirm/plan/question auto-approves. Treat the access token as an RCE credential.

Note

Daemon-failure delivery. The initial HTTP exchange returns only the pre-dispatch statuses (400, 403, 413, 429, 503, 500) plus the 200 SSE or 202 job acknowledgement. The daemon run starts AFTER the response, so a server-side failure cannot return 404 or 504 on this operation. In the async form the failure completes the job and surfaces via GET /jobs/{job_id}/result as { "status": "failed", "error": ... }. In the streaming form the failure arrives as the error SSE frame.

Create a headless run

POST /api/v1/agent/headless/runs

Drives the full agent loop once over an ephemeral, gateway-owned session. Set format: "stream-json" (or stream: true) to stream the run over SSE; otherwise the run is accepted as an async job and the gateway returns a job_id that you poll for the captured Result.

Parameters

Name	In	Type	Required	Description
X-Hoody-Cwd	header	string	No	Per-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-Dir	header	string	No	Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-Realm	header	string	No	Per-request realm selector: "global" or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realm	query	string	No	Per-request realm selector — the query-string alias of the X-Hoody-Realm header (read only when the header is absent): "global" or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Request Body

Field	Type	Required	Description
prompt	string	Yes	The prompt to drive the ephemeral session.
workflow	string	No	Optional workflow name to run instead of, or alongside, the prompt.
model	string	No	Optional model spec for the run.
format	string	No	Output rendering: text | json | stream-json. stream-json (or stream: true) streams the run over SSE; otherwise the run is an async job.
stream	boolean	No	Force SSE streaming (equivalent to format: "stream-json").
timeout_ms	integer	No	Optional run timeout in milliseconds (clamped to the hard ceiling).

Example request:

{
  "prompt": "Refactor the auth middleware to use dependency injection",
  "workflow": "code-review",
  "model": "claude-sonnet-4.5",
  "format": "json",
  "stream": false,
  "timeout_ms": 120000
}

Response

200 (SSE stream)

Returned when the request opts into streaming (format: "stream-json" or stream: true). The body is a Server-Sent Events stream with content type text/event-stream. Frames progress start -> result/error -> end; a server-side daemon failure is delivered as the error frame.

event: start
data: {"run_id":"run_01HXY8N4R7K2M9P3QD5VCE6T8B"}

event: result
data: {"status":"ok","output":"Refactor complete. Files updated: src/middleware/auth.ts"}

event: end
data: {}

202 (Async job)

Returned when the request is accepted as an async job (default text/json). The run executes after this acknowledgement; its outcome — including any server-side daemon failure — is delivered via GET /jobs/{job_id}/result, not as an HTTP status on this operation.

{
  "job_id": "01HXY8N4R7K2M9P3QD5VCE6T8B"
}

400

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
bad_request	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.

403

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
forbidden	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy (e.g. hoody agent … -> platform -> proxy), not by connecting to the container directly.

413

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
payload_too_large	Payload too large	The request body exceeds the configured size cap (MaxBodyBytes). The gateway rejects an oversized body at the edge (http.MaxBytesReader) before the handler reads it — a well-formed-but-large body is a size violation, not a JSON syntax error.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

429

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
rate_limited	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the Retry-After header and retry; reduce the request rate.

500

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
internal_error	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

503

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
service_unavailable	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor Retry-After and retry.

Example

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/headless/runs?realm=global" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Hoody-Cwd: /workspace/api" \
  -d '{
    "prompt": "Refactor the auth middleware to use dependency injection",
    "workflow": "code-review",
    "model": "claude-sonnet-4.5",
    "format": "json",
    "timeout_ms": 120000
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.headless.createHeadlessRun(
  {
    prompt: 'Refactor the auth middleware to use dependency injection',
    workflow: 'code-review',
    model: 'claude-sonnet-4.5',
    format: 'json',
    timeout_ms: 120000,
  },
  { realm: 'global' }
);