Skip to content

Beta: these docs are still being updated. The next full update is on 19 November at 8 PM UTC. Docs in beta. Full update 19 Nov, 8 PM UTC.

Hoody.com

Lookup tables for the Quick Start.

You needUsed byDetail
A Hoody account with a verified emailEvery stepSign up at hoody.com/signup, with hoody signup, from the ssh hoody.com menu or through your AI (Step 1). Verify your email before signing in. If someone referred you, open their referral link or enter their code in the optional referral field at signup: it cannot be added later (Referral Program)
A server with a running computerSteps 2 to 9A verified new account comes with a free server, a project named Default and a first computer with the Hoody Kit (the free tier). GET /api/v1/users/me/free-tier-status shows whether you can claim one and why not (free tier and onboarding)
hoody-sdk@1.0.1CLI and SDK tabsOne package holds the CLI and the SDK. The examples pin this version
Node.js 20.19 or later (22 or later recommended), Bun or DenoSDK tabs, and the CLI installed from npmThe SDK tabs are one file, quickstart.mts, run with npx tsx quickstart.mts. Standalone CLI binaries for Linux, macOS and Windows need no Node.js (Install)
jqCLI and HTTP tabsReads ids out of JSON answers
curlHTTP tabsAny HTTP client works the same way
An ssh clientssh hoody.comInteractive only
A current browserThe Hub, the desktop, the web terminal and the agentNothing is installed on the device

A computer runs Debian 13 with systemd. Its Kit services are part of the computer when it is created with hoody_kit: true (--hoody-kit), which is what the first computer and Step 9 use.

The same three values appear in every computer URL. In prose they are written in braces, in shell tabs as variables, and in URL tabs as bare uppercase names to replace before you open the link.

In URL shapesIn shell and URL tabsValue
{projectId}$PROJECT_ID, PROJECT_IDThe computer’s project_id, a 24-character ID
{computerId}$COMPUTER_ID, COMPUTER_IDThe computer’s id, a 24-character ID
{server}$SERVER_NAME, SERVER_NAMEThe computer’s server_name, the hostname segment its URLs live on. Not server_id
{service}Written out: desktop, terminal, http, files, sqlite, agentThe Kit service label. The Hoody Kit lists them all
{instance}Written out: terminal-0, files-1, http-3000The service instance number. For http it is the port your server listens on
VariableUsed forValue
HOODY_TOKENThe Bearer header on api.hoody.comThe access token hoody login --print-token prints, or an auth token. The Kit calls on the page send no token
HOODY_EMAIL, HOODY_PASSWORDHoodyClient.login in the SDK tabsYour account’s email and password. Pass username instead of email if you signed up with a username
COMPUTERSteps 2 and 9The JSON of one computer, from which the three URL values and its server_id are read
SERVER_IDCreating a computer (Step 9)The server_id of one of your servers. It identifies the server in API calls and is not part of computer service hostnames
SESSION_IDThe agent task (Step 8)The session_id the agent returns when it creates a session
HOODY_COMPUTER_IDThe CLIExported once, it is the computer for Kit commands that carry no -c

A link in a URL tab is sent by the computer’s own curl-1 service, so its host also carries the three values. That is why Steps 1 and 2, which find those values, have no link.

These programmatic interfaces reach the same account and the same computers. The Quick Start uses the first four in its tabs.

InterfaceSetup
CLInpm install -g hoody-sdk@1.0.1, or without installing: npx hoody-sdk@1.0.1 <command>. Other install methods: Install. Profiles, defaults, update, uninstall: CLI reference
TypeScript SDKnpm install hoody-sdk@1.0.1 (Node.js 20.19+, 22+ recommended; Bun; Deno)
Raw HTTPcurl with a Bearer token on api.hoody.com
A linkAny request written as one GET link that the computer’s curl-1 service sends for you (cURL)
Browser SDKCDN build that exposes window.HoodySDK in any static page, from one script tag: https://cdn.jsdelivr.net/npm/hoody-sdk@1.0.1/dist/hoody-sdk.browser.min.js. Hand pages short-lived scoped auth tokens, never your account credentials

These entry points need no code:

