Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Projects & Containers

Section titled “Projects & Containers”

You are not limited to one computer. A container is an isolated Linux computer, and projects are how you group them.

The hierarchy has three levels: projects organize, containers execute, and 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-1, exec-1, sqlite-1...
        │     └── browser-1, agent-1... (18 services)
        ├── Container 2 (HTTP computer)
        ├── Container 3 (HTTP computer)
        └── ...

Projects

Section titled “Projects”

A project is an organizational unit that groups 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 one project can run on any of your servers (US, EU, Asia).

What a project provides

Section titled “What a project provides”
  • Organization: group by client, purpose, or environment
  • Limits: a max_containers quota per project
  • Permissions: project-level access control applies to all its containers
  • Defaults: project-wide settings such as SSH keys, inherited by new containers

Create a project:

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

Learn more: Projects API →

Containers

Section titled “Containers”

Each container is a complete Linux computer, and every capability it has is an HTTP endpoint.

One container is one computer, addressable as a set of per-service URLs:

  • Terminal: execute shell commands 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: Chrome automation as REST APIs
  • Agent: the Hoody OS UI for AI and agent orchestration, and for managing services
  • Tunnel: raw TCP and WebSocket bridging
  • Also: Code, cURL, Cron, Daemons, Pipe, Notifications, Notes, Watch, Run, and 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/{id}/containers
Click "Run" to execute the request

Container creation is asynchronous. The create call returns immediately with status: "creating" (when the container is served from a warm prespawn pool the claim is finalized before the response, so you get "running" straight away). Services become reachable in under 30 seconds for most images; poll GET /api/v1/containers/{id} (SDK: client.api.containers.get("...")) 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, built from this structure:

https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-us-1.containers.hoody.com

       └─────────┬─────────┘ └─────────┬─────────┘ └───┬───┘ └┬┘ └────┬────┘
            Project ID          Container ID        Service  Inst  ServerName

Each field can be read or swapped on its own:

  • Change terminal → display to switch to a desktop session
  • Change 1 → 2 to reach another instance
  • node-us-1 shows which server runs this container

The URL alone tells you the project, container, service, instance, and server.

Quick example

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

Response returns the new project’s id: abc123...

Container capabilities

Section titled “Container capabilities”

Every capability below is managed over HTTP. This section is an overview; each one has its own page.

Lifecycle and state

Section titled “Lifecycle and state”
  • Snapshots →: capture the container’s complete state and restore it later
  • Copy & Sync →: duplicate to other projects or servers, and sync with the source
  • Images →: choose the OS, such as Ubuntu, Debian, Alpine, or Fedora

Networking and security

Section titled “Networking and security”

Data and sharing

Section titled “Data and sharing”

Access and control

Section titled “Access and control”

Advanced

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

Summary

Section titled “Summary”

You compose HTTP endpoints instead of managing servers.

  • Projects organize your work (by client, purpose, or 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, and more)
  • Everything is HTTP (AI agents, humans, and IoT devices use the same protocol)

The vision pages build on this hierarchy:

What’s Next

Section titled “What’s Next”