Projects & Computers
Section titled “Projects & Computers”A computer is an isolated Linux computer, and you are not limited to one. Projects are how you group them: projects organize, computers execute, and services provide capabilities.
Account └── Projects (organizational units) ├── Computer 1 (HTTP computer) │ ├── terminal-1, terminal-2... │ ├── display-1, display-2... │ ├── files-1, exec-1, sqlite-1... │ └── browser-1, agent-1... (20 services) ├── Computer 2 (HTTP computer) ├── Computer 3 (HTTP computer) └── ...Every service of a computer has its own URL, so you compose HTTP endpoints instead of managing servers. AI agents, humans and IoT devices all use the same protocol.
Group computers into a project
Section titled “Group computers into a project”A project is an organizational unit that groups related computers. It is not tied to a server: the computers of one project can run on any of your servers (US, EU, Asia).
| A project gives you | How |
|---|---|
| Organization | Group computers by client, purpose or environment, with a name (alias) and a color for visual identification |
| A quota | max_computers caps the computers in the project; null means unlimited. It is checked when a computer is created |
| Access | Proxy permissions decide who can open the computers’ URLs (open by default). Project groups and permission cells merge with the computer’s own settings: a computer’s definitions override matching group names and cells, and unmatched project grants still apply. A computer can also override the project’s default policy. Teammates get read, edit or delete access to the project through project permissions |
For example, a project client-acme-corp might contain 15 computers (frontend, backend, database, staging, testing…), use purple (#9b59b6) for visual identification and have a limit of 50 computers. Create a project:
You can rename a project, change its color or quota later, or delete it. Your account starts with one default project (is_default: true), which cannot be deleted. Deleting any other project that still holds computers is refused with 422 PROJECT_HAS_COMPUTERS unless you pass delete_computers=true, which deletes its computers with it and cannot be undone. Update, delete and every field: Projects API.
In the Hub, open Computers, select Projects and press New project. Enter a Name, pick a Colour and press Make project. Where permitted, a project’s menu offers Rename and Delete. The first project cannot be deleted, and other projects must contain no computers before the Hub can delete them. Use the API to set the computer quota.
Create a computer in a project
Section titled “Create a computer in a project”Each computer is a complete Linux computer, and every capability it has is an HTTP endpoint. You create it inside a project, on the server you name in server_id: the server_id field of one of your servers in hoody servers list -o json or GET /api/v1/rentals, not the rental id. Replace {id} with the project’s id and ... with your server’s server_id before sending.
The create call returns the computer with status: "creating", or with "running" when it is already ready; a create can take several minutes. Poll GET /api/v1/computers/{id} (SDK: client.api.computers.get("...")) until status === "running" before calling the service URLs.
To make a create safe to retry, send an Idempotency-Key header: a retry within 24 hours with the same key and body returns the first request’s outcome, with the computer as it is now, instead of a second computer. A retry while the first request is still running can get 409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After. A create that fails with nothing created frees the key (Computers API). Fields, defaults and what is fixed at creation: Create, edit & delete.
In the Hub, open Computers and press Get a computer. Pick the Server and Project (or make one with New project), keep or change the suggested Name, and press Get computer. Hoody Kit, Developer kit and Autostart are under More options and are on by default. A new computer starts regardless of Autostart; this setting controls whether it starts when its server boots.
Which services does a computer run?
Section titled “Which services does a computer run?”With Hoody Kit (hoody_kit: true, the default), one computer is addressable as a set of per-service URLs. A computer created without it has none of the Kit service URLs. Your own HTTP service still answers at http-{port}.
| Service | What it gives you |
|---|---|
| Terminal | Shell commands executed over HTTP |
| Displays | Desktop sessions reachable through a URL |
| Files | The filesystem as HTTP endpoints |
| Exec | Scripts that become HTTP APIs |
| SQLite | A database you query over HTTP |
| Browser | Chromium or Firefox automation as REST APIs |
| Agent | The Hoody Agent web UI for AI and agent orchestration, and for managing services |
| Tunnel | Raw TCP and WebSocket bridging |
Also Code, cURL, Cron, Daemons, egress, Pipe, Notifications, Notes, Watch, Run, Proxy Logs and VM: 20 built-in HTTP services, plus SSH and dynamic http/https port ranges. The Hoody Kit overview is the authoritative service list.
Read a computer’s URL
Section titled “Read a computer’s URL”Every computer service has its own URL, built from this structure:
https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.computers.hoody.com| Segment | In the example | Read or swap it |
|---|---|---|
| Project ID | 67e89abc123def456789abcd | The project the computer belongs to |
| Computer ID | 890abcdef12345678901cdef | The computer |
| Service | terminal | Change it to display to switch to a desktop session |
| Instance | 1 | Change it to 2 to reach another instance (which services run several) |
| Server name | node-example-1 | Shows which server runs this computer |
The URL alone tells you the project, computer, service, instance and server. More on the model: Everything is a URL, and the vision pages that build on this hierarchy: The HTTP Revolution, Embeddability, Multiplayer by Default, 100x Foundation.
Build a project with three computers
Section titled “Build a project with three computers”Create a project for your SaaS, then a frontend, a backend and a database computer in it.
The three computers need three free computer slots on the server you pick. A free server usually already holds a default computer and allows three in total, stopped ones included. Delete a computer you do not need, or pick a server with room.
Response returns the new project’s id: abc123...
Replace {id} with the project’s id and ... with your server’s server_id before sending.
Frontend computer:
Backend computer:
Database computer:
3 isolated computers in one project, each with:
- Terminal URLs for command execution
- Display URLs for desktop access
- Files URLs for filesystem
- Exec URLs for running scripts
- SQLite URLs for databases
- 15 more HTTP services each (20 total)
What else can a computer do?
Section titled “What else can a computer do?”Every capability below is managed over HTTP. Each one has its own page.
| Area | Capability | What it does |
|---|---|---|
| Lifecycle and state | Snapshots | Capture the computer’s filesystem and restore it later |
| Copy & Sync | Duplicate it to other projects or servers. Syncing a copy is not available yet | |
| Images | The base image (debian/13) and the image marketplace | |
| Networking and security | Network Config | Route outbound traffic through a proxy, or block it |
| Firewall Rules | Granular ingress and egress control | |
| IPv4 | A dedicated IPv4 can’t be ordered yet (coming soon); how to set a computer’s exit IP and reach it without one | |
| Data and sharing | Storage Shares | Share directories between computers |
| Storage Systems | Persistent data management | |
| Access and control | Proxy Aliases | A hostname you choose, such as my-app.node-us.computers.hoody.com |
| Permissions | Authentication, IP restrictions, JWT |
Advanced
Section titled “Advanced”- Realms: API-level isolation for multi-tenant setups. A token restricted to a realm sees and changes only the resources in that realm, and the number of realms your account can use is limited. See Realms.
- Project statistics and proxied usage: read resource usage for every computer in a project, or its per-month proxied request counts and response bytes. See project statistics and proxied usage on the Projects API page.
What’s next
Section titled “What’s next”- Explore Foundation: the HTTP-first mindset
- The Hoody Kit: what each service does
- API Reference: complete endpoint documentation