Share Servers

Pools transform rented servers into team infrastructure.

Instead of managing individual servers, organize them into Pools with role-based access - seamless collaboration for teams of any size.

What Are Pools?

Pools are groups of rented servers with shared access.

Think of a Pool as a container for servers, not containers. When you assign rented servers to a Pool, all members get access based on their role.

Key Concepts:

• Default Pool: Every user has one automatically - all servers go here unless you specify otherwise during rental
• Shared Pools: Created for teams, clients, or organizational units
• Role-Based Access: Owner (the pool creator, implicit), plus two assignable roles — admin and user
• Server Assignment: A server is assigned to a pool when you rent it (via pool_id)
• Container Deployment: Pool members deploy containers to pool servers

API Endpoints Summary

Pool management uses these endpoints:

Pool Management

• GET /api/v1/pools - List your pools
• POST /api/v1/pools - Create new pool
• GET /api/v1/pools/{id} - View pool details
• PUT /api/v1/pools/{id} - Update pool settings
• PATCH /api/v1/pools/{id} - Update pool settings
• DELETE /api/v1/pools/{id} - Delete pool

Pool Invitations

• GET /api/v1/pools/invitations/pending - List your pending invitations
• POST /api/v1/pools/{id}/accept - Accept an invitation (here {id} is the Pool ID — the pool_id returned by the pending-invitations list)
• POST /api/v1/pools/{id}/reject - Decline an invitation (here {id} is the Pool ID — the pool_id returned by the pending-invitations list)

Server Assignment

• Assign server to a pool during rental (pool_id on POST /api/v1/servers/{id}/rent)
• View pool’s servers

For detailed API documentation, see Servers API.

Pool Roles

Only admin and user are assignable via the members API (role enum). Owner is implicit — it’s whoever created the pool — and is not passed as a role string.

Owner (Full Control — pool creator, not assignable)

• Create the pool
• Add/remove members
• Assign servers to the pool at rental time
• Modify pool settings
• Delete the pool — only when it holds no servers and has never held a rental

Admin (Management)

• Add/remove members
• View all pool resources
• Cannot rent servers into the pool, change member roles, modify pool settings, or delete pool (owner only)

User (Access)

• Deploy containers to pool servers
• View pool servers and members
• Cannot modify pool structure

Pool membership does not grant server commands

Server commands are authorized on server ownership, not pool membership: only the account that rents the machine can run them, and only on a dedicated host it actively rents. Free-tier servers, subserver slices and shared hosts are never eligible. Any other pool member — including an Admin — gets 403 No access to this server.

Tip

Best Practice: Give developers “User” role for deploying containers. Reserve “Admin” for DevOps team members who manage infrastructure.

Creating a Pool

1. Create the Pool

   CLI

   # Create a team pool
   hoody pools create \
     --name "Frontend Team Pool" \
     --description "Shared servers for frontend development"
   
   # Invite a team member
   hoody pools members invite $POOL_ID \
     --username "$USERNAME" \
     --role "user"
   
   # List your pools
   hoody pools list

   SDK

   import { HoodyClient } from 'hoody-sdk';
   
   const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });
   
   // Create a team pool
   const pool = await client.api.pools.create({
     name: 'Frontend Team Pool',
     description: 'Shared servers for frontend development',
   });
   
   // Invite a member (by username)
   await client.api.poolMembers.invite(pool.data.id, {
     username: 'teammate_handle',
     role: 'user',
   });
   
   // List pools
   const pools = await client.api.pools.list();

   HTTP

   # Create a team pool
   curl -X POST "https://api.hoody.icu/api/v1/pools" \
     -H "Authorization: Bearer $HOODY_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Frontend Team Pool",
       "description": "Shared servers for frontend development"
     }'
   
   # Invite a member
   curl -X POST "https://api.hoody.icu/api/v1/pools/$POOL_ID/members" \
     -H "Authorization: Bearer $HOODY_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"username": "teammate_handle", "role": "user"}'

