# Create, Edit, Delete

**Page:** foundation/containers/create-edit-delete

[Download Raw Markdown](./foundation/containers/create-edit-delete.md)

---

# Create, Edit, Delete

**Containers are HTTP computers you spawn on demand.** Create them in 1-5 seconds, configure them exactly how you need, and delete them when you're done.

After understanding [Projects & Containers](/foundation/projects-containers/), you need to know how to **actually create and manage** individual containers.

---

## API Endpoints Summary

**Official Technical Reference:**

This Foundation page explains container CRUD concepts and workflows. For complete endpoint documentation:

**Container Creation:**
- **[POST /api/v1/projects/\{id\}/containers](/api/containers/)** - Create new container
- **[GET /api/v1/containers](/api/containers/)** - List all containers
- **[GET /api/v1/containers/\{id\}](/api/containers/)** - Get container details

**Container Modification:**
- **[PATCH /api/v1/containers/\{id\}](/api/containers/)** - Update container configuration

**Container Deletion:**
- **[DELETE /api/v1/containers/\{id\}](/api/containers/)** - Delete container permanently

**Related Operations:**
- **[Container Operations](/api/container-operations/)** - Start/stop/pause/resume
- **[Projects](/api/projects/)** - Project management

---

## Creating Containers

**Every container you create becomes a complete HTTP computer with the full Hoody Kit service stack.**

### The Basic Creation



**Within 1-5 seconds:**
- Container is running (prespawn) or creating (regular)
- The full Hoody Kit HTTP stack is live
- URLs automatically generated

**Startup timing:**
- **With prespawn:** Sub-second (claimed from warm pool)
- **Without prespawn:** 1-5 seconds (created on demand)

**Response includes container details:**

```json
{
  "statusCode": 201,
  "message": "Container created successfully",
  "data": {
    "id": "890abcdef12345678901cdef",
    "project_id": "67e89abc123def456789abcd",
    "server_id": "63f8b0e5c9a1b2d3e4f5a6b7",
    "server_name": "node-us",
    "name": "dev-environment",
    "status": "creating",
    "hoody_kit": true,
    "dev_kit": true
  }
}
```

**Your container URLs are now live:**

```
Terminal:  https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-us.containers.hoody.icu
Display:   https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.icu
Files:     https://67e89abc123def456789abcd-890abcdef12345678901cdef-files-1.node-us.containers.hoody.icu
Exec:      https://67e89abc123def456789abcd-890abcdef12345678901cdef-exec-1.node-us.containers.hoody.icu
SQLite:    https://67e89abc123def456789abcd-890abcdef12345678901cdef-sqlite-1.node-us.containers.hoody.icu
+ the rest of the 18 Kit services...
```

---

## Container Configuration Options

**When creating a container, you can customize every aspect:**

### Essential Parameters


  
    ```json
    {
      "name": "my-container"
    }
    ```
    
    - 3-100 characters
    - Alphanumeric + hyphens/underscores
    - Unique within project
    - Use `"rand"` or omit for auto-generated name
  
  
    ```json
    {
      "server_id": "63f8b0e5c9a1b2d3e4f5a6b7"
    }
    ```
    
    - Required during creation
    - Determines where container runs
    - Get via: `GET /api/v1/rentals` or `GET /api/v1/servers/available`
    - Choose by geography, capacity, or price
  
  
    ```json
    {
      "hoody_kit": true
    }
    ```
    
    - `true`: Install the Hoody Kit HTTP services (terminal, display, files, exec, sqlite, cron, pipe, notifications, curl, browser, code, daemon, tunnel, workspaces, ssh, proxy, plus dynamic http/https ports)
    - `false`: Plain Linux container
    - **Recommended:** Always use `true`
    - Can't be changed after creation
  
  
    ```json
    {
      "dev_kit": true
    }
    ```
    
    - `true`: Include developer-focused Kit services (editor, agent, and related workspaces tooling) on top of `hoody_kit`
    - `false`: Omit the developer stack to keep the image smaller
    - Default: `true` when `hoody_kit: true`
    - Can't be changed after creation
  


### Image Selection

**Choose your operating system:**

```json
{
  "container_image": "debian/13"
}
```

