Agent: Tools

The agent exposes a built-in tool catalogue and a per-session effective tool list. You can inspect schemas, list the tools a live session actually has on PATH (including its MCP subset), and run tools either inside a live session (gated, claims the serial turn slot) or sessionless (gated, read-only by default). Sessionless runs ship in three forms: synchronous (run), async (runAsync — returns a job id you poll), and streamed (stream — SSE envelopes).

Catalogue

GET /api/v1/agent/tools

List the full tool catalogue. Returns each tool’s name, description, JSON-Schema input, and read_only flag. Catalogue-wide and realm-independent — a per-request realm header is rejected with realm_scope_unsupported.

Parameters

Name	In	Type	Required	Description
`page`	query	integer	No	1-based page number for pagination.
`limit`	query	integer	No	Maximum items per page (0 = no pagination).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector (`"global"` or a 24-hex id). Rejected on this route.
`realm`	query	string	No	Realm selector (in:query alias of `X-Hoody-Realm`). Rejected on this route.

Responses

{
  "items": [
    {
      "name": "bash",
      "description": "Run a shell command in the session's working directory.",
      "input_schema": {
        "type": "object",
        "properties": {
          "command": { "type": "string" },
          "timeout_ms": { "type": "integer" }
        },
        "required": ["command"]
      },
      "read_only": false
    },
    {
      "name": "read_file",
      "description": "Read a UTF-8 text file from the workspace.",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" }
        },
        "required": ["path"]
      },
      "read_only": true
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20
  }
}