2. Invite Team Members

   Add members with appropriate roles. Invited users find pending invitations via GET /api/v1/pools/invitations/pending (or the dashboard) and accept with POST /api/v1/pools/{id}/accept (or decline with POST /api/v1/pools/{id}/reject).

3. Assign Servers

   When renting servers, specify the pool:

   {
     "pool_id": "507f1f77bcf86cd799439011",
     "rental_days": 30,
     "max_charge_cents": 27500
   }

   max_charge_cents is required on every paid rental. Read pricing.price_tiers[rental_days].total_first_payment, which is a decimal-dollar string, and convert it to integer cents ("275.00" → 27500).

   A server’s pool is set at rental time, and pool_id must name a pool you own. To place servers in different pools, rent each one directly into the pool you want by passing its pool_id. Only the pool’s owner can rent into it, so a shared team pool is stocked by its owner.

4. Team Starts Deploying

   All pool members can now deploy containers to pool servers based on their role permissions.

Pool Organization Strategies

By Team/Department

Development Pool, QA Pool, DevOps Pool

• Each team manages their own servers
• Clear resource ownership
• Budget tracking per team

By Client/Project

Client A Pool, Client B Pool, Client C Pool

• Perfect for agencies and consultancies
• Complete client data isolation
• Transparent per-client billing

By Environment

Production Pool, Staging Pool, Development Pool

• Separate environments by security level
• Different access rules per pool
• Clear separation of concerns

Note

Note on Environment Separation: Since containers are fully isolated, it’s perfectly safe to run development and production containers on the same server. All execution happens within containers, not on the host. However, separating environments across different servers/pools adds an additional layer of obfuscation and organizational clarity, which is generally beneficial for larger teams and regulated industries.

Hybrid Approach

Most teams use combinations:

Production Pool (3 servers)
  → Owner: CTO
  → Admins: Senior DevOps (2)
  → Users: Backend team (8)

Client Projects Pool (5 servers)
  → Owner: Account Manager
  → Admins: Project Leads (3)
  → Users: Developers (12)

AI Experiments Pool (2 servers)
  → Owner: AI Lead
  → Admins: ML Engineers (4)
  → Users: Whole company (open access)

Member Management

Adding Members

CLI

# Invite a user to a pool
hoody pools members invite $POOL_ID \
  --username "$USERNAME" \
  --role "user"

# Update a member's role (positional pool ID and user ID)
hoody pools members update-role $POOL_ID $USER_ID \
  --role "admin"

# Remove a member (--yes skips the confirmation prompt)
hoody pools members delete $POOL_ID $USER_ID --yes

SDK

import { HoodyClient } from 'hoody-sdk';

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

// Invite a user to a pool (by username)
await client.api.poolMembers.invite(poolId, {
  username: 'teammate_handle',
  role: 'user',
});

// Update member role
await client.api.poolMembers.updateRole(poolId, userId, {
  role: 'admin',
});

// Remove a member
await client.api.poolMembers.remove(poolId, userId);

HTTP

# Invite a user to a pool
curl -X POST "https://api.hoody.icu/api/v1/pools/$POOL_ID/members" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "teammate_handle", "role": "user"}'

# Update member role (role must be "admin" or "user")
curl -X PUT "https://api.hoody.icu/api/v1/pools/$POOL_ID/members/$USER_ID" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

# Remove a member
curl -X DELETE "https://api.hoody.icu/api/v1/pools/$POOL_ID/members/$USER_ID" \
  -H "Authorization: Bearer $HOODY_TOKEN"

Member accepts invitation (POST /api/v1/pools/{id}/accept) → Immediately gains pool access

Roles and Permissions

What each role can do:

Action	Owner	Admin	User
View pool servers	Yes	Yes	Yes
Deploy containers	Yes	Yes	Yes
Add members	Yes	Yes	No
Remove members	Yes	Yes	No
Change member role	Yes	No	No
Assign servers (rent into this pool)	Yes	No	No
Change pool settings	Yes	No	No
Delete pool	Yes	No	No