**Available images:**
- `debian/13` - Debian 13 Trixie ⭐ (recommended default)
- `debian/12` - Debian 12 Bookworm
- `ubuntu/24.04` - Ubuntu 24.04 LTS
- `ubuntu/22.04` - Ubuntu 22.04 LTS
- `alpine/3.19` - Alpine Linux (minimal)
- `fedora/<release>` - Fedora (pick an available release from `GET /api/v1/images/public?os=fedora`)

**Default:** If omitted or null, the system default image is used — currently `debian/13` (Debian 13 Trixie). You can override it with any image from the marketplace.

**See:** [Container Images](/foundation/containers/images/) for complete marketplace and OS options.

### Realm Assignment (API Segregation)

**Assign container to specific realms for API-level isolation:**

```json
{
  "realm_ids": ["64a2c4e9f3d5e2b6a8c7d8e1", "65b3d5f0a4e6f3c7b9d8e9f2"]
}
```

**Important:** Realms are **NOT private networks**. They segregate the Hoody API:
- Different realms use different API endpoints: `https://{realmId}.api.hoody.icu`
- AI agents in one realm can't discover containers in another
- Auth tokens can be scoped to specific realms
- Production/staging/development separated at API level

When creating from a realm-scoped host:
- The target project must already include that realm.
- The scoped realm is merged into container `realm_ids`.
- Realm-restricted auth tokens are forced to the active scoped realm only.


**AI Safety:** Isolate AI agents in different realms to prevent managing wrong containers. One realm per container = zero mistakes.


**See:** [Realms](/foundation/hoody-api/realms/) for complete API segregation details.

### Environment Variables

**Set environment variables for your application:**

```json
{
  "environment_vars": {
    "NODE_ENV": "production",
    "DATABASE_URL": "postgresql://...",
    "API_KEY": "your-secret-key"
  }
}
```

**These are available in the container immediately.**

### SSH Access

**Provide your SSH public key:**

```json
{
  "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGx..."
}
```

**Critical SSH Key Rules:**


**Each container needs a UNIQUE SSH public key:**
- SSH keys **must be different** for every container
- Hoody's SSH Proxy routes by public key (duplicates will conflict)
- **If omitted:** Defaults to `null` - container will have **NO SSH access** (but you can still access the shell via [hoody-terminal](/kit/terminals/) web interface)
- **Can be added later** via container update if you forget



**SSH is optional on Hoody.** You don't need SSH to manage containers - [`hoody-terminal`](/kit/terminals/) provides web-based shell access through HTTP. SSH is useful for local tools (VS Code Remote, rsync) but not required for day-to-day operations.


**Generate unique keys for each container:**

```bash
# Generate new key pair for each container
ssh-keygen -t ed25519 -f ~/.ssh/hoody-container-1 -N ""
ssh-keygen -t ed25519 -f ~/.ssh/hoody-container-2 -N ""

# Use different public keys
container_1: {"ssh_public_key": "ssh-ed25519 AAAA... (from container-1.pub)"}
container_2: {"ssh_public_key": "ssh-ed25519 AAAA... (from container-2.pub)"}
```

**Why unique keys matter:** Hoody's SSH Proxy identifies containers by public key. Reusing a key breaks routing - multiple containers can't share the same SSH identity.

**See:** [SSH Access](/foundation/networking/ssh/) for SSH configuration.

### Visual Organization (Color)

**Qubes-inspired color coding for instant visual identification:**

```json
{
  "color": "#3498db"  // HEX color (with or without #)
}
```

**Why colors matter (inspired by Qubes OS):**

Like Qubes OS uses colors to visually distinguish security domains (red = untrusted, green = trusted), Hoody lets you color-code containers for instant recognition.

**Especially useful for:**
- 🖥️ **WebOS builders** - Color-code different workspaces/applications
- 🔐 **Security zones** - Red = public-facing, green = internal, blue = database
- 👥 **Multi-user teams** - Each user/team gets distinct colors
- 🎯 **Environment types** - Yellow = dev, orange = staging, green = production

**Visual scanning beats text** - spot your production database instantly in 50 containers.

### Additional Options

```json
{
  "comment": "Development environment for Project X",
  "autostart": true,         // Auto-start when host reboots (default: true)
  "ai": true,               // Enable AI features (default: true)
  "cache": true,            // Use cached images (faster creation)
  "prespawn": false,        // Create as prespawn cache
  "ramdisk": true           // enabled by default, set false to disable
}
```