{
  "code": "realm_scope_unsupported",
  "message": "realm scope not supported on this route"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

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

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

{
  "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.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "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.

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/tools?page=1&limit=20" \
  -H "Authorization: Bearer $HOODY_TOKEN"

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.tools.listToolsIterator({ page: 1, limit: 20 });

GET /api/v1/agent/tools/{name}

Get the schema for a single built-in tool by name. Returns the tool’s full descriptor — the body is the forwarded daemon reply (free-form). 404 tool_not_found for an unknown name.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Realm selector (in:query alias). Rejected on this route.

Responses

{
  "name": "bash",
  "description": "Run a shell command in the session's working directory.",
  "input_schema": {
    "type": "object",
    "properties": {
      "command": { "type": "string" },
      "timeout_ms": { "type": "integer" }
    },
    "required": ["command"]
  },
  "read_only": false
}

{
  "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.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

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

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

{
  "code": "tool_not_found",
  "message": "no tool with that name"
}

Error Code	Title	Description	Resolution
`tool_not_found`	Tool not found	No tool with the given name exists in the catalogue or in the session’s effective tool list.	List the catalogue (`GET /tools`) or the session’s tools (`GET /sessions/{id}/tools`) and use a valid name.

{
  "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.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "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.

SDK usage

cURL
TypeScript SDK

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/tools/bash" \
  -H "Authorization: Bearer $HOODY_TOKEN"

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.tools.getTool('bash');

GET /api/v1/agent/tools/read-only

List the read-only tool subset — tools safe for planning and sessionless runs. Same envelope and pagination as the full catalogue.

Parameters

Name	In	Type	Required	Description
`page`	query	integer	No	1-based page number for pagination.
`limit`	query	integer	No	Maximum items per page (0 = no pagination).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Realm selector (in:query alias). Rejected on this route.

Responses

{
  "items": [
    {
      "name": "read_file",
      "description": "Read a UTF-8 text file from the workspace.",
      "input_schema": {
        "type": "object",
        "properties": { "path": { "type": "string" } },
        "required": ["path"]
      },
      "read_only": true
    },
    {
      "name": "list_dir",
      "description": "List a directory.",
      "input_schema": {
        "type": "object",
        "properties": { "path": { "type": "string" } },
        "required": ["path"]
      },
      "read_only": true
    }
  ],
  "meta": {
    "total": 11,
    "page": 1,
    "limit": 20
  }
}

{
  "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.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

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

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

{
  "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.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "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.

SDK usage

cURL
TypeScript SDK

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/tools/read-only" \
  -H "Authorization: Bearer $HOODY_TOKEN"

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.tools.listReadOnlyToolsIterator();

Session Tools

These endpoints return the effective tool list for a live session — the subset of the catalogue that is both enabled in config and on the session’s compute PATH, gated by the session’s tool mode, agent allowlist, and headless exclusions. Both return 404 when the session is not live.

GET /api/v1/agent/sessions/{id}/tools

List a session’s effective tool set.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Session identifier.
`page`	query	integer	No	1-based page number for pagination.
`limit`	query	integer	No	Maximum items per page (0 = no pagination).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Realm selector (in:query alias). Rejected on this route.

Responses

{
  "items": [
    {
      "name": "bash",
      "description": "Run a shell command in the session's working directory.",
      "input_schema": {
        "type": "object",
        "properties": {
          "command": { "type": "string" },
          "timeout_ms": { "type": "integer" }
        },
        "required": ["command"]
      },
      "read_only": false
    },
    {
      "name": "read_file",
      "description": "Read a UTF-8 text file from the workspace.",
      "input_schema": {
        "type": "object",
        "properties": { "path": { "type": "string" } },
        "required": ["path"]
      },
      "read_only": true
    }
  ],
  "meta": {
    "total": 28,
    "page": 1,
    "limit": 20
  }
}

{
  "code": "realm_scope_unsupported",
  "message": "realm scope not supported on this route"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only RPC.	Omit the realm header on this route, or open a session to scope by realm.

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

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

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "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.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "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.

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

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK usage

cURL
TypeScript SDK

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/{id}/tools" \
  -H "Authorization: Bearer $HOODY_TOKEN"

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.tools.listSessionToolsIterator('{id}');

GET /api/v1/agent/sessions/{id}/tools/mcp

List a session’s MCP tools (mcp__*). Same envelope and semantics as the effective tool list, but filtered to the MCP subset of the session’s compute PATH snapshot.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Session identifier.
`page`	query	integer	No	1-based page number for pagination.
`limit`	query	integer	No	Maximum items per page (0 = no pagination).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Realm selector (in:query alias). Rejected on this route.

Responses

{
  "items": [
    {
      "name": "mcp__github__create_issue",
      "description": "Open a new issue on a GitHub repo.",
      "input_schema": {
        "type": "object",
        "properties": {
          "repo": { "type": "string" },
          "title": { "type": "string" },
          "body": { "type": "string" }
        },
        "required": ["repo", "title"]
      },
      "read_only": false
    },
    {
      "name": "mcp__github__list_issues",
      "description": "List open issues on a GitHub repo.",
      "input_schema": {
        "type": "object",
        "properties": {
          "repo": { "type": "string" },
          "state": { "type": "string", "enum": ["open", "closed", "all"] }
        },
        "required": ["repo"]
      },
      "read_only": true
    }
  ],
  "meta": {
    "total": 6,
    "page": 1,
    "limit": 20
  }
}

{
  "code": "realm_scope_unsupported",
  "message": "realm scope not supported on this route"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only RPC.	Omit the realm header on this route, or open a session to scope by realm.

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

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

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "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.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "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.

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

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK usage

cURL
TypeScript SDK

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/{id}/tools/mcp" \
  -H "Authorization: Bearer $HOODY_TOKEN"

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.tools.listSessionMCPToolsIterator('{id}');

Running Tools

Sessionless runs

Sessionless runs create an ephemeral local session from the scope headers (X-Hoody-Cwd, X-Hoody-Config-Dir) and run the full permission checks. They are read-only by default — a mutating tool requires allow_mutations: true or confirm: true, otherwise the run is refused with tool_mutation_refused. A parked confirmation returns 409 tool_needs_confirmation with the echoed tool+params; re-issue with confirm: true (and the confirm_token returned in the 409 details).

A sessionless run resolves paths under the caller-supplied X-Hoody-Cwd subtree (dir-scope defaults to home, restricted to cwd).

Session run

A session-scoped run claims the session’s single serial turn slot — it never races the turn loop. Concurrent activity returns 409 turn_in_flight or 409 gate_parked. A parked confirmation returns 409 tool_needs_confirmation.

POST /api/v1/agent/tools/{name}/run

Run a tool sessionless, gated. Returns the tool result directly.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Tool name.
`confirm`	query	boolean	No	Query alias of the body `confirm` field — re-issue a previously-parked confirmation.
`confirm_token`	query	string	No	Query alias of the body `confirm_token` field — the single-use token returned in the 409 details.
`X-Hoody-Tool-Mode`	header	string	No	Sessionless tool-mode for the ephemeral session (e.g. `read_only`, `full`).
`X-Hoody-Dir-Scope`	header	string	No	Sessionless directory-access scope (`home` or `full`); default `home`.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Realm selector (in:query alias). Rejected on this route.

Request Body

Name	Type	Required	Description
`params`	object	No	The tool’s input parameters (its JSON-Schema body).
`confirm`	boolean	No	Re-issue a previously-parked confirmation. MUST be paired with a valid `confirm_token`.
`confirm_token`	string	No	The single-use token returned in the 409 `tool_needs_confirmation` details.
`allow_mutations`	boolean	No	Sessionless only: opt a non-read-only tool into running under the full permission checks.

{
  "params": {
    "command": "ls -la",
    "timeout_ms": 5000
  }
}

Responses

{
  "stdout": "total 12\ndrwxr-xr-x  3 user user 4096 May  1 12:00 .\ndrwxr-xr-x  6 user user 4096 May  1 12:00 ..\n-rw-r--r--  1 user user  220 May  1 12:00 README.md",
  "stderr": "",
  "exit_code": 0
}

{
  "code": "tool_mutation_refused",
  "message": "sessionless run refused for a non-read-only tool"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`tool_mutation_refused`	Tool mutation refused	A sessionless run resolved to a mutating tool with no confirmation posture. Sessionless runs are read-only by default.	Open a session and run the tool there, or supply `allow_mutations: true` / `confirm: true` on the sessionless run.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

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

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

{
  "code": "tool_not_found",
  "message": "no tool with that name"
}

Error Code	Title	Description	Resolution
`tool_not_found`	Tool not found	No tool with the given name exists in the catalogue.	List the catalogue (`GET /tools`) and use a valid name.

{
  "code": "tool_needs_confirmation",
  "message": "tool requires confirmation before execution"
}

Error Code	Title	Description	Resolution
`tool_needs_confirmation`	Tool needs confirmation	The tool was NOT executed: the permission checks requires confirmation first.	Re-issue the run with `confirm: true` (or `?confirm=true`), preserving the echoed params.

{
  "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`).	Reduce the request body below the limit (default 8 MiB); split a large payload into smaller requests.

{
  "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.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "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.

SDK usage

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/tools/bash/run" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -d '{
    "params": {
      "command": "ls -la",
      "timeout_ms": 5000
    }
  }'

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.tools.runTool('bash', {
  params: {
    command: 'ls -la',
    timeout_ms: 5000
  }
}, { // X-Hoody-Cwd option omitted for brevity
});

POST /api/v1/agent/tools/{name}/runAsync

Async form of runTool. Returns {job_id} immediately; the gated tool runs in the background. Poll GET /jobs/{id}/result for the result, a parked confirmation, or an execution error.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Tool name.
`confirm`	query	boolean	No	Query alias of the body `confirm` field.
`confirm_token`	query	string	No	Query alias of the body `confirm_token` field.
`X-Hoody-Tool-Mode`	header	string	No	Sessionless tool-mode for the ephemeral session.
`X-Hoody-Dir-Scope`	header	string	No	Sessionless directory-access scope.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Realm selector (in:query alias). Rejected on this route.

Request Body

Name	Type	Required	Description
`params`	object	No	The tool’s input parameters.
`confirm`	boolean	No	Re-issue a previously-parked confirmation.
`confirm_token`	string	No	The single-use token returned in the 409 details.
`allow_mutations`	boolean	No	Sessionless only: opt a non-read-only tool into running under the full permission checks.

{
  "params": {
    "command": "npm test",
    "timeout_ms": 120000
  }
}

Responses

{
  "job_id": "job_67e89abc123def456789abcd"
}

{
  "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.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a global-no-realm RPC.	Omit the realm header on this route.

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

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

{
  "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.	Reduce the request body below the limit (default 8 MiB).

{
  "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.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "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.

SDK usage

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/tools/bash/runAsync" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -d '{
    "params": {
      "command": "npm test",
      "timeout_ms": 120000
    }
  }'

import { HoodyClient } from 'hoody-sdk';

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

// Kick off the async run
const { job_id } = await client.agent.tools.runToolAsync('bash', {
  params: {
    command: 'npm test',
    timeout_ms: 120000
  }
});

// Later: poll the job result
const result = await client.agent.jobs.getJobResult({ id: job_id });

POST /api/v1/agent/tools/{name}/stream

Stream a tool run over Server-Sent Events. Frame sequence: a start frame, then a single result / needs_confirmation / error frame, then end. The gated work is a one-shot RPC, so there is no per-token stream — the SSE shape mirrors the kit streaming convention for symmetry with the session stream.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Tool name.
`confirm`	query	boolean	No	Query alias of the body `confirm` field.
`confirm_token`	query	string	No	Query alias of the body `confirm_token` field.
`X-Hoody-Tool-Mode`	header	string	No	Sessionless tool-mode for the ephemeral session.
`X-Hoody-Dir-Scope`	header	string	No	Sessionless directory-access scope.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Realm selector (in:query alias). Rejected on this route.

Request Body

Name	Type	Required	Description
`params`	object	No	The tool’s input parameters.
`confirm`	boolean	No	Re-issue a previously-parked confirmation.
`confirm_token`	string	No	The single-use token returned in the 409 details.
`allow_mutations`	boolean	No	Sessionless only: opt a non-read-only tool into running.

{
  "params": {
    "command": "tail -f /var/log/app.log",
    "timeout_ms": 30000
  }
}

Responses

event: start
data: {"id":"job_67e89abc123def456789abcd"}

event: result
data: {"stdout":"INFO listening on :3000\n","stderr":"","exit_code":0}

event: end
data: {}

{
  "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.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to a global-no-realm RPC.	Omit the realm header on this route.

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

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

{
  "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.	Reduce the request body below the limit (default 8 MiB).

{
  "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.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "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.

{
  "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.

SDK usage

cURL
TypeScript SDK

curl -N -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/tools/bash/stream" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -d '{
    "params": {
      "command": "tail -f /var/log/app.log",
      "timeout_ms": 30000
    }
  }'

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.tools.streamTool('bash', {
  params: {
    command: 'tail -f /var/log/app.log',
    timeout_ms: 30000
  }
});

POST /api/v1/agent/sessions/{id}/tools/{name}/run

Run a named tool inside a live session, gated and constrained to the session’s frozen realm/container/cwd/tool-mode/dir-scope. Claims the session’s single serial turn slot, so a direct tool run never races the turn loop. The run is also cancellable (concurrent POST /sessions/{id}/cancel, a WS cancel frame, or session close aborts an in-flight run).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Session identifier.
`name`	path	string	Yes	Tool name.
`confirm`	query	boolean	No	Query alias of the body `confirm` field.
`confirm_token`	query	string	No	Query alias of the body `confirm_token` field.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	Realm selector (in:query alias). Rejected on this route.

Request Body

Name	Type	Required	Description
`params`	object	No	The tool’s input parameters (its JSON-Schema body).
`confirm`	boolean	No	Re-issue a previously-parked confirmation.
`confirm_token`	string	No	The single-use token returned in the 409 details.
`allow_mutations`	boolean	No	Sessionless only: opt a non-read-only tool into running. Omitted for in-session runs.

{
  "params": {
    "command": "git status",
    "timeout_ms": 5000
  }
}

Responses

{
  "stdout": "On branch main\nnothing to commit, working tree clean",
  "stderr": "",
  "exit_code": 0
}

{
  "code": "realm_scope_unsupported",
  "message": "realm scope not supported on this route"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only RPC.	Omit the realm header on this route.

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

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

{
  "code": "tool_not_found",
  "message": "no tool with that name"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.
`tool_not_found`	Tool not found	The tool is not in the session’s effective tool list.	List the session’s tools (`GET /sessions/{id}/tools`) and use a valid name.

{
  "code": "tool_needs_confirmation",
  "message": "tool requires confirmation before execution"
}

Error Code	Title	Description	Resolution
`tool_needs_confirmation`	Tool needs confirmation	The tool was NOT executed: the permission checks requires confirmation first.	Re-issue the run with `confirm: true` (or `?confirm=true`), preserving the echoed params.
`turn_in_flight`	Turn in flight	A turn is already running on this session; the single serial turn slot is occupied.	Wait for the running turn to finish (observe `agent_done` on the session stream), then retry.
`gate_parked`	Gate parked	A confirm/question gate is parked on this session, so a new turn/workflow run is refused until it is answered.	Answer the parked gate (`/confirm` or `/answer`) and retry; read it via `GET /sessions/{id}` or `details.pending_gate`.

{
  "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.	Reduce the request body below the limit (default 8 MiB).

{
  "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.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "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.

SDK usage

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/{id}/tools/bash/run" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "command": "git status",
      "timeout_ms": 5000
    }
  }'

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.tools.runSessionTool('{id}', 'bash', {
  params: {
    command: 'git status',
    timeout_ms: 5000
  }
});