# Hoody Kit reference **Page:** kit/reference [Download Raw Markdown](./kit/reference.md) --- # Hoody Kit reference Lookup tables for [the Hoody Kit](/kit/). Every route, field and response is in the [API reference](/api/authentication/). ## Service URLs When you spawn a computer with `hoody_kit: true`, you get URLs for all 20 Kit services: ``` https://PROJECT-COMPUTER-terminal-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-display-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-files-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-sqlite-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-exec-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-browser-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-agent-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-code-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-curl-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-n-1.SERVER.computers.hoody.com # Notifications https://PROJECT-COMPUTER-daemon-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-cron-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-pipe-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-notes-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-watch-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-run-1.SERVER.computers.hoody.com # Run https://PROJECT-COMPUTER-logs-1.SERVER.computers.hoody.com # Proxy Logs https://PROJECT-COMPUTER-tunnel-1.SERVER.computers.hoody.com https://PROJECT-COMPUTER-vm-1.SERVER.computers.hoody.com # Virtual machines https://PROJECT-COMPUTER-egress.SERVER.computers.hoody.com # Egress: one proxy per computer; the index is optional and defaults to 1 ``` | Item | Rule | |---|---| | Start | Nothing needs installing or starting by hand. Most services, Hoody Agent among them, start on the first request that reaches their URL; Terminal, Cron, Watch, VM and egress run from computer boot. Either way, open a URL and use it. | | Daemon and Proxy Logs | Neither is a program the daemon supervises: Daemon runs as a systemd unit and Proxy Logs is served by the proxy. | | Egress | One proxy per computer; the index is optional and defaults to 1. | | Companion labels | Not counted among the 20, because each is a companion to a service above: `desktop` opens the terminal kit in a desktop session, `cdp` is the Chrome DevTools Protocol endpoint paired with a Browser instance, and `d-tcp` is the direct display WebSocket endpoint. | | Not documented here | One more registered label: `workspaces`. | ## Interaction and display Services you use to see and control your computers. | Service | Capabilities | Used for | |---|---|---| | [Agent](/kit/agent/) | An AI coding agent that lives in your computer: open it in a browser tab, or send it a task with `hoody agent prompt` from your own terminal or the hosted CLI over SSH. Chat sessions that keep running when you close the tab. Fleet tabs to browse your computers, files, scripts and domains. A grid of panes: sessions, computer terminals and embedded web pages, with draggable dividers. Every action also available over an HTTP API. Access from any device. Terminal-native TUI plus HTTP API. | Coding and automation inside a computer, managing a fleet from one place, working from a phone or a borrowed laptop | | [Terminals](/kit/terminals/) ([API](/api/terminal/sessions/)) | The computer's Linux terminal as a web service, reachable from anywhere. Web terminal UI in browser. HTTP command execution API. Multiple terminal instances per computer. Session state persistence (cwd, env, history). SSH to remote servers (no client needed). Launch GUI apps. | Command execution, automation, remote server management, AI agent control | | [Displays](/kit/displays/) ([API](/api/displays/web-client/)) | Remote desktop over HTTP, with nothing to configure. Linux GUI applications in the browser, or a full Xfce desktop through `desktop-N`. Multiple display instances, each an X display that can run several applications. Pairing with terminals: GUI programs started from a terminal first opened in a browser at `terminal-5` open on `display-5`. Session sharing for multiplayer. Screenshot API. Computer Use API: mouse, keyboard, window and clipboard control over HTTP. | Visual development tools, GUI applications, browser automation, design software | | [Browser](/kit/browser/) ([API](/api/browser/instance-management/)) | Control Chromium and Firefox instances over a REST API for testing and automation. Browser instance management. JavaScript evaluation in the page. HTML and text extraction, and PDF export from headless Chromium. Screenshot capture. Cookies, console logs (page console calls need `stealth=false`) and network logs. Health monitoring. | Web scraping, automated testing, screenshot services | | [Pipe](/kit/pipe/) | Named pipes over the internet: send to a path, receive from the same path, and the data streams through as it arrives. Real-time streaming (not store-and-forward). Multi-receiver fan-out (up to 256 receivers). Live broadcasts with late joins; slow viewers skip ahead or are cut. WebSocket relay for messages in both directions between two peers. Browser pages for files, downloads, screen, camera and audio sharing. Video player and progress spectating via SSE. Status snapshots, transfer receipts, SHA-256 checks and Prometheus metrics. Binary-clean transport, so you can add your own encryption (`openssl enc -aes-256-cbc -pbkdf2 -in secret.pdf \| curl -T - "$PIPE/encrypted"`, with `$PIPE` your pipe URL) for end-to-end secrecy. | Screen sharing, file transfers, live data piping, event forwarding, multiplayer collaboration | ## Data and state Services that store and return information. | Service | Capabilities | Used for | |---|---|---| | [Files](/kit/files/) ([API](/api/files/)) | Read, download and manage files over HTTP across local storage and 49 cloud storage and protocol backends. Web File Manager UI. HTTP file streaming. File integrity verification (hashes). Shared Storage cross-computer access. | Cloud aggregation, download verification, cross-computer file sharing | | [SQLite](/kit/sqlite/) ([API](/api/sqlite/sql-operations/)) | Run SQLite queries and use a KV store through HTTP endpoints. Web Database UI. SQL operations via HTTP. KV store with time-travel. Reachable from other computers over HTTP. Atomic operations and batch updates. | Configuration management, feature flags, session storage, shared state | | Notes ([API](/api/notes/)) | Realtime multi-user notes over HTTP, with inline databases and file attachments. Realtime multi-user editing. Inline tables and databases. File attachments per note. ZIP export as Markdown or HTML, with attachments and CSV. REST and WebSocket API. Permissions are checked again when each write is saved, so many clients and scripts can write at once safely: a write whose author lost access before it saved is refused and nothing is saved to the notebook (sync batches report refusals per item). Only notebook owners can grant or change the owner role. | Shared runbooks, team knowledge bases, embedded checklists | ## Automation and orchestration Services that run code and coordinate systems. | Service | Capabilities | Used for | |---|---|---| | [Exec](/kit/exec/) ([API](/api/exec/script-execution/)) | Turn a script file into an HTTP endpoint, with dependency management and script templates. Run TypeScript and JavaScript via HTTP (Bun runtime). Automatic dependency installation. AI helpers inside scripts. Hoody AI interception and proxy hooks. Built-in logging and monitoring. | API endpoints, webhooks, automation, service customization | | [cURL](/kit/curl/) ([API](/api/curl/execution/)) | Make web requests from your computer, with scheduling, sessions and response storage. Wrap POST into GET: turn any POST request into a GET URL. Execute HTTP requests via API. Request scheduling (cron-like). Session management (cookies, headers). Response storage and history. | API integrations, web scraping, scheduled tasks, workflow automation | | Run ([API](/api/run/)) | A multi-source app resolver: query app names across Nix, pkgx, AppImage, Docker/OCI and manifest registries, and get back the exact shell command. Search across 9+ package sources in one query. Candidate ranking (manual or first-match). Exact shell command output (agent-friendly). Path-based URLs that resolve an app and return its command. Named profiles with your default preferences. | AI agent app discovery, portable install flows, cross-source launchers | ## Operations and monitoring Services that manage and observe what is running. | Service | Capabilities | Used for | |---|---|---| | [Daemons](/kit/daemons/) ([API](/api/daemon/management/)) | Manage long-running background services through an HTTP API. Program lifecycle control (enable, disable, start, stop). Process monitoring and health checks. Log aggregation. Auto-restart on failure. Resource usage tracking. Optional [program sandbox](/kit/program-sandbox/) for filesystem, TCP port and resource confinement. | Background services, worker processes, monitoring daemons | | [Cron](/kit/cron/) ([API](/api/cron/)) | Create, update, enable, disable and auto-expire scheduled tasks through a REST API. Managed entries with UUID, metadata and comments. Enable or disable without deletion. Auto-expiration with background cleanup. Per-user crontab management. Raw crontab read and write for full control. Standard 5-field cron plus macros (`@hourly`, `@daily` and others). | Scheduled backups, periodic data processing, maintenance tasks, temporary monitoring | | [Notifications](/kit/notifications/) ([API](/api/kit/notification-server/)) | Trigger desktop push notifications through HTTP endpoints. Custom icons. Notification history. WebSocket streaming. Urgency levels (low, normal, critical). | Build alerts, monitoring notifications, user engagement | | [Code](/kit/code/) ([API](/api/code/)) | A full VS Code editor in the browser, reachable at a web URL. Extensions from the Open VSX marketplace, from an HTTP call, or preloaded from a directory in the computer. Terminal integration. Multi-instance support. Health monitoring. | Web-based development, collaborative coding, mobile development | | Watch ([API](/api/watch/)) | Watch paths recursively and stream the file system events over SSE or WebSocket. Recursive directory watching (Linux inotify). SSE streaming. WebSocket streaming. Pattern filters. | Build triggers, live reload, file-change-driven automation | | Proxy Logs ([API](/api/proxy-logs/)) | Query and tail the Hoody Proxy access log for the computer over HTTP. Query historical access logs. Live tail over SSE. Filter by path, method, status, time range. | Debugging access issues, traffic analysis, audit trails | | [Tunnel](/kit/tunnel/) | TCP tunneling over HTTP: expose local services online, or pull remote services into the computer through the relay. Expose HTTP and WebSocket services at the computer's URL. Pull a TCP service from your laptop onto the computer's loopback. Session-based control plane. URL and port bindings management. | Sharing local dev servers, bridging networks, remote access | | [Egress](/kit/egress/) | The computer's outbound HTTP proxy: `CONNECT` for HTTPS, absolute-URI forwarding for plain HTTP, and optional chaining to an upstream proxy. Standard HTTP proxy endpoint on its own URL. Chain to a SOCKS5 or HTTP upstream. Change or clear the upstream at runtime. Upstream credentials stored, never returned. | Routing computer traffic through a fixed exit IP, reaching APIs that allowlist an address | | [VM](/kit/vm/) ([API](/api/vm/)) | Full virtual machines inside the computer: QEMU accelerated by KVM, managed over HTTP by name. Create from a template, a blank disk, an installer image or an imported snapshot. Start, stop, force stop, pause and resume. Snapshots with restore, and export to another computer. Serial console, run logs and guest-agent reports. Live state changes over Server-Sent Events. | Running Windows or another Linux distribution, disposable test machines, OS installs watched in the browser | ## Instances | Use | Example | |---|---| | Separation of concerns | terminal-1 for frontend, terminal-2 for backend, terminal-3 for the database | | Parallel operations | Run tests in exec-1 while building in exec-2 | | Agent windows | `agent-1` and `agent-2` open separate windows on the same agent | | Multi-user collaboration | Each user gets their own terminal or display instance | Give instances semantic meaning: ``` terminal-1 → Frontend work terminal-2 → Backend work terminal-3 → Database management terminal-4 → DevOps/deployment agent-1 → Agent window: code and tests agent-2 → Agent window: documentation agent-3 → Agent window: infrastructure exec-1 → API endpoints exec-2 → Scheduled tasks exec-3 → Data processing ``` ## Embedding The proxy generally adds iframe headers (`Content-Security-Policy: frame-ancestors` and `Cross-Origin-Resource-Policy`) to the browser pages of the terminal, desktop, display, browser, code, files, notes, SQLite, notifications, pipe, cron, Hoody Run, watch and exec services. A page that explicitly refuses framing keeps that refusal. For Exec pages, an application's own `X-Frame-Options` or CSP `frame-ancestors` policy is preserved; the proxy adds its framing headers only when neither is supplied. On the Agent service only the web UI gets them. A page your own application serves on an `http-{port}` or `https-{port}` URL keeps the headers the application sends. The cURL service has no page to frame and gets no iframe headers. | Service | Embed | |---|---| | Terminals | A live shell | | Desktop | A full graphical desktop | | Displays | A display in the web viewer | | Files | A file browser or editor | | Code | VS Code | | Browser | A live browser view | | SQLite | The database overview, tables and query pages | | Notes | A notebook | ## Snapshots and services Snapshots capture the [computer filesystem](/foundation/computers/snapshots/#what-snapshots-capture): file contents, on-disk database state, daemon configuration, and terminal history that has been written to disk. They do not capture RAM, running processes, or in-flight connections, so restoring starts the computer from that filesystem instead of resuming it mid-execution. ## Terminal or Exec Prefer Exec when the job deserves a script: run `cd /app && npm test && echo "done"` by POSTing `{"command":"cd /app && npm test && echo \"done\""}` as JSON to `/api/v1/terminal/execute` on the desired `terminal-N` service URL, but POSTing to `/test-runner.ts` on the desired `exec-N` service URL gets you logging, error handling, and structure. Prefer Terminal when the job is one command: creating an Exec script just to run `ls -la` is overhead, so POST `{"command":"ls -la"}` as JSON to `/api/v1/terminal/execute` on the desired `terminal-N` service URL instead. ## Multi-service scripts Because everything speaks HTTP, everything composes: ```javascript // terminalUrl, sqliteUrl, execUrl, filesUrl, agentUrl: the service URLs listed above; // process-data.ts: an Exec script you create. // Assumes database `app` with a `users` table already exists. // Terminal executes command that queries database fetch(terminalUrl + '/api/v1/terminal/execute', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: `curl -X POST ${sqliteUrl}/api/v1/sqlite/db?db=app -H 'Content-Type: application/json' -d '{"transaction":[{"statement":"SELECT * FROM users"}]}'` }) }); // Exec script reads file, processes data, stores in database fetch(execUrl + '/process-data.ts', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ input_file: filesUrl + '/data/input.csv', output_db: sqliteUrl }) }); // Agent orchestrates entire workflow across all services // 1. Create a session const session = await fetch(agentUrl + '/api/v1/agent/sessions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({}) }).then(r => r.json()); // 2. Dispatch a turn (:sync waits for the turn but returns pending_gate if it parks on a gate, // and after 290 seconds answers 503 with details.turn_id while the turn keeps running) fetch(agentUrl + `/api/v1/agent/sessions/${session.session_id}/prompt:sync`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ text: "Deploy the app using terminal, monitor with browser, store logs in database" }) }); ``` ### Files, SQLite and Exec as a data pipeline ```javascript // filesUrl, execUrl, sqliteUrl: the service URLs listed above; etl.ts: an Exec script you create. // Read CSV from a connected cloud backend (Google Drive here; use its backend ID) const driveBackendId = 'YOUR_GOOGLE_DRIVE_BACKEND_ID'; const data = await (await fetch( filesUrl + '/api/v1/files/data.csv?backend=' + encodeURIComponent(driveBackendId) )).text(); // Process with exec script const processed = await fetch(execUrl + '/etl.ts', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ data }) }); if (!processed.ok) throw new Error('Exec failed: ' + processed.status); // Store the script's output in SQLite await fetch(sqliteUrl + '/api/v1/sqlite/db?db=analytics&create_db_if_missing=true', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ transaction: [ { statement: 'CREATE TABLE IF NOT EXISTS analytics (payload TEXT NOT NULL)' }, { statement: 'INSERT INTO analytics (payload) VALUES (?)', values: [await processed.text()] } ] }) }); ``` ### The agent driving every service One task description drives multiple services: ```javascript // Agent has access to all computer services // 1. Create a session const session = await fetch(agentUrl + '/api/v1/agent/sessions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({}) }).then(r => r.json()); // 2. Dispatch a turn and wait for it (:sync). ?policy=auto_approve auto-answers confirm gates // for hands-off automation, except rule-raised and static_stakes destructive-action gates // (answered false) and human_only ones (returned as pending_gate); a question or plan gate still returns pending_gate, and a turn // that runs past about five minutes answers 503 with details.turn_id while it keeps running. const agent = await fetch(agentUrl + `/api/v1/agent/sessions/${session.session_id}/prompt:sync?policy=auto_approve`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ text: "Set up production environment" }) }); // Agent coordinates: // 1. Terminal - Install dependencies // 2. Files - Download config from cloud // 3. SQLite - Initialize database schema // 4. Exec - Run deployment script // 5. Notifications - Alert when complete ``` ## Example setups | Setup | How | |---|---| | Coding from a phone or tablet | The code, terminal and display URLs put the whole development environment in a mobile browser. | | AI-driven development | The agent has HTTP access to every service and orchestrates the development workflow over HTTP, and a human approves critical decisions. | | A team across time zones | Share the agent URL (`agent-1`); everyone works in the same computer, from anywhere, through the agent's grid of sessions, computer terminals and embedded pages. | ``` https://PROJECT-COMPUTER-code-1.SERVER.computers.hoody.com → Full VS Code in mobile browser https://PROJECT-COMPUTER-terminal-1.SERVER.computers.hoody.com → Run builds and tests https://PROJECT-COMPUTER-display-1.SERVER.computers.hoody.com → Preview GUI applications ``` ``` PROJECT-COMPUTER-agent-1.SERVER.computers.hoody.com → AI has HTTP access to: ├─ terminal (execute commands) ├─ files (read/write code) ├─ exec (run scripts) ├─ sqlite (manage state) └─ browser (test web apps) ``` ``` # Share the agent URL with the team https://PROJECT_ID-COMPUTER_ID-agent-1.node-example-1.computers.hoody.com # Team sees: - Live terminal sessions (multiplayer) - Shared displays (see what others see) - Common file access - Shared database state ``` ## Troubleshooting | Symptom | Cause | What to do | |---|---|---| | Service URL returns 404 | The hostname names no computer or no Kit service: wrong project ID, computer ID, server or service label | [Check the URL](#service-url-returns-404) | | Service URL returns 503 with a holding page | The computer is being provisioned or the requested service is starting | Check its status with `GET /api/v1/computers/{id}` | | Service URL returns 401 or 403 | Proxy permissions block the service | [Check the permissions](#service-url-returns-404) | | Service URLs respond slowly | The server is overloaded with too many computers or processes, high traffic on the computer congests the network, or the computer is out of CPU or memory | [Check resources](#service-is-slow-or-unresponsive) | | A service works from your laptop but not from a phone or public WiFi | Proxy permissions restrict access by IP or require authentication | [Read and change the default](#service-unreachable-from-one-device-or-network) | ### Service URL returns 404 `https://PROJECT_ID-COMPUTER_ID-terminal-1.node-us.computers.hoody.com` returns 404 when the hostname names no computer (`errorCode: MAPPING_NOT_FOUND`) or no Kit service. Verify the project ID, the computer `id`, the `server_name` and the service label. Other answers have other causes: - `503` with a holding page: the computer is being provisioned or the requested service is starting. `503` with `COMPUTER_STOPPED` or `COMPUTER_PAUSED`: the computer is stopped or paused. Check its status with `GET /api/v1/computers/{id}`. - `401` or `403`: proxy permissions block the service. To diagnose: ```bash # Verify computer is running curl "https://api.hoody.com/api/v1/computers/$COMPUTER_ID" \ -H "Authorization: Bearer $HOODY_TOKEN" | jq '.data.status' # Check server name matches # Should be: node-example-1, node-example-2, etc. (check computer response) # Verify proxy permissions allow access curl "https://api.hoody.com/api/v1/computers/$COMPUTER_ID/proxy/permissions" \ -H "Authorization: Bearer $HOODY_TOKEN" ``` ### Service is slow or unresponsive To diagnose: ```bash # Check the computer's CPU, memory and disk I/O counters curl "https://$PROJECT_ID-$COMPUTER_ID-terminal-1.$SERVER.computers.hoody.com/api/v1/system/resources" # Check running processes curl "https://$PROJECT_ID-$COMPUTER_ID-terminal-1.$SERVER.computers.hoody.com/api/v1/system/processes?sort=cpu" # Consider moving to less loaded server or upgrading server resources ``` ### Service unreachable from one device or network This usually means proxy permissions restrict access by IP or require authentication. With `"default": "allow"`, callers who match no group get in too, apart from [two refusals](/foundation/proxy/permissions/#who-can-open-my-urls), so the computer is no longer limited to your groups. See [proxy permissions](/foundation/proxy/permissions/) for access control details. In the Hub, open Computers, select the computer and open Permissions. Review **Who can open the programs**. If **Only these IPs** is selected, update **Allowed IPv4 addresses or ranges**, choose **Save** and confirm the change. To do the same over HTTP: ```bash # Check current permissions (note the file_version for the If-Match header) GET /api/v1/computers/{id}/proxy/permissions # Remove the IP restriction by opening the default policy to "allow". # Write operations require the If-Match: file:v header. PATCH /api/v1/computers/{id}/proxy/permissions/default If-Match: file:v3 { "default": "allow" } ```