**About autostart (default: true):**
- When `true`: Container automatically starts when host machine reboots
- When `false`: Container stays stopped after host reboot (manual start required)
- **Default behavior:** Containers auto-start to ensure services remain available after server maintenance/restarts

**About ramdisk (default: enabled):**
- `/ramdisk` available by default for ultra-fast temporary storage in RAM
- **Set `ramdisk: false` to disable** if you don't need it
- **Zero RAM consumed when empty** - RAM allocated on-demand as you store files
- **Data persists through container restarts** (unique Hoody feature!)
- **Data lost only when HOST machine reboots** (not when container restarts)
- Perfect for cache, build artifacts, temporary processing that needs speed
- **See:** [/ramdisk](/foundation/storage/ramdisk/) for usage patterns and memory balancing

---

## Complete Creation Examples

### Example 1: Development Container

**Full-featured development environment:**



**Use case:** Your daily driver - full resources, all services, auto-starts.

### Example 2: Production API Container

**Optimized for running APIs:**



**Then configure:**
1. Create [proxy alias](/foundation/proxy/aliases/) for clean URL
2. Set [proxy permissions](/foundation/proxy/permissions/) for authentication
3. Configure [firewall rules](/foundation/networking/firewall/) for security

### Example 3: Minimal Utility Container

**Lightweight container for specific tasks:**



**Use case:** Run occasionally for backups, minimal resource footprint.

### Example 4: AI Agent Container

**Dedicated container for AI orchestration:**



**With hoody-agent service:**
```
https://67e89abc123def456789abcd-890abcdef12345678901cdef-workspaces-1.node-us.containers.hoody.icu
```

---

## Editing Containers

**Update container configuration via the API.**

### Update Workflow

**Important:** Most updates require the container to be stopped.


  
    ```bash
    # 1. Stop container
    hoody containers manage $CONTAINER_ID stop

    # 2. Update configuration
    hoody containers update $CONTAINER_ID \
      --name "renamed-container" \
      --environment-vars NODE_ENV=staging

    # 3. Restart container
    hoody containers manage $CONTAINER_ID start
    ```
  
  
    ```typescript
    // 1. Stop container
    await client.api.containers.manage(CONTAINER_ID, 'stop');

    // 2. Update configuration
    await client.api.containers.update(CONTAINER_ID, {
      name: 'renamed-container',
      environment_vars: { NODE_ENV: 'staging' }
    });

    // 3. Restart container
    await client.api.containers.manage(CONTAINER_ID, 'start');
    ```
  
  
    ```bash
    # 1. Stop container
    curl -X POST "https://api.hoody.icu/api/v1/containers/{container_id}/stop" \
      -H "Authorization: Bearer $HOODY_TOKEN"

    # 2. Update configuration
    curl -X PATCH "https://api.hoody.icu/api/v1/containers/{container_id}" \
      -H "Authorization: Bearer $HOODY_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "renamed-container",
        "environment_vars": {"NODE_ENV": "staging"}
      }'

    # 3. Restart container
    curl -X POST "https://api.hoody.icu/api/v1/containers/{container_id}/start" \
      -H "Authorization: Bearer $HOODY_TOKEN"
    ```
  


### What You Can Update

**Container metadata:**
- `name` - Rename container
- `color` - Change UI color
- `comment` - Update description

**Configuration:**
- `environment_vars` - Add/modify/remove env variables
- `ssh_public_key` - Change SSH access key
- `realm_ids` - Update API realm membership (realm-restricted tokens cannot modify this)
- `autostart` - Enable/disable auto-start
- `ai` - Enable/disable AI features
- `ramdisk` - Enable/disable ramdisk mount

**What you CANNOT change:**
- `container_image` - OS is permanent (create new container instead)
- `hoody_kit` - Service installation is permanent
- `server_id` - Cannot move servers (use [copy](/foundation/containers/copy-sync/) instead)

### Update Examples

**Example 1: Change Environment**

```bash
# Switch from staging to production
PATCH /api/v1/containers/{id}
{
  "environment_vars": {
    "NODE_ENV": "production",
    "API_BASE_URL": "https://api.mycompany.com"
  }
}
```

