# Projects & Computers **Page:** foundation/projects-computers [Download Raw Markdown](./foundation/projects-computers.md) --- # 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 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](/foundation/proxy/permissions/#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](/api/projects/#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](/api/projects/). 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 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}`](/foundation/computers/managing/#check-current-status) (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](/api/computers/#create-and-authorize-computers)). Fields, defaults and what is fixed at creation: [Create, edit & delete](/foundation/computers/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? With Hoody Kit (`hoody_kit: true`, the default), one computer is addressable as a set of per-service URLs. A computer created [without it](/foundation/computers/create-edit-delete/#can-i-create-computers-without-hoody_kit) has none of the Kit service URLs. Your own HTTP service still answers at [`http-{port}`](/foundation/proxy/#serve-your-own-app). | 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](/kit/) is the authoritative service list. ## 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](/kit/#run-several-instances-of-a-service)) | | 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](/concepts/everything-is-a-url/#how-is-a-computer-url-built), and the vision pages that build on this hierarchy: [The HTTP Revolution](/vision/http-revolution/), [Embeddability](/vision/embeddability/), [Multiplayer by Default](/vision/multiplayer/), [100x Foundation](/vision/100x-foundation/). ## 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? Every capability below is managed over HTTP. Each one has its own page. | Area | Capability | What it does | |---|---|---| | Lifecycle and state | [Snapshots](/foundation/computers/snapshots/) | Capture the computer's filesystem and restore it later | | | [Copy & Sync](/foundation/computers/copy-sync/) | Duplicate it to other projects or servers. Syncing a copy is not available yet | | | [Images](/foundation/computers/images/) | The base image (`debian/13`) and the image marketplace | | Networking and security | [Network Config](/foundation/networking/network/) | Route outbound traffic through a proxy, or block it | | | [Firewall Rules](/foundation/networking/firewall/) | Granular ingress and egress control | | | [IPv4](/foundation/networking/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](/foundation/storage/sharing-files/) | Share directories between computers | | | [Storage Systems](/foundation/storage/) | Persistent data management | | Access and control | [Proxy Aliases](/foundation/proxy/aliases/) | A hostname you choose, such as `my-app.node-us.computers.hoody.com` | | | [Permissions](/foundation/proxy/permissions/) | Authentication, IP restrictions, JWT | ## 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](/foundation/hoody-api/realms/#realm-limits). See [Realms](/foundation/hoody-api/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](/api/projects/#project-statistics) and [proxied usage](/api/projects/#proxied-usage) on the Projects API page. ## What's next - [Explore Foundation](/foundation/http-mindset/): the HTTP-first mindset - [The Hoody Kit](/kit/): what each service does - [API Reference](/api/authentication/): complete endpoint documentation