Removing Members

Members can be removed anytime:

• Their containers on pool servers remain
• They lose access to deploy new containers
• Existing containers can be reassigned or deleted

Server Assignment

During Rental

Every server is assigned to a pool. You can specify which pool, or it defaults to your personal pool.

Specify a pool:

{
  "pool_id": "507f1f77bcf86cd799439011",
  "rental_days": 30,
  "max_charge_cents": 27500
}

Omit pool (uses default):

{
  "rental_days": 30,
  "max_charge_cents": 27500
}
// Automatically assigned to your default pool

max_charge_cents is required on every paid rental. Read pricing.price_tiers[rental_days].total_first_payment, which is a decimal-dollar string, and convert it to integer cents ("275.00" → 27500).

Server immediately accessible to all pool members based on their roles.

Choosing the Pool

A server’s pool is chosen when you rent it, and a rented server can only be attached to a pool you own. Passing a pool you merely belong to — even as an Admin — returns 403 ACCESS_DENIED. So the owner of a shared team pool is the one who rents servers into it; other members rent into their own pools. There is no public endpoint to move an existing server between pools.

Use Cases:

• The pool owner rents into the shared team pool so the whole team has access immediately
• Rent a testing server into a dedicated staging pool you own
• Rent client work into a per-client pool for isolation

Pool Settings

Each pool carries a free-form settings JSON object that you can set at creation and update later. It defaults to an empty object and accepts arbitrary keys.

Hoody stores and returns settings unchanged — nothing on the platform interprets or enforces its contents. It is metadata for your own tooling, not a place to configure caps or approval workflows.

{
  "settings": {
    "owning_team": "frontend",
    "cost_center": "R&D-114"
  }
}

The only rules Hoody applies are structural: settings must be a JSON object (not an array), and both its serialized size and its nesting depth are capped — exceed either and the create/update returns 400 with field: "pool_settings".

Use Cases

Small Development Team

• Create “Dev Team Pool”
• Rent server(s) and assign to pool
• All developers deploy to shared infrastructure
• Team collaboration on shared resources
• Cost-effective team development

Digital Agency (Multiple Clients)

• Create pool per client for perfect isolation
• Rent servers and assign to respective client pools
• Complete data separation between clients
• Transparent per-client billing
• Rent new servers into client pools as clients come and go

Enterprise Multi-Team

• Create pools by department or function
• Rent multiple servers per pool as needed
• Role-based access across pools
• Developers can be members of multiple pools
• Clear budget and resource tracking

Open Source Project

• Create “Community Pool”
• Rent server(s), add all contributors as Users
• Everyone can deploy demos and test branches
• Owner maintains production deployments
• Shared infrastructure costs across contributors

Freelancer → Agency Transition

• Start with default pool (personal servers)
• First client: Create “Client Pool”, assign server
• Additional clients: Create additional pools
• Hire developers: Add them to client pools as needed
• Scale smoothly from solo to team

Multi-Pool Access

Users can be members of multiple pools:

Developer Jane:
  → "Frontend Pool" (User) - Can deploy frontend containers
  → "Staging Pool" (Admin) - Manages staging infrastructure
  → "AI Experiments" (User) - Access to AI playground

Benefits:

• Cross-team collaboration without friction
• Flexible access as responsibilities evolve
• Clear audit trail of who can access what

Best Practices

Pool Design:

• Create pools for logical boundaries (team, client, environment)
• Don’t create pool per server (defeats the purpose)
• Name pools clearly - teams grow and members forget context

Role Assignment:

• Start everyone as “User”, promote to “Admin” as needed
• Owners should be team leads or managers
• Audit roles quarterly - people change responsibilities

Server Organization:

• Group related work on same servers
• Production servers in strict-access pools
• Development servers in open-access pools
• Scale servers together logically (e.g., 3 prod servers in prod pool)

Security:

• Separate production and development pools
• Remember that server commands stay with the renter — pool roles never widen them
• Review pool membership regularly
• Remove members promptly when they leave team/project

Cost Management:

• Use pools to track infrastructure costs per team/client
• Pool-level usage monitoring
• Transparent billing: each pool shows total server costs
• Delete pools that never held a rental to clean up (a pool with rental history is permanent)

Useful Questions

Can members see each other’s containers?

Pool members see that containers exist on pool servers, but privacy depends on container permissions. By default, containers are isolated. Use container permissions to control access.

What happens when I delete a pool?

A pool can only be deleted when it is empty. Any server currently assigned to it, any past rental row referencing it, or any pending paid server reservation naming it as the delivery destination blocks deletion — rental rows reference a pool permanently, so a pool that has ever held a rental can never be deleted. Only the owner may delete a pool, and the default pool can never be deleted.

Can a server be in multiple pools?

No, each server belongs to exactly one pool. A server’s pool is chosen when you rent it via pool_id.

Do pool members share container limits?

Container limits are per-server and per-project, not per-user. A server can carry an operator-set max_containers (10 on a free-tier slice; unset means unlimited on a rented machine), and that count includes every member’s containers on that host — so on a capped server, pool members do share one set of slots. Projects can carry their own max_containers on top of that.

Can I change a member’s role after adding them?

Yes. Changing a member’s role (PUT /api/v1/pools/{id}/members/{userId}) is restricted to the pool owner — admins can invite and remove members, but only the owner can promote or demote roles. Changes take effect immediately.

What if a pool member leaves the organization?

Remove them from the pool via API or dashboard. Their containers remain on pool servers but they lose all access. You can then delete their containers or reassign to other members.

Can I limit which servers in a pool a member can access?

Not directly per server, but you can create separate pools with different server groups and add members to specific pools based on their needs.

Troubleshooting

Can’t Add Member to Pool

Cause: Unknown username, or member already in pool

Solution: Verify the username exists exactly as registered. Check the existing member list - inviting a user who is already a member returns a conflict, so you can’t add the same user twice.

Member Can’t Deploy Containers to Pool Servers

Cause: Role doesn’t grant deployment permission, or server resource limits

Solution: Verify member has “User” role or higher. Check server resource availability. Ensure member’s container quota not exhausted.

Server Assignment Fails

Cause: Invalid pool_id, or the target pool is not yours

Solution: A server’s pool is set at rental time via pool_id on POST /api/v1/servers/{id}/rent. Verify the pool_id is a valid 24-character hex ID and that you own that pool. A rented server can only be attached to a pool you own — passing a pool you merely belong to, even as an Admin, returns 403 ACCESS_DENIED. Rent into your own pool instead.

Pool Deletion Blocked

Cause: You aren’t the owner, or the pool isn’t empty

Solution: Verify you’re the pool owner - only the owner may delete a pool. Beyond that, a pool can only be deleted when it is empty: any server currently assigned to it, any past rental row referencing it, or any pending paid server reservation naming it blocks deletion, and the default pool can never be deleted. To remove a member from a pool, use DELETE /api/v1/pools/{id}/members/{userId} (admin or owner).

Member Can’t Accept Pool Invitation

Cause: Member is looking in the wrong place, or the invitation was already removed

Solution: Invitations are not delivered by email — the invited user finds them via GET /api/v1/pools/invitations/pending (or the dashboard) and accepts with POST /api/v1/pools/{id}/accept. Verify you invited the correct username, and that you haven’t since removed the member (which clears the pending invitation).

What’s Next

Ready to organize your infrastructure?

• Rent Servers → - Get servers to add to pools
• Servers API → - Complete pools API reference

Set up team workflows:

• Projects & Containers → - Understand container deployment
• Proxy Permissions → - Control container access

Collaboration features:

• Container Copy/Sync → - Share containers between servers
• Storage Shares → - Shared files across pool containers