**Example 2: Move to Different Realm**

```bash
# Isolate to production network
PATCH /api/v1/containers/{id}
{
  "realm_ids": ["64a2c4e9f3d5e2b6a8c7d8e1"]
}
```

---

## Deleting Containers

**Permanent deletion of a container and all its data.**

### The Deletion Process



**What gets deleted:**
- ✅ Container filesystem and all data
- ✅ Environment variables
- ✅ Network configuration
- ✅ Firewall rules
- ✅ All service URLs become inaccessible
- ❌ **Snapshots are preserved** (until you delete them)
- ❌ **Existing copies keep running** (they are independent containers, but can no longer be synced — the source link is broken)


**This action is irreversible.** Always [snapshot](/foundation/containers/snapshots/) important containers before deletion.


### Safe Deletion Workflow


  
    ```bash
    # 1. Create final snapshot
    hoody snapshots create --container $CONTAINER_ID --alias "before-deletion-2025-11-09"

    # 2. Stop running container
    hoody containers manage $CONTAINER_ID stop

    # 3. Permanent deletion
    hoody containers delete $CONTAINER_ID

    # 4. Cleanup (optional) - delete proxy aliases
    hoody proxy delete $ALIAS_ID
    ```
  
  
    ```typescript
    // 1. Create final snapshot
    await client.api.containers.createSnapshot(CONTAINER_ID, {
      alias: 'before-deletion-2025-11-09'
    });

    // 2. Stop running container
    await client.api.containers.manage(CONTAINER_ID, 'stop');

    // 3. Permanent deletion
    await client.api.containers.delete(CONTAINER_ID);

    // 4. Cleanup (optional)
    await client.api.proxyAliases.delete(ALIAS_ID);
    ```
  
  
    ```bash
    # 1. Create final snapshot
    curl -X POST "https://api.hoody.icu/api/v1/containers/{id}/snapshots" \
      -H "Authorization: Bearer $HOODY_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"alias": "before-deletion-2025-11-09"}'

    # 2. Stop running container
    curl -X POST "https://api.hoody.icu/api/v1/containers/{id}/stop" \
      -H "Authorization: Bearer $HOODY_TOKEN"

    # 3. Permanent deletion
    curl -X DELETE "https://api.hoody.icu/api/v1/containers/{id}" \
      -H "Authorization: Bearer $HOODY_TOKEN"

    # 4. Cleanup (optional) - delete proxy aliases
    curl -X DELETE "https://api.hoody.icu/api/v1/proxy/aliases/{alias_id}" \
      -H "Authorization: Bearer $HOODY_TOKEN"
    ```
  


**Best practice:** Keep snapshots of production containers for disaster recovery.

---

## The Hoody Kit

**When you set `hoody_kit: true`, your container gets the full Hoody Kit HTTP stack:**

### What Gets Installed

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 1.5rem 0;">

<div style="padding: 1rem; background: #f8f8f8; border: 1px solid #ddd; border-radius: 4px;">

**Interact & Visualize:**
- **Terminal** ([hoody-terminal](/kit/terminals/)) - Web-based terminal
- **Display** ([hoody-display](/kit/displays/)) - Full desktop environment
- **Browser** ([hoody-browser](/kit/browser/)) - Chrome automation

</div>

<div style="padding: 1rem; background: #f8f8f8; border: 1px solid #ddd; border-radius: 4px;">

**Data & State:**
- **Files** ([hoody-files](/kit/files/)) - Filesystem access
- **SQLite** ([hoody-sqlite](/kit/sqlite/)) - Database + KV store

</div>

<div style="padding: 1rem; background: #f8f8f8; border: 1px solid #ddd; border-radius: 4px;">

**Automate & Orchestrate:**
- **Exec** ([hoody-exec](/kit/exec/)) - Scripts as HTTP APIs
- **cURL** ([hoody-curl](/kit/curl/)) - HTTP request wrapper

</div>

<div style="padding: 1rem; background: #f8f8f8; border: 1px solid #ddd; border-radius: 4px;">

