Skip to content
Hoody Documentation
Download Page (.md)

Projects & Containers

Section titled “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

Section titled “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

Section titled “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

Section titled “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:

POST Create a new project
/api/v1/projects/
Click "Run" to execute the request

Learn More: Projects API →

Containers: HTTP Computers

Section titled “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 for the authoritative service list.

Create a Container:

POST Create a new container
/api/v1/projects/{project_id}/containers
Click "Run" to execute the request

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 →

The URL Pattern

Section titled “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

Section titled “Quick Example”
POST Create a project for your SaaS
/api/v1/projects/
Click "Run" to execute the request

Response returns project_id: abc123...

What Containers Can Do

Section titled “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

Section titled “Lifecycle & State”
  • Snapshots → - Time travel: capture complete state, restore instantly
  • Copy & Sync → - Duplicate to other projects/servers, sync with source
  • Images → - Choose OS: Ubuntu, Debian, Alpine, Fedora…

Networking & Security

Section titled “Networking & Security”

Data & Sharing

Section titled “Data & Sharing”

Access & Control

Section titled “Access & Control”

Advanced

Section titled “Advanced”
  • Realms → - API-level isolation for multi-tenant setups

The Foundation

Section titled “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:

Next Steps: