Quick Start reference
Section titled “Quick Start reference”Lookup tables for the Quick Start.
Before you start
Section titled “Before you start”| You need | Used by | Detail |
|---|---|---|
| A Hoody account with a verified email | Every step | Sign 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 computer | Steps 2 to 9 | A 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.1 | CLI and SDK tabs | One package holds the CLI and the SDK. The examples pin this version |
| Node.js 20.19 or later (22 or later recommended), Bun or Deno | SDK tabs, and the CLI installed from npm | The 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) |
jq | CLI and HTTP tabs | Reads ids out of JSON answers |
curl | HTTP tabs | Any HTTP client works the same way |
An ssh client | ssh hoody.com | Interactive only |
| A current browser | The Hub, the desktop, the web terminal and the agent | Nothing 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.
Placeholders and variables
Section titled “Placeholders and variables”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 shapes | In shell and URL tabs | Value |
|---|---|---|
{projectId} | $PROJECT_ID, PROJECT_ID | The computer’s project_id, a 24-character ID |
{computerId} | $COMPUTER_ID, COMPUTER_ID | The computer’s id, a 24-character ID |
{server} | $SERVER_NAME, SERVER_NAME | The computer’s server_name, the hostname segment its URLs live on. Not server_id |
{service} | Written out: desktop, terminal, http, files, sqlite, agent | The Kit service label. The Hoody Kit lists them all |
{instance} | Written out: terminal-0, files-1, http-3000 | The service instance number. For http it is the port your server listens on |
| Variable | Used for | Value |
|---|---|---|
HOODY_TOKEN | The Bearer header on api.hoody.com | The access token hoody login --print-token prints, or an auth token. The Kit calls on the page send no token |
HOODY_EMAIL, HOODY_PASSWORD | HoodyClient.login in the SDK tabs | Your account’s email and password. Pass username instead of email if you signed up with a username |
COMPUTER | Steps 2 and 9 | The JSON of one computer, from which the three URL values and its server_id are read |
SERVER_ID | Creating 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_ID | The agent task (Step 8) | The session_id the agent returns when it creates a session |
HOODY_COMPUTER_ID | The CLI | Exported 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.
Ways to connect
Section titled “Ways to connect”These programmatic interfaces reach the same account and the same computers. The Quick Start uses the first four in its tabs.
| Interface | Setup |
|---|---|
| CLI | npm 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 SDK | npm install hoody-sdk@1.0.1 (Node.js 20.19+, 22+ recommended; Bun; Deno) |
| Raw HTTP | curl with a Bearer token on api.hoody.com |
| A link | Any request written as one GET link that the computer’s curl-1 service sends for you (cURL) |
| Browser SDK | CDN 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 point | What it opens | Detail |
|---|---|---|
ssh hoody.com (https://ssh.hoody.com) | A sandboxed, memory-only Hoody CLI session from any machine with an ssh client | Nothing 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.com | The 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 Linux | Step 8 |
@https://hoody.com Connect to Hoody | Any AI that can run code with network access signs you in through your browser and runs the platform for you | Paste 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 add | The Hoody Skill in a coding agent you already run | Give your agent the Skill |
| A computer’s service URLs | The desktop, the web terminal, the file manager and the agent, each in a browser tab | Step 3 |
| Telegram, Slack or Discord | A Bot that answers in the chat app and starts agents on your computers | A 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 URL | One Bot, for people and AI apps that hold a key you made | Bot URLs |
What each step returns
Section titled “What each step returns”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.
| Step | Call | What comes back |
|---|---|---|
| 1 | GET /api/v1/users/auth/me | Confirms 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 |
| 2 | GET /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 |
| 3 | The desktop-1 and terminal-1 links | Pages. The desktop link sends the browser on to the display that shows the desktop, normally display-1601 for desktop-1 (display numbers) |
| 4 | POST /api/v1/terminal/execute, then GET on the http-3000 link | The command’s finished result, then whatever your server answers: here, the index.html the command wrote |
| 5 | POST /api/v1/terminal/execute | With 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 |
| 6 | PUT /api/v1/files/{path}, then GET on the same path | The 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 |
| 7 | POST /api/v1/sqlite/db | results, one item per statement or query, in order. A query’s item carries success, resultHeaders and resultSet, one object per row |
| 8 | POST /api/v1/agent/sessions, then POST /api/v1/agent/sessions/{id}/prompt:sync | Create 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 |
| 9 | POST /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 |
Create a computer and wait for it
Section titled “Create a computer and wait for it”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.
# 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 serverPROJECT_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=0while [ "$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 2doneecho "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 usingif [ "$STATUS" = running ]; then hoody config set computer "$COMPUTER_ID"fi// Take your first active server (on a new account, that is the free-tier one)const rentals = (await hoody.api.servers.list()).data ?? [];const serverId = rentals.find(r => r.status === 'active' && r.server_id)?.server_id;if (!serverId) throw new Error('No active server yet: a new free-tier server can take a moment, retry shortly');
// Create a project, then spawn a Kit computer on that serverconst project = await hoody.api.projects.create({ alias: 'my-first-project' });const { data: created } = await hoody.api.computers.create(project.data!.id, { server_id: serverId, name: 'dev-box', hoody_kit: true, // preinstall the Kit service layer: terminal, files, sqlite, agent, ...});const computerId = created?.id;if (!computerId) throw new Error('The computer was not created');
// Poll until "running" (up to 5 minutes), then scope a client to the computer.// If it ends "failed", delete it and create it again.const deadline = Date.now() + 5 * 60 * 1000;for (;;) { const { data } = await hoody.api.computers.get(computerId); if (data?.status === 'running') break; if (data?.status === 'failed') throw new Error(`Creation failed (${data.failure_reason?.code}): delete the computer and create it again`); if (Date.now() > deadline) throw new Error(`Still ${data?.status} after 5 minutes`); await new Promise(r => setTimeout(r, 2000));}const devBox = await hoody.withComputer(computerId);# Grab your free-tier server's server_idSERVER_ID=$(curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ https://api.hoody.com/api/v1/servers \ | jq -r '[.data[] | select(.status == "active")][0].server_id')
# Create a projectPROJECT_ID=$(curl -s -X POST https://api.hoody.com/api/v1/projects/ \ -H "Authorization: Bearer $HOODY_TOKEN" -H "Content-Type: application/json" \ -d '{"alias": "my-first-project"}' | jq -r '.data.id')
# Spawn a Kit computer on that serverCOMPUTER=$(curl -s -X POST "https://api.hoody.com/api/v1/projects/$PROJECT_ID/computers" \ -H "Authorization: Bearer $HOODY_TOKEN" -H "Content-Type: application/json" \ -d '{"server_id": "'"$SERVER_ID"'", "name": "dev-box", "hoody_kit": true}')COMPUTER_ID=$(echo "$COMPUTER" | jq -r '.data.id')SERVER_NAME=$(echo "$COMPUTER" | jq -r '.data.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=0while [ "$SECONDS" -lt 300 ]; do STATUS=$(curl -s -H "Authorization: Bearer $HOODY_TOKEN" \ "https://api.hoody.com/api/v1/computers/$COMPUTER_ID" | jq -r '.data.status') [ "$STATUS" = running ] && break [ "$STATUS" = failed ] && { echo "Creation failed: delete the computer and create it again" >&2; break; } sleep 2doneecho "Status: $STATUS"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.
Limits
Section titled “Limits”| What | Limit |
|---|---|
| A free server | 2 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 login | Lasts 1 day |
| A CLI request | Waits 30 seconds by default |
| An SDK call | Waits 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 time | Its 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:sync | A turn still running after 290 seconds answers 503 with details.turn_id to poll |
| The auth token that signs the agent in | Needs at least 15 minutes left before it expires |
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | What to do |
|---|---|---|
servers list returns nothing active | A fresh free-tier server may still be provisioning, and provisioning time varies | Keep polling; it appears with status: "active" and a non-null server_id |
servers list returns nothing at all | The free server was not assigned: free-tier capacity ran out, or the claim is on hold or was refused | Read 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 null | The first computer is still being set up, the free server is not on the account yet, or the computer is not running | Run 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 connect | The computer or service is still starting | Poll 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 connect | The computer was created with --no-hoody-kit / hoody_kit: false | Kit URLs need a computer created with the Kit (--hoody-kit / hoody_kit: true) |
| Kit URLs 404 or refuse to connect | Your URL uses server_id where the hostname needs server_name | Put the computer’s server_name in the hostname |
401 on api.hoody.com | The 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 stdout | The 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 open | Poll GET /api/v1/terminal/result/{command_id} on the same host for its output |
The http-3000 link gives a connection error | Nothing listens on that port, the port in the URL is wrong, or the bind address | Check 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 in | The session was bound to a computer through your account while the agent had no sign-in | Sign 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_gate | A confirmation is waiting for a decision | Answer 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_LIMIT | The server is at its computer cap, and stopped computers count | Delete a computer you no longer need, or use a server with room (Servers) |