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
• 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
• POST /api/v1/pools/{id}/reject - Decline an invitation

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 and delete the pool
• Add/remove members
• Assign servers to the pool at rental time
• Modify pool settings
• Delete pool (removes access, keeps servers)

Admin (Management)

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

User (Access)

• Deploy containers to pool servers
• View pool servers and members
• Execute allowed server commands
• Cannot modify pool structure

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-ai/hoody-sdk';
   
   const client = new HoodyClient({ baseURL: 'https://api.hoody.com', 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.com/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.com/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
   }

   A server’s pool is set at rental time. To place an existing server in a different pool, rent it into that pool.

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-ai/hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', 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.com/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.com/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.com/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	✅	✅	✅
Deploy containers	✅	✅	✅
Add members	✅	✅	❌
Remove members	✅	✅	❌
Change member role	✅	❌	❌
Assign servers	✅	✅	❌
Change pool settings	✅	❌	❌
Delete pool	✅	❌	❌

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
}

Omit pool (uses default):

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

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

Choosing the Pool

A server’s pool is chosen when you rent it. To share a server with a team, rent it directly into the team pool by passing that pool’s pool_id:

Use Cases:

• Rent into a shared team pool so the whole team has access immediately
• Rent a testing server into a dedicated staging pool
• 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. Commonly used keys include:

max_servers - Cap on how many servers the pool holds

{
  "settings": {
    "auto_approve": true,
    "max_servers": 20
  }
}

auto_approve - Whether assigned servers are accepted into the pool without an explicit approval step

Because settings is stored as opaque JSON, you can include additional organizational metadata your team relies on.

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
• Limit who can execute risky server commands
• 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 with no active servers to clean up

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?

Only the owner may delete a pool, and the default pool cannot be deleted. Deleting a pool removes the organizational grouping; your rented servers and their containers are billed and managed independently of the pool grouping.

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?

No, container limits are per-user, not per-pool. Each member can deploy their quota of containers to pool servers regardless of what others deploy.

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 you lack access to the target pool

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 are a member (Owner/Admin) of the target pool.

Pool Deletion Blocked

Cause: Only owners can delete pools

Solution: Verify you’re the pool owner. Only the owner may delete a pool, and the default pool cannot 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