Entry pointWhat it opensDetail
ssh hoody.com (https://ssh.hoody.com)A sandboxed, memory-only Hoody CLI session from any machine with an ssh clientNothing is installed on the device and nothing is kept between connections. Its menu creates an account or signs you in. An account with a computer opens the Hub in the terminal; an account without one first offers Get my free computer. A scoped auth token, limited to the calls it needs, as the SSH username (ssh <hdy_token>@hoody.com) skips the welcome screen and sign-in. It is interactive only; scripts use the installed CLI (Use the CLI over SSH)
https://hub.hoody.comThe Hub, Hoody’s web interface, in any browser; its Agent panel talks to the Hoody Agent on your computer. hoody hub opens the same Hub in a terminal, from the standalone binary on Linux (x86-64 and arm64) or from the npm package under Node 26 or later on LinuxStep 8
@https://hoody.com Connect to HoodyAny AI that can run code with network access signs you in through your browser and runs the platform for youPaste it into ChatGPT, Claude, Gemini or another such AI. It reads the Hoody Skill, sends you a sign-in link and a code to approve in your browser (or a signup link if you are new), and once you approve can do anything the API, SDK or CLI can do on your account. An AI that can only fetch URLs can read the Skill but cannot sign you in. There is no server to host and no plugin to install. Connect Your AI to Hoody walks through it, including the setting some AI apps need before they can reach Hoody
npx skills addThe Hoody Skill in a coding agent you already runGive your agent the Skill
A computer’s service URLsThe desktop, the web terminal, the file manager and the agent, each in a browser tabStep 3
Telegram, Slack or DiscordA Bot that answers in the chat app and starts agents on your computersA Bot is a long-running assistant inside the Hoody Agent that talks with people and starts agent sessions to do work. Reach one from a chat app (Chat apps for your Bot) or by voice
A Bot URLOne Bot, for people and AI apps that hold a key you madeBot URLs

api.hoody.com answers with an envelope, { statusCode, message, data }, and the result is in data. The CLI’s -o json prints data itself. A Kit service answers with its result directly, which the SDK returns under .data.

StepCallWhat comes back
1GET /api/v1/users/auth/meConfirms the token is valid: data is the signed-in account, with id, username, email and email_verified. hoody login --print-token prints only the access token
2GET /api/v1/computers/data.computers, one entry per computer with id, project_id, server_id, server_name, status, is_default and hoody_kit, and data.pagination
3The desktop-1 and terminal-1 linksPages. The desktop link sends the browser on to the display that shows the desktop, normally display-1601 for desktop-1 (display numbers)
4POST /api/v1/terminal/execute, then GET on the http-3000 linkThe command’s finished result, then whatever your server answers: here, the index.html the command wrote
5POST /api/v1/terminal/executeWith wait: true, the finished result: command_id, stdout, stderr, exit_code, timed_out. In a terminal session stdout is terminal text, with stderr merged into it and CRLF line endings. GET /api/v1/terminal/result/{command_id} returns the same object. Ask the host that ran it: terminal-0 for an ephemeral command, terminal-N for terminal N. The SDK’s terminal.run returns stdout, stderr, exitCode, timedOut, duration and commandId
6PUT /api/v1/files/{path}, then GET on the same pathThe upload answers 201 with success, message, path and size, and creates the folders that are missing on the way. The read returns the file’s raw bytes
7POST /api/v1/sqlite/dbresults, one item per statement or query, in order. A query’s item carries success, resultHeaders and resultSet, one object per row
8POST /api/v1/agent/sessions, then POST /api/v1/agent/sessions/{id}/prompt:syncCreate returns session_id. The turn returns status, session_id and turn_id when it ends, with no reply text, and pending_gate when a confirmation is waiting
9POST /api/v1/projects/{id}/computers, then GET /api/v1/computers/{id}Create answers 201 with data.id, data.project_id and data.server_name. Repeat the read until data.status is running; failed comes with data.failure_reason

Step 9 creates a computer next to your first one. This script starts from the account alone: it takes your first active server, creates a project, creates a Kit computer in it and waits until the computer is running.

In the Hub, open Computers, then Projects, and press New project. Enter my-first-project as its Name and press Make project. Then press Get a computer, pick the new project under Project and a server with room under Server, leave Hoody kit on and press Get computer. Wait until its state is Running.

Terminal window
# Take your first active server (on a new account, that is the free-tier one)
# (-o json prints the response data itself, no envelope to unwrap)
SERVER_ID=$(hoody servers list -o json \
| jq -r '[.[] | select(.status == "active")][0].server_id')
# Create a project, then spawn a Kit computer on that server
PROJECT_ID=$(hoody projects create --alias "my-first-project" -o json | jq -r '.id')
COMPUTER=$(hoody computers create --project "$PROJECT_ID" --server-id "$SERVER_ID" \
--name "dev-box" --hoody-kit -o json)
COMPUTER_ID=$(echo "$COMPUTER" | jq -r '.id')
SERVER_NAME=$(echo "$COMPUTER" | jq -r '.server_name')
# Wait until it is "running" (up to 5 minutes); then retry Kit requests while services start.
# If it ends "failed", delete it and create it again.
SECONDS=0
while [ "$SECONDS" -lt 300 ]; do
STATUS=$(hoody computers get "$COMPUTER_ID" -o json | jq -r '.status')
[ "$STATUS" = running ] && break
[ "$STATUS" = failed ] && { echo "Creation failed: delete the computer and create it again" >&2; break; }
sleep 2
done
echo "Status: $STATUS"
# Once it is running, make it the CLI's default computer. Sign-in picked your account's
# existing default, which commands without -c would otherwise keep using
if [ "$STATUS" = running ]; then
hoody config set computer "$COMPUTER_ID"
fi

The CLI and HTTP tabs leave PROJECT_ID, COMPUTER_ID and SERVER_NAME on the new computer, so the Quick Start’s Steps 3 to 8 run on it unchanged. In the SDK, devBox is its client.

WhatLimit
A free server2 cores, 3 GB RAM, 20 GB disk and 3 computers, with caps on disk and network speed, shared by every computer on it. Limits can change: Pricing. Stopped computers count toward the computer cap
The access token from hoody loginLasts 1 day
A CLI requestWaits 30 seconds by default
An SDK callWaits 30 seconds by default; pass timeoutMs for a longer call, as the agent task does
A command in an ephemeral session (Step 5)Ended after 600 seconds unless the request sets a timeout
A desktop opened for the first timeIts display can take a moment to start; the link waits up to a minute for it
Ports for your own servers (Step 4)80 to 499 are always clear of the Kit; a higher port can collide with one the Kit uses (reserved ports)
An agent turn over prompt:syncA turn still running after 290 seconds answers 503 with details.turn_id to poll
The auth token that signs the agent inNeeds at least 15 minutes left before it expires
SymptomCauseWhat to do
servers list returns nothing activeA fresh free-tier server may still be provisioning, and provisioning time variesKeep polling; it appears with status: "active" and a non-null server_id
servers list returns nothing at allThe free server was not assigned: free-tier capacity ran out, or the claim is on hold or was refusedRead GET /api/v1/users/me/free-tier-status and follow its reason (free tier and onboarding)
Step 2 finds no running computer, or COMPUTER_ID is nullThe first computer is still being set up, the free server is not on the account yet, or the computer is not runningRun Step 2 again in a moment, then check the two rows above. Start a stopped computer with hoody computers start <computer-id> (find the ID with hoody computers list), or create one
Kit URLs 404 or refuse to connectThe computer or service is still startingPoll the computer until it is running, then retry the Kit request. If it remains unavailable, check the service’s status through the Daemon API.
Kit URLs 404 or refuse to connectThe computer was created with --no-hoody-kit / hoody_kit: falseKit URLs need a computer created with the Kit (--hoody-kit / hoody_kit: true)
Kit URLs 404 or refuse to connectYour URL uses server_id where the hostname needs server_namePut the computer’s server_name in the hostname
401 on api.hoody.comThe token is missing or expired (an access token lasts 1 day)Re-run hoody login --print-token and re-export HOODY_TOKEN
CLI says No computer specified. Kit commands require a target computer.Kit commands (terminal, files, db, …) target a computer via -c "$COMPUTER_ID"Pass it explicitly, or export it once as HOODY_COMPUTER_ID
A terminal call answers status: "running" or "queued" and no stdoutThe call was sent with wait: false, so it returned at once. wait: true answers the same way for an SSH session, with defer_pid, or when 256 waiting calls are openPoll GET /api/v1/terminal/result/{command_id} on the same host for its output
The http-3000 link gives a connection errorNothing listens on that port, the port in the URL is wrong, or the bind addressCheck with netstat -tlnp | grep 3000 in the computer, use the server’s port in the URL, and see bind addresses
The agent’s tools answer not logged inThe session was bound to a computer through your account while the agent had no sign-inSign the agent in with hoody agent login -c "$COMPUTER_ID" and an auth token created from your signed-in session (Sign the agent in to your account), then start a new session
The agent turn returns pending_gateA confirmation is waiting for a decisionAnswer it in the agent’s page. Sending the prompt again, even with automatic approval, returns the same gate. For later turns, --gate-policy auto_approve or policy=auto_approve approves ordinary confirmations; a human-only gate still waits for a person
Creating a computer is refused with SERVER_COMPUTER_LIMITThe server is at its computer cap, and stopped computers countDelete a computer you no longer need, or use a server with room (Servers)