**Operate & Monitor:**
- **Daemons** ([hoody-daemon](/kit/daemons/)) - Process management
- **Notifications** ([hoody-notifications](/kit/notifications/)) - Alerts
- **Code** ([hoody-code](/kit/code/)) - VS Code instances
- **Cron** ([hoody-cron](/kit/cron/)) - Scheduled task runner
- **Pipe** ([hoody-pipe](/kit/pipe/)) - Data streaming between services
- **Workspace** ([hoody-workspace](/kit/workspaces/)) - Collaborative workspace service

</div>

</div>

**Installation time:** Added to container creation (no extra wait).

**See:** [The Hoody Kit](/kit/) for complete service documentation.

---

## Container Lifecycle States

**Containers progress through these states:**

```
creating → running → (paused) → stopped → deleted
              ↓                    ↑
           (can pause)          (can restart)
```

### State Descriptions

| State | Description | Transitions Available |
|-------|-------------|----------------------|
| `creating` | Container being provisioned | → `running` (automatic) |
| `running` | Container is active | → `stopped`, `paused` |
| `paused` | Container suspended | → `running` (resume) |
| `stopped` | Container is stopped | → `running` (start) |
| `failed` | Creation or operation failed | → `deleted` (cleanup) |
| `copying` | Being copied to another location | → `running` (when complete) |
| `deleted` | Marked for deletion | (final state) |

**Get current state:**



**See:** [Managing Containers](/foundation/containers/managing/) for state transitions.

---

## Listing Your Containers

**Find containers across all projects:**

### List All Containers



### List Project Containers



### Filtering & Pagination



### Include Runtime Information

**Get live service status:**



**Response includes:**
- Active terminal sessions
- Display connections
- Running services (with PIDs)
- Network services and ports
- Command history

**Use this to verify services are running before using their URLs.**

---

## Complete Workflow Example

**From project creation to running container:**


  
    ```bash
    # 1. Create a project
    hoody projects create --alias "client-acme" --color "#e74c3c"

    # 2. Check your servers
    hoody servers list

    # 3. Create a container
    hoody containers create --project $PROJECT_ID \
      --server-id $SERVER_ID \
      --name "acme-frontend" \
      --hoody-kit \
      --ssh-public-key "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA..."

    # 4. Verify it's running
    hoody containers get $CONTAINER_ID

    # 5. Container URLs are live:
    # https://{project_id}-{container_id}-terminal-1.{server_name}.containers.hoody.icu
    # https://{project_id}-{container_id}-display-1.{server_name}.containers.hoody.icu
    ```
  
  
    ```typescript
    import { HoodyClient } from '@hoody-ai/hoody-sdk';
    const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: TOKEN });

    // 1. Create a project
    const project = await client.api.projects.create({
      alias: 'client-acme', color: '#e74c3c'
    });

    // 2. Get server ID from rentals
    const rentals = await client.api.rentals.list();
    const serverId = rentals.data[0].server_id;

    // 3. Create a container
    const container = await client.api.containers.create(
      project.data.id,
      {
        name: 'acme-frontend',
        server_id: serverId,
        hoody_kit: true,
        ssh_public_key: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...'
      }
    );

    // 4. Verify it's running
    const status = await client.api.containers.get(container.data.id);
    console.log(status.data.status); // 'running'
    ```
  
  
    ```bash
    # 1. Create a project
    curl -X POST "https://api.hoody.icu/api/v1/projects/" \
      -H "Authorization: Bearer $HOODY_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"alias": "client-acme", "color": "#e74c3c"}'

    # 2. Check your servers
    curl "https://api.hoody.icu/api/v1/rentals" \
      -H "Authorization: Bearer $HOODY_TOKEN"

    # 3. Create a container
    curl -X POST "https://api.hoody.icu/api/v1/projects/{project_id}/containers" \
      -H "Authorization: Bearer $HOODY_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "acme-frontend",
        "server_id": "{server_id}",
        "hoody_kit": true,
        "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA..."
      }'

    # 4. Verify it's running
    curl "https://api.hoody.icu/api/v1/containers/{container_id}" \
      -H "Authorization: Bearer $HOODY_TOKEN"

    # 5. Container URLs are live:
    # https://{project_id}-{container_id}-terminal-1.{server_name}.containers.hoody.icu
    ```
  


---

## Best Practices

### 1. Use Prespawn for Production

