# Quick Start reference **Page:** getting-started/quickstart/reference [Download Raw Markdown](./getting-started/quickstart/reference.md) --- # Quick Start reference Lookup tables for the [Quick Start](/getting-started/quickstart/). ## Before you start | You need | Used by | Detail | | :--- | :--- | :--- | | A Hoody account with a verified email | Every step | Sign up at [hoody.com/signup](https://hoody.com/signup), with `hoody signup`, from the `ssh hoody.com` menu or through your AI ([Step 1](/getting-started/quickstart/#step-1-create-an-account-and-sign-in)). 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](/foundation/wallet/referral-program/#signup-with-a-referral)) | | 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](/foundation/servers/#the-free-tier)). `GET /api/v1/users/me/free-tier-status` shows whether you can claim one and why not ([free tier and onboarding](/api/users/#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](/foundation/cli/#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 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](/kit/#the-20-http-services) 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](/foundation/hoody-api/authentication/#create-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 These programmatic interfaces reach the same account and the same computers. The Quick Start uses the first four in its tabs. | Interface | Setup | | :--- | :--- | | **[CLI](https://cli.hoody.com)** | `npm install -g hoody-sdk@1.0.1`, or without installing: `npx hoody-sdk@1.0.1 `. Other install methods: [Install](/foundation/cli/#install). Profiles, defaults, update, uninstall: [CLI reference](/foundation/cli/) | | **[TypeScript SDK](https://sdk.hoody.com)** | `npm install hoody-sdk@1.0.1` (Node.js 20.19+, 22+ recommended; Bun; Deno) | | **[Raw HTTP](/api/authentication/)** | `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](/kit/curl/)) | | **[Browser SDK](https://sdk.hoody.com)** | 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](/foundation/hoody-api/authentication/#create-an-auth-token), never your account credentials | These entry points need no code: | Entry point | What it opens | Detail | | :--- | :--- | :--- | | `ssh hoody.com` ([https://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](/foundation/cli/#open-the-hub-in-your-terminal); an account without one first offers **Get my free computer**. A [scoped auth token](/foundation/hoody-api/authentication/#create-an-auth-token), limited to the calls it needs, as the SSH username (`ssh @hoody.com`) skips the welcome screen and sign-in. It is interactive only; scripts use the installed CLI ([Use the CLI over SSH](/foundation/cli/#use-the-cli-over-ssh)) | | [https://hub.hoody.com](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](/getting-started/quickstart/#step-8-open-the-hoody-agent) | | `@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](/getting-started/connect-your-ai/) 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](/getting-started/quickstart/#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](/getting-started/quickstart/#step-3-open-a-desktop-and-a-terminal-in-the-browser) | | 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](/kit/agent/chat-apps/)) or by [voice](/kit/agent/voice/) | | A Bot URL | One Bot, for people and AI apps that hold a key you made | [Bot URLs](/kit/agent/bot-urls/) | ## 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](/kit/displays/#open-or-embed-a-display)) | | 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 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**. ```bash # 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 ``` ```typescript // 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 server const 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); ``` ```bash # Grab your free-tier server's server_id SERVER_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 project PROJECT_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 server COMPUTER=$(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=0 while [ "$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 2 done echo "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 | 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](/foundation/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](/foundation/proxy/reference/#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 | 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](/api/users/#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 ` (find the ID with `hoody computers list`), or [create one](#create-a-computer-and-wait-for-it) | | 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](/foundation/proxy/reference/#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](/kit/agent/#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](/foundation/servers/)) |