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.

---

Prespawn

Pre-warm containers so they are ready the instant you need them. Zero cold-start latency.

Server Pools

Share server capacity across team members. Collaborative infrastructure without per-user billing.

Realm Isolation

Scope API visibility by realm. Tokens cannot see resources outside their assigned realm.

Network Routing

Route container traffic through SOCKS5, HTTP proxies, or block outbound entirely. One API call.

Storage Shares

Share directories between containers — readonly or readwrite, same server or cross-server.

Copy & Sync

Clone containers to different servers. Sync copies with source changes incrementally.

Snapshots

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.

CLI

# Create a prespawned container (ready instantly when needed)
hoody containers create \
  --project $PROJECT_ID \
  --server-id $SERVER_ID \
  --name "prespawned" \
  --hoody-kit \
  --prespawn

SDK

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

HTTP

# 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.

CLI

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

# Invite a team member
hoody pools members invite $POOL_ID --username "alice" --role "user"

SDK

// 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'
});

HTTP

# 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 | Servers API

---

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.

CLI

# 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

SDK

// 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();

HTTP

# List containers in a specific realm
curl "https://507f1f77bcf86cd799439011.api.hoody.icu/api/v1/containers" \
  -H "Authorization: Bearer $REALM_TOKEN"

Tip

Realms scope API visibility, not network traffic. For network-level isolation, use Container Network and Firewall configuration.

Deep dive: Realms Concept | Realms Foundation | Realms API

---

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.

CLI

# Route container traffic through a SOCKS5 proxy
hoody network update --container $CONTAINER_ID \
  --type socks5 \
  --proxy "socks5://user:pass@proxy.example.com:1080"

SDK

// 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'
});

HTTP

# 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 | Container Network API

---

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.

CLI

# 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

SDK

// 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/

HTTP

# 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 | Cloud Storage | SQLite Drive | 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.

CLI

# 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

SDK

// 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);

HTTP

# 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 | Copy & Sync API

---

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.

CLI

# 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

SDK

// 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
);

HTTP

# 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"

Caution

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 | Snapshots API

---

What’s Next

• The Hoody Kit — the full HTTP service stack that runs in every container
• Hoody API — platform API overview and authentication
• API Reference — 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.