# Advanced Features

**Page:** foundation/advanced

[Download Raw Markdown](./foundation/advanced.md)

---

# Advanced Features

**You have containers. You have HTTP services. Now what?**

The basics of Hoody -- spawn a container, access it via URL, run whatever you want -- cover 80% of use cases. This page is about the other 20%. The infrastructure patterns that separate "I deployed an app" from "I built a platform."

Prespawn pools that eliminate cold starts. Realm isolation that makes multi-tenancy trivial. Snapshot branching that gives you Git-style version control for entire computers. Storage shares that let containers collaborate without duplicating data. Network routing that changes a container's exit IP with one API call.

Each section below gives you the concept, a quick example, and a link to the deep dive. Think of this as your map to the power-user features.

---


  
    Pre-warm containers so they are ready the instant you need them. Zero cold-start latency.
  
  
    Share server capacity across team members. Collaborative infrastructure without per-user billing.
  
  
    Scope API visibility by realm. Tokens cannot see resources outside their assigned realm.
  
  
    Route container traffic through SOCKS5, HTTP proxies, or block outbound entirely. One API call.
  
  
    Share directories between containers -- readonly or readwrite, same server or cross-server.
  
  
    Clone containers to different servers. Sync copies with source changes incrementally.
  
  
    Capture complete container state. Restore to any point in time. Branch infrastructure like Git.
  


---

## Prespawn System

**Cold starts kill latency-sensitive applications.** A container takes 20-30 seconds to provision. For an on-demand SaaS, a webhook handler, or an AI agent launcher, that is 20-30 seconds too many.

Prespawn fixes this. You define a template -- base image, resource limits, Kit configuration -- and Hoody keeps a pool of containers pre-created and ready. When you need one, it is assigned instantly. No boot time. No provisioning delay.


  
    ```bash
    # Create a prespawned container (ready instantly when needed)
    hoody containers create \
      --project $PROJECT_ID \
      --server-id $SERVER_ID \
      --name "prespawned" \
      --hoody-kit \
      --prespawn
    ```
  
  
    ```typescript
    import { HoodyClient } from '@hoody-ai/hoody-sdk';

    const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });

    // Create a prespawned container (ready instantly when needed)
    await client.api.containers.create(PROJECT_ID, {
      server_id: SERVER_ID,
      name: 'prespawned',
      hoody_kit: true,
      prespawn: true
    });

    // Container is pre-warmed and assigned from the pool instantly
    ```
  
  
    ```bash
    # Create a prespawned 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 '{
        "server_id": "'"$SERVER_ID"'",
        "name": "prespawned",
        "hoody_kit": true,
        "prespawn": true
      }'
    ```
  


---

## Server Pools

**One server, multiple users.** Server pools let you share bare metal capacity across team members without giving everyone root access to the host. Create a pool, invite members, and everyone can spawn containers on shared hardware.


  
    ```bash
    # Create a server pool
    hoody pools create --name "engineering-team"

    # Invite a team member
    hoody pools members invite $POOL_ID --username "alice" --role "user"
    ```
  
  
    ```typescript
    // Create a pool and invite team members
    const pool = await client.api.pools.create({ name: 'engineering-team' });

    await client.api.poolMembers.invite(pool.data.id, {
      username: 'alice',
      role: 'user'
    });
    ```
  
  
    ```bash
    # Create a server pool
    curl -X POST "https://api.hoody.icu/api/v1/pools" \
      -H "Authorization: Bearer $HOODY_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"name": "engineering-team"}'
    ```
  


**Deep dive:** [Server Management](/foundation/servers/) | [Servers API](/api/servers/)

---

## Multi-Realm Isolation

**Realm-restricted tokens cannot even see resources outside their realm.** Not "access denied" -- the resources do not exist in their API universe. This is the foundation for multi-tenant isolation, environment separation, and AI agent sandboxing.


  
    ```bash
    # Create a realm-restricted token for staging
    hoody auth create \
      --alias "ci-staging" \
      --realm-ids "507f1f77bcf86cd799439011" \
      --no-allow-no-realm

    # This token can only operate on the realm-scoped host
    hoody --base-url "https://507f1f77bcf86cd799439011.api.hoody.icu" \
      containers list
    ```
  
  
    ```typescript
    // Create realm-restricted token
    const token = await client.api.authTokens.create({
      alias: 'ci-staging',
      realm_ids: ['507f1f77bcf86cd799439011'],
      allow_no_realm: false
    });

    // Use realm-scoped client
    const realmClient = new HoodyClient({
      baseURL: 'https://507f1f77bcf86cd799439011.api.hoody.icu',
      token: token.data.token
    });

    // Only sees staging resources
    const containers = await realmClient.api.containers.list();
    ```
  
  
    ```bash
    # List containers in a specific realm
    curl "https://507f1f77bcf86cd799439011.api.hoody.icu/api/v1/containers" \
      -H "Authorization: Bearer $REALM_TOKEN"
    ```
  



Realms scope API visibility, not network traffic. For network-level isolation, use [Container Network](/foundation/networking/network/) and [Firewall](/foundation/networking/firewall/) configuration.


**Deep dive:** [Realms Concept](/concepts/realms-projects/) | [Realms Foundation](/foundation/hoody-api/realms/) | [Realms API](/api/realms/)

---

## Container Network Configuration

**Change where your container's traffic exits the internet -- without touching anything inside the container.** Route all outbound TCP through a SOCKS5 proxy, an HTTP proxy, or block outbound traffic entirely. The container does not know. It just works.


  
    ```bash
    # Route container traffic through a SOCKS5 proxy
    hoody network update --container $CONTAINER_ID \
      --type socks5 \
      --proxy "socks5://user:pass@proxy.example.com:1080"
    ```
  
  
    ```typescript
    // Route through SOCKS5
    await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
      type: 'socks5',
      proxy: 'socks5://user:pass@proxy.example.com:1080'
    });

    // Or block all outbound traffic
    await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
      type: 'block'
    });
    ```
  
  
    ```bash
    # Route container through SOCKS5 proxy
    curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network" \
      -H "Authorization: Bearer $HOODY_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "socks5",
        "proxy": "socks5://user:pass@proxy.example.com:1080"
      }'
    ```
  


**Deep dive:** [Network Configuration](/foundation/networking/network/) | [Container Network API](/api/container-network/)

---

## Storage Shares

**Share a directory from one container to others -- automatically works across servers.** Source controls what is shared and the access mode. Target controls whether to mount it. Readonly for config distribution. Readwrite for collaboration.


  
    ```bash
    # Share a directory with another container (readonly)
    hoody storage create --container $SOURCE_CONTAINER_ID \
      --source-path "/hoody/storage/shared-assets" \
      --target-container-id $TARGET_CONTAINER_ID \
      --mode readonly

    # Share with an entire project (all containers)
    hoody storage create --container $SOURCE_CONTAINER_ID \
      --source-path "/hoody/storage/config" \
      --target-project-id $PROJECT_ID \
      --mode readonly
    ```
  
  
    ```typescript
    // Share directory with another container
    await client.api.storageShares.create(SOURCE_CONTAINER_ID, {
      source_path: '/hoody/storage/shared-assets',
      target_container_id: TARGET_CONTAINER_ID,
      mode: 'readonly',
      alias: 'assets'
    });

    // Target sees files at /hoody/shares/assets/
    ```
  
  
    ```bash
    # Create a storage share
    curl -X POST "https://api.hoody.icu/api/v1/containers/$SOURCE_CONTAINER_ID/storage/shares" \
      -H "Authorization: Bearer $HOODY_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "source_path": "/hoody/storage/shared-assets",
        "target_container_id": "'"$TARGET_CONTAINER_ID"'",
        "mode": "readonly",
        "alias": "assets"
      }'
    ```
  


**Deep dive:** [Shared Storage](/foundation/storage/sharing-files/) | [Cloud Storage](/foundation/storage/cloud/) | [SQLite Drive](/foundation/storage/sqlite-drive/) | [Ramdisk](/foundation/storage/ramdisk/)

---

## Container Copy & Sync

**Clone a container to a different server in minutes. Sync incremental changes in seconds.** Copy gives you a full independent duplicate -- different server, different project, same state. Sync keeps the copy updated without re-copying everything.


  
    ```bash
    # Copy production container to EU server for geographic redundancy
    hoody containers copy $PROD_CONTAINER_ID \
      --target-project-id $PROJECT_ID \
      --target-server-id $EU_SERVER_ID \
      --name "prod-eu-replica"

    # Later: sync the copy with production changes
    hoody containers sync $EU_COPY_ID
    ```
  
  
    ```typescript
    // Copy to different server
    const copy = await client.api.containers.copy(PROD_CONTAINER_ID, {
      target_project_id: PROJECT_ID,
      target_server_id: EU_SERVER_ID,
      name: 'prod-eu-replica'
    });

    // Sync incrementally (only changes transferred)
    await client.api.containers.sync(copy.data.id);
    ```
  
  
    ```bash
    # Copy container to EU server
    curl -X POST "https://api.hoody.icu/api/v1/containers/$PROD_ID/copy" \
      -H "Authorization: Bearer $HOODY_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "target_project_id": "'"$PROJECT_ID"'",
        "target_server_id": "'"$EU_SERVER_ID"'",
        "name": "prod-eu-replica"
      }'

    # Sync copy with source changes
    curl -X POST "https://api.hoody.icu/api/v1/containers/$EU_COPY_ID/sync" \
      -H "Authorization: Bearer $HOODY_TOKEN"
    ```
  


**Deep dive:** [Copy & Sync](/foundation/containers/copy-sync/) | [Copy & Sync API](/api/container-copy-sync/)

---

## Snapshot Management

**Capture the complete filesystem state of a container -- and restore to that exact moment in seconds.** Snapshots are copy-on-write, so they cost almost nothing to create. Use them before every risky change, every deployment, every AI experiment.


  
    ```bash
    # Snapshot before a risky change
    hoody snapshots create -c $CONTAINER_ID \
      --alias "before-ai-refactor"

    # Something broke? Restore in seconds
    hoody snapshots restore -c $CONTAINER_ID \
      --name "snap-20260325-143045"

    # List all snapshots
    hoody snapshots list -c $CONTAINER_ID
    ```
  
  
    ```typescript
    // Create snapshot before deployment
    const snapshot = await client.api.containers.createSnapshot(CONTAINER_ID, {
      alias: 'pre-deploy-v2.1',
      expiry: 30 // auto-delete after 30 days
    });

    // Deployment failed? Restore
    await client.api.containers.restoreSnapshot(
      CONTAINER_ID,
      snapshot.data.snapshot.name
    );
    ```
  
  
    ```bash
    # Create a snapshot
    curl -X POST "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/snapshots" \
      -H "Authorization: Bearer $HOODY_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"alias": "pre-deploy-v2.1", "expiry": 30}'

    # Restore from snapshot
    curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/snapshots/snap-20260325-143045" \
      -H "Authorization: Bearer $HOODY_TOKEN"
    ```
  



Restoration is destructive -- current container state is replaced by the snapshot state. If you want to preserve the current state, create a snapshot before restoring.


**Deep dive:** [Snapshots](/foundation/containers/snapshots/) | [Snapshots API](/api/container-snapshots/)

---

## What's Next

- [The Hoody Kit](/kit/) -- the full HTTP service stack that runs in every container
- [Hoody API](/foundation/hoody-api/) -- platform API overview and authentication
- [API Reference](/api/authentication/) -- complete endpoint documentation

---

> **These are not edge cases. These are the tools that turn containers into a platform.**
> **Prespawn eliminates cold starts. Realms eliminate blast radius. Snapshots eliminate fear.**
> **The basics get you running. The advanced features let you build empires.**