# Projects & Containers **Page:** foundation/projects-containers [Download Raw Markdown](./foundation/projects-containers.md) --- # Projects & Containers **You don't have one computer anymore. You have infinite isolated computers, organized into Projects.** Hoody's architecture is simple: **Projects** organize, **Containers** execute, **Services** provide capabilities. --- ## The Hierarchy ``` Account └── Projects (organizational units) ├── Container 1 (HTTP computer) │ ├── terminal-1, terminal-2... │ ├── display-1, display-2... │ ├── files, exec-1, sqlite-1... │ └── browser-1, agent-1... (18 services) ├── Container 2 (HTTP computer) ├── Container 3 (HTTP computer) └── ... ``` --- ## Projects: Folders for Computers **Projects are organizational units** that group related Containers.
**Example Project**: `client-acme-corp` - **Contains**: 15 containers (frontend, backend, database, staging, testing...) - **Color**: Purple (#9b59b6) for visual identification - **Limit**: 50 max containers
**Projects are NOT tied to servers** - Containers within a Project can run on ANY of your servers (US, EU, Asia). ### What You Get - **Organization** - Group by client, purpose, or environment - **Limits** - `max_containers` quota per project - **Permissions** - Project-level access control applies to all containers - **Prespawn** - Auto-create ready containers **Create a Project:** **Learn More**: [Projects API →](/api/projects/) --- ## Containers: HTTP Computers **Each Container is a complete Linux computer.** Every capability is exposed as HTTP endpoints.
**One Container = One Computer, addressable as a set of per-service URLs:** - **Terminal** - Execute shell commands via HTTP - **Displays** - Desktop sessions accessible through URL - **Files** - Filesystem as HTTP endpoints - **Exec** - Scripts that become HTTP APIs - **SQLite** - Database queryable via HTTP - **Browser** - Chrome automation as REST APIs - **Workspaces** - AI/agent orchestration (hosts the `agent` service) - **Tunnel** - Raw TCP/WebSocket bridging - **Plus**: Code, cURL, Cron, Daemons, Pipe, Notifications, Notes, Watch, Run, Proxy Logs, plus SSH and dynamic `http`/`https` ports See the [Hoody Kit overview](/kit/) for the authoritative service list.
**Create a Container:** **Creation is asynchronous.** The create call returns immediately with `status: "creating"`. Services become reachable in under 30 seconds for most images; poll `GET /api/v1/containers/{id}` (SDK: `client.api.containers.get(id)`) until `status === "running"` before hitting the service URLs. **Learn More**: [Containers API →](/api/containers/) --- ## The URL Pattern Every Container service has its own URL following this structure:
https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-us.containers.hoody.icu ``` └─────────┬─────────┘ └─────────┬─────────┘ └───┬───┘ └┬┘ └────┬────┘ Project ID Container ID Service Inst ServerName ```
**What this means:** - Change `terminal` → `display` to switch to desktop - Change `1` → `2` for another instance - `node-us` shows which server runs this Container **Everything is self-documenting through URLs.** --- ## Quick Example Response returns `project_id: abc123...` **Frontend container:** **Backend container:** **Database container:** **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 - 13 more HTTP services each (18 total) --- ## What Containers Can Do Containers provide extensive capabilities, all managed via HTTP. This is just an introduction—each capability has its own detailed documentation. ### Lifecycle & State - **[Snapshots →](/foundation/containers/snapshots/)** - Time travel: capture complete state, restore instantly - **[Copy & Sync →](/foundation/containers/copy-sync/)** - Duplicate to other projects/servers, sync with source - **[Images →](/foundation/containers/images/)** - Choose OS: Ubuntu, Debian, Alpine, Fedora... ### Networking & Security - **[Network Config →](/foundation/networking/network/)** - Route through proxies, custom DNS - **[Firewall Rules →](/foundation/networking/firewall/)** - Granular ingress/egress control - **[IPv4 Management →](/foundation/networking/ipv4/)** - Dedicated IP addresses ### Data & Sharing - **[Storage Shares →](/foundation/storage/sharing-files/)** - Share directories between containers - **[Storage Systems →](/foundation/storage/)** - Persistent data management ### Access & Control - **[Proxy Aliases →](/foundation/proxy/aliases/)** - Custom domains: `my-app.hoody.icu` - **[Permissions →](/foundation/proxy/permissions/)** - Authentication, IP restrictions, JWT ### Advanced - **[Realms →](/foundation/hoody-api/realms/)** - API-level isolation for multi-tenant setups --- ## The Foundation **You compose HTTP endpoints, not manage servers.** - **Projects** organize your work (by client, purpose, environment) - **Containers** are computers (each spawns with 18 built-in HTTP services plus dynamic HTTP/HTTPS port ranges) - **Every service has a URL** (terminal, display, files, exec, sqlite...) - **Everything is HTTP** (AI agents, humans, IoT all speak the same language) This simple hierarchy enables everything else: - [The HTTP Revolution →](/vision/http-revolution/) - [Embeddability →](/vision/embeddability/) - [Multiplayer by Default →](/vision/multiplayer/) - [100x Foundation →](/vision/100x-foundation/) --- **Next Steps:** - 🏛️ [Explore Foundation →](/foundation/http-mindset/) - Understand the HTTP-first mindset - 🛠️ [The Hoody Kit →](/kit/) - See what each service does - 📚 [API Reference →](/api/authentication/) - Complete endpoint documentation