Configure prespawn templates for production containers to eliminate startup delays. Sub-second availability means faster auto-scaling, instant failover, and better user experience.

### 2. Generate Unique SSH Keys Per Container

Never reuse SSH keys. Generate a new ed25519 key pair for each container to ensure proper routing via Hoody's SSH Proxy.

```bash
ssh-keygen -t ed25519 -f ~/.ssh/container-{name} -N ""
```

### 3. Use realm_ids for AI Agent Isolation

When using AI agents, isolate containers in different realms to prevent accidents. An agent in realm A cannot discover or manage containers in realm B - complete API-level separation ensures safety.

### 4. Color-Code by Purpose

Use Qubes-style color coding: red for public-facing, green for internal services, blue for databases, yellow for development. Visual identification beats reading labels.

### 5. Snapshot Before Deletion

Always create a snapshot before permanently deleting important containers. The snapshot preserves all data for recovery if needed.

### 6. Set autostart Based on Priority

Critical services: `autostart: true` (ensures availability after host reboots). Development containers: `autostart: false` (saves resources).

### 7. Use debian/13 as Default

Unless you have specific requirements, stick with `debian/13` for excellent stability, security, and package availability.

### 8. Leverage /ramdisk for Performance

ramdisk is enabled by default—use it for ultra-fast temporary storage (caches, build artifacts, temporary processing). Remember: empty ramdisk consumes zero RAM.

---

## Useful Questions

### Can I change the OS after creating a container?

No. The `container_image` is permanent. To use a different OS:
1. [Snapshot](/foundation/containers/snapshots/) your data
2. Create new container with desired image
3. Transfer data via [storage shares](/foundation/storage/sharing-files/) or manual copy
4. Delete old container

### How many containers can I create?

Optionally limited by the `max_containers` quota on your project (unset by default, so there's no per-project cap unless you set one). Get the current quota via `GET /api/v1/projects/{id}`. Free servers cap at 10 containers each. No platform-wide limit—create as many projects as needed.

### What happens if container creation fails?

Status becomes `failed`. Check error via `GET /api/v1/containers/{id}`. Common causes:
- Server out of capacity
- Invalid image name
- Resource quota exceeded
- Network issues

Delete the failed container and try again.

### Can I create containers without hoody_kit?

Yes! Set `hoody_kit: false` for plain Linux containers. **Important limitations:**
- ❌ **No Hoody Proxy** - Container services won't be accessible via HTTP
- ❌ **No Hoody Kit HTTP stack** - No terminal, display, files, exec, etc.
- ✅ **SSH access only** - But ONLY if you provide `ssh_public_key` (defaults to null otherwise)
- ⚠️ **No web access at all** - Without hoody_kit AND without SSH key, container is completely inaccessible

**Use when:** You need minimal overhead, custom service installations, or are managing everything via SSH yourself.

**Recommendation:** Almost always use `hoody_kit: true`. The HTTP services are what make Hoody powerful.

### Do I get charged for stopped containers?

Storage charges apply to stopped containers (they still occupy disk space). CPU/RAM charges stop when container is stopped. Minimize cost: delete unused containers or use minimal storage allocation.

### Can I create containers on multiple servers simultaneously?

Yes. Each container creation is independent. Spawn 100 containers across 10 servers in parallel—all via standard HTTP requests. Common pattern for auto-scaling or testing.

### What's the fastest way to create a container?

Use prespawn templates - pre-created container pools that are claimed in milliseconds (sub-second). Regular creation: 1-5 seconds.

### Can I automate container creation with CI/CD?

Absolutely. Create [auth token](/foundation/hoody-api/authentication/), store as GitHub Secret, use `curl` in workflows. Container creation is just an HTTP POST—works in any CI/CD system.

### How do I know which services are running in my container?

Query with `runtime=true` parameter:
```bash
GET /api/v1/containers/{id}?runtime=true
```

Response shows active services with PIDs, ports, and connection status.

---

## Troubleshooting

### Container Stuck in "creating" Status

**Problem:** Container status remains "creating" for longer than expected

**Typical creation time:** 1-5 seconds (prespawn: sub-second)

**If longer than 2 minutes:**

1. **Check server status:**
   ```bash
   curl "https://api.hoody.icu/api/v1/servers/{server_id}" \
     -H "Authorization: Bearer $HOODY_TOKEN"
   
   # Verify server is "ready", not "maintenance"
   ```

2. **Check server capacity:**
   - Server may be at capacity
   - Try different server_id

3. **Wait and re-check:**
   - Complex images take longer
   - First creation on server takes longer (image pull)
   - Hoody Kit installation adds ~10-15 seconds

4. **If stuck >5 minutes:**
   - Delete and recreate
   - Or contact support with container_id

### Cannot Update Container (400 Error)

**Problem:** Update request returns 400 Bad Request

**Common causes:**

1. **Container is running:**
   ```bash
   # Stop first
   POST /api/v1/containers/{id}/stop
   
   # Then update
   PATCH /api/v1/containers/{id}
   ```

2. **Invalid values:**
   - Name must be unique in project
   - Color must be valid HEX format
   - SSH public key must be unique (can't reuse across containers)
   - realm_ids must be array of valid realm IDs

3. **Immutable fields:**
   - Cannot change `container_image`
   - Cannot change `hoody_kit`
   - Cannot change `server_id`

### Container Creation Fails Immediately

**Problem:** Response shows `status: "failed"` immediately

**Check error details:**

```bash
curl "https://api.hoody.icu/api/v1/containers/{failed_container_id}" \
  -H "Authorization: Bearer $HOODY_TOKEN"

# Look for error message in response
```

**Common issues:**

1. **Invalid image name:**
   ```bash
   # ❌ Wrong: "ubuntu:22.04" or "ubuntu-22.04"
   # ✅ Correct: "ubuntu/24.04" or "debian/13"
   ```

2. **Server quota exceeded:**
   - Server out of CPU/RAM
   - Choose different server

3. **Project quota:**
   ```bash
   # Check project limits
   GET /api/v1/projects/{id}
   # Look at: max_containers
   ```

### Cannot Delete Container

**Problem:** Delete operation fails

**Solutions:**

1. **Stop container first:**
   ```bash
   POST /api/v1/containers/{id}/stop
   
   # Wait for stopped status
   GET /api/v1/containers/{id}
   
   # Then delete
   DELETE /api/v1/containers/{id}
   ```

2. **Remove proxy aliases:**
   ```bash
   # List aliases for container
   GET /api/v1/proxy/aliases?container_id={id}
   
   # Delete each alias
   DELETE /api/v1/proxy/aliases/{alias_id}
   
   # Then delete container
   ```

3. **Check permissions:**
   - Verify you own the container
   - Check you're using correct auth token

### Services Not Accessible After Creation

**Problem:** Container created but service URLs return errors

**Debug steps:**

1. **Verify container is running:**
   ```bash
   GET /api/v1/containers/{id}
   # Check: "status": "running"
   ```

2. **Wait for services to start:**
   - Container may be running but services still initializing
   - Wait 30-60 seconds after `status: "running"`

3. **Check runtime information:**
   ```bash
   GET /api/v1/containers/{id}?runtime=true
   
   # Verify services are listed in runtime_info
   ```

4. **Verify hoody_kit was enabled:**
   ```bash
   GET /api/v1/containers/{id}
   # Check: "hoody_kit": true
   ```

---

## What's Next

**Your container is running:**

1. **[Managing Containers →](./managing/)** - Start, stop, pause, resume operations
2. **[Snapshots →](./snapshots/)** - Backup and restore your container state
3. **[Copy & Sync →](./copy-sync/)** - Duplicate containers across projects/servers

**Configure access and networking:**
- **[Hoody Proxy →](/foundation/proxy/)** - Make services accessible
- **[Network Configuration →](/foundation/networking/network/)** - Proxy/VPN routing
- **[Firewall →](/foundation/networking/firewall/)** - Security rules

**Understanding gained:**
- ✅ Containers are created via HTTP POST
- ✅ Hoody Kit provides the full HTTP service stack automatically
- ✅ Container configuration can be updated (when stopped)
- ✅ Deletion is permanent (snapshot first!)
- ✅ Service URLs follow predictable pattern

---

> **Spawn containers like you spawn URLs.**  
> **Configure them via HTTP.**  
> **Delete them when you're done.**  
> **This is the foundation of infinite computers.**