Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Agent: Discovery

Section titled “Agent: Discovery”

The agent’s shell, file and search tools act on containers through the agent’s own sign-in to a Hoody account. A newly created container’s agent has none, so those tools answer “not logged in” until the agent signs in. This page covers the operations that sign the agent in to a Hoody account, switch its active realm, and list the realms and containers a session can bind to.

Begin with the sign-in operations in this order:

  1. GET /api/v1/agent/hoody/auth/status to check whether the agent already holds an active credential (auth_active: true means it is).
  2. POST /api/v1/agent/hoody/auth/bootstrap to install a credential from a platform token if none is active, or replace one owned by the same account.
  3. PUT /api/v1/agent/hoody/realm to choose the realm the agent will work in.

Then use the discovery operations:

  1. GET /api/v1/agent/realms to list the realms visible to that login.
  2. GET /api/v1/agent/containers to list the containers in a realm.

Sign-in

Section titled “Sign-in”

GET /api/v1/agent/hoody/auth/status

Section titled “GET /api/v1/agent/hoody/auth/status”

Reports which Hoody account the agent is logged in as and which realm it is scoped to, without opening a session. The reply is secret-free: no token, no email, no expiry.

auth_active: true means a platform credential is active; auth_active: false means none is (every local session is visible). owner_fingerprint is the session-ownership view: every session this agent creates reports it as started.owner_fingerprint, and sessions are readable only while the same account is active. restricted and realm_ids describe a realm-limited login (see restriction, restriction_reason). realm is the scope session listing and by-id reads use: the agent’s pinned realm when it has one, otherwise its active realm selection (an empty id means no realm is selected).

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

POST /api/v1/agent/hoody/auth/bootstrap

Section titled “POST /api/v1/agent/hoody/auth/bootstrap”

Installs the Hoody platform credential from a raw token. This is the programmatic equivalent of an interactive login.

The submitted token must meet every requirement below, or it is refused:

  • Belong to the same account as the container’s owner (the token is checked against this container on one of the token’s realms, or on the account for an all-realms token).
  • Be created from a signed-in session, not from another token. A session login (the account’s JWT) is not an API token and is refused the same way.
  • Carry the full login grant: vault access, the container, project and resource permissions the agent uses, and permission to create tokens.
  • Have at least 15 minutes of life left.
  • Not belong to a platform administrator.

A refusal names what the token lacks: login_not_for_this_box (the token cannot see this container), login_grant_insufficient (with details.missing listing what it lacks), login_expiring, admin_login_refused, or token_rejected (invalid or expired). The token itself is write-only and is never returned.

In the TypeScript SDK this operation has two methods:

  • client.agent.signIn({ token }) signs this container’s agent in to the Hoody platform with a token of the box’s owner; token is required. Until then the agent’s shell and file tools answer “not logged in”.
  • client.agent.platform.bootstrapToken(data) sends the same request body as given, without the SDK checking for token first.

Request body

Section titled “Request body”
NameTypeRequiredDescription
tokenstringYesThe raw Hoody platform token to install. Write-only; validated via the sidecar before install and never echoed.
capabilitystringNoThe operator bootstrap capability, required only on deployments configured with one; a mismatch is answered 404.
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.signIn({ token: 'hdy_...' });

PUT /api/v1/agent/hoody/realm

Section titled “PUT /api/v1/agent/hoody/realm”

Switches the realm the agent is working in, exactly like the realm selector of its terminal interface. The selection is saved and applies to every client; it is the realm new sessions bind to by default and the realm session listing uses on an agent without a pinned realm.

realm_id is a 24-hex realm id, or an empty string for all realms. An agent logged in with a realm-limited token may select only a realm its login serves (GET /api/v1/agent/hoody/auth/status lists them in realm_ids); any other realm, or all realms, is refused 403 realm_not_allowed. While the login’s realms cannot be read yet the switch is refused 503 restriction_unknown.

Request body

Section titled “Request body”
NameTypeRequiredDescription
realm_idstringYesA 24-hex realm id, or an empty string for all realms.
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.realms.use({ realm_id: '67e89abc123def456789abcd' });

Discovery

Section titled “Discovery”

GET /api/v1/agent/realms

Section titled “GET /api/v1/agent/realms”

Lists the realms visible to the token, so a caller can pick a valid bind target for POST /api/v1/agent/sessions. The agent’s own realm scope (pinned or active, and whether it is blocked) is on GET /api/v1/agent/hoody/auth/status.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pagequeryintegerNo1-based page number for pagination.
limitqueryintegerNoMaximum items per page (0 = no pagination).
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer, record cwd, or tool and workflow cwd. Required by routes that resolve a cwd (for example POST /todos; client.agent.todos.create() also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read or write resolves against.
import { HoodyClient } from 'hoody-sdk';


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


for await (const item of client.agent.realms.listIterator()) {
  // each item is a 24-hex realm id
}

GET /api/v1/agent/containers

Section titled “GET /api/v1/agent/containers”

Lists the containers in a realm so a caller can pick a bind target. A 24-hex realm id lists that realm’s containers; an omitted or empty realm, or global, lists the agent’s active realm; any other value is refused.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pagequeryintegerNo1-based page number for pagination.
limitqueryintegerNoMaximum items per page (0 = no pagination).
realmquerystringNoPer-request realm selector, the in-query 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 or no-realm routes.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer, record cwd, or tool and workflow cwd. Required by routes that resolve a cwd (for example POST /todos; client.agent.todos.create() also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read or write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only or no-realm routes.
import { HoodyClient } from 'hoody-sdk';


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


for await (const item of client.agent.containers.listIterator({ realm: '67e89abc123def456789abcd' })) {
  // each item is a container row in the selected realm
}