Network Configuration

Change where your container’s traffic exits to the internet. Route through SOCKS5/HTTP/HTTPS proxies, or block all outbound traffic—with zero configuration inside the container.

API Endpoints Summary

Complete endpoint documentation:

GET /api/v1/containers/{id}/network - Get current network config
PATCH /api/v1/containers/{id}/network - Configure proxy/VPN/block mode
DELETE /api/v1/containers/{id}/network - Remove config (restore default)
POST /api/v1/containers/{id}/network/start - Start container network proxy/blocking
POST /api/v1/containers/{id}/network/stop - Stop container network proxy/blocking

Two Different “Proxies” on Hoody

⚠️ CRITICAL: Don’t confuse these two systems:

System	Direction	Purpose
Hoody Proxy	Internet → Container	Makes services accessible via URLs
Network Configuration (this page)	Container → Internet	Changes exit IP address

Key distinction:

Hoody Proxy = How others ACCESS your containers (inbound)
Network Configuration = How your container ACCESSES the internet (outbound)

Both work together. Hoody Proxy handles inbound service requests. Network Configuration handles outbound connections.

Four Routing Types

1. SOCKS5 Proxy (Recommended)

Routes ALL TCP traffic through SOCKS5:

# Route all container traffic through SOCKS5 proxy
hoody network update --container $CONTAINER_ID \
  --type socks5 \
  --proxy "socks5://username:password@proxy.example.com:1080" \
  --dns-servers "1.1.1.1,1.0.0.1"

await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
  type: 'socks5',
  proxy: 'socks5://username:password@proxy.example.com:1080',
  dns_servers: ['1.1.1.1', '1.0.0.1'],
});

curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "socks5",
    "proxy": "socks5://username:password@proxy.example.com:1080",
    "dns_servers": ["1.1.1.1", "1.0.0.1"]
  }'

What happens:

All container TCP connections route through SOCKS5 proxy
Container appears to originate from proxy’s IP
Supports authentication (username:password)

Why SOCKS5 is best:

Natively forwards ANY TCP protocol without CONNECT tunneling
SSH, databases, Git, custom protocols all work
Many providers (including VPN services) offer SOCKS5 with credentials
Zero in-container configuration needed

2. HTTP Proxy

# Route container traffic through HTTP proxy
hoody network update --container $CONTAINER_ID \
  --type http \
  --proxy "http://user:pass@corporate-proxy.com:8080"

await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
  type: 'http',
  proxy: 'http://user:pass@corporate-proxy.com:8080',
});

curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "http",
    "proxy": "http://user:pass@corporate-proxy.com:8080"
  }'

Use for: Corporate proxy requirements, environments that mandate an HTTP forward proxy

Note: type: http configures the upstream as an HTTP proxy. Hoody still DNATs all container TCP egress through it (using the proxy’s CONNECT tunneling for non-HTTP destinations), so this isn’t limited to plain HTTP payloads. SOCKS5 remains the most broadly compatible upstream.

3. HTTPS Proxy

# Route container traffic through HTTPS proxy
hoody network update --container $CONTAINER_ID \
  --type https \
  --proxy "https://user:pass@secure-proxy.com:443"

await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
  type: 'https',
  proxy: 'https://user:pass@secure-proxy.com:443',
});

curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "https",
    "proxy": "https://user:pass@secure-proxy.com:443"
  }'

Use for: Encrypted HTTP proxy connections

Note: type: https configures the upstream as an HTTPS proxy (CONNECT tunneling); all TCP egress is DNATed through it just as with the http type, so this isn’t restricted to HTTPS payloads.

4. Block (Complete Isolation)

# Block all outbound internet traffic
hoody network update --container $CONTAINER_ID --type block

await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
  type: 'block',
});

curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "block"}'

Blocks all outbound internet. Container can still:

✅ Be accessed via Hoody Proxy URLs (terminal, files, display)
✅ Access localhost services and /ramdisk
❌ Make ANY outbound connections

Perfect for running untrusted code or processing sensitive data.

Host-Level Routing Power

Traditional approach: Configure proxy inside every application:

export HTTP_PROXY=http://proxy:8080
npm config set proxy http://proxy:8080
git config http.proxy http://proxy:8080
# Every single application needs configuration

Hoody approach: One API call, affects ALL applications:

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

await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
  type: 'socks5',
  proxy: 'socks5://user:pass@proxy.example.com:1080',
});

curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "socks5",
    "proxy": "socks5://user:pass@proxy.example.com:1080"
  }'

Now all applications automatically route through SOCKS5: npm downloads, curl requests, Python/Node.js/Go apps, SSH connections, database connections—zero in-container configuration.

Benefits:

Universal routing (every TCP protocol)
Zero application configuration
Tamper-proof (container cannot bypass)
Easy VPN provider switching

Common Use Cases

Change Exit IP for Geo-Restricted APIs

Server in Germany, but API requires US IP:

# Route through US proxy for geo-restricted APIs
hoody network update --container $CONTAINER_ID \
  --type socks5 \
  --proxy "socks5://user:pass@us-proxy.example.com:1080"

await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
  type: 'socks5',
  proxy: 'socks5://user:pass@us-proxy.example.com:1080',
});

curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "socks5",
    "proxy": "socks5://user:pass@us-proxy.example.com:1080"
  }'

Container requests appear to originate from the proxy’s location.

Route Through Corporate Proxy

# Route through corporate HTTP proxy for compliance
hoody network update --container $CONTAINER_ID \
  --type http \
  --proxy "http://employee:pass@corporate-proxy.com:8080"

await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
  type: 'http',
  proxy: 'http://employee:pass@corporate-proxy.com:8080',
});

curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "http",
    "proxy": "http://employee:pass@corporate-proxy.com:8080"
  }'

All HTTP traffic logged by corporate proxy for compliance.

Secure AI Code Sandbox

# Block all outbound traffic for AI sandbox
hoody network update --container $CONTAINER_ID --type block

await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
  type: 'block',
});

curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "block"}'

AI-generated code cannot:

Call external APIs
Download malicious packages
Exfiltrate data

Even if compromised, it’s isolated.

Multi-Region Testing

Spawn containers with different exit IPs to test from multiple regions simultaneously:

PATCH Configure US region proxy

/api/v1/containers/{container_id}/network

Click "Run" to execute the request

PATCH Configure EU region proxy

/api/v1/containers/{container_id}/network

Click "Run" to execute the request

PATCH Configure Asia region proxy

/api/v1/containers/{container_id}/network

Click "Run" to execute the request

Test your API from multiple regions simultaneously.

Network + Firewall + Permissions

Three-layer defense for complete traffic control:

Step 1: Route through VPN:

PATCH Route all traffic through VPN

/api/v1/containers/{container_id}/network

Click "Run" to execute the request

Step 2: Only allow HTTPS through VPN (firewall):

POST Allow HTTPS traffic (port 443)

/api/v1/containers/{container_id}/firewall/egress

Click "Run" to execute the request

POST Block all other TCP traffic

/api/v1/containers/{container_id}/firewall/egress

Click "Run" to execute the request

Result: Traffic routes through VPN, but only HTTPS permitted by firewall.

Three-layer security:

Layer	Controls	Page
Network Config	Exit IP routing (outbound)	This page
Firewall	Packet filtering (ingress/egress)	Firewall →
Proxy Permissions	HTTP service access (inbound)	Permissions →

Layer all three for defense-in-depth.

Managing Network Configuration

Get Current Config

# View current network configuration
hoody network get --container $CONTAINER_ID

const config = await client.api.containers.getNetworkConfig(CONTAINER_ID);
console.log(config.data); // { type, proxy, dns_servers, status, remote_status }

curl "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network" \
  -H "Authorization: Bearer $TOKEN"

Remove Config (Restore Default)

# Remove network config, restore direct connection
hoody network delete --container $CONTAINER_ID

await client.api.containers.removeNetworkConfig(CONTAINER_ID);

curl -X DELETE "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network" \
  -H "Authorization: Bearer $TOKEN"

Start / Stop Network Proxy

# Start network proxy/blocking
hoody network start --container $CONTAINER_ID

# Stop network proxy/blocking
hoody network stop --container $CONTAINER_ID

// Start network proxy/blocking
await client.api.containers.startNetwork(CONTAINER_ID);

// Stop network proxy/blocking
await client.api.containers.stopNetwork(CONTAINER_ID);

# Start network proxy/blocking
curl -X POST "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network/start" \
  -H "Authorization: Bearer $TOKEN"

# Stop network proxy/blocking
curl -X POST "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network/stop" \
  -H "Authorization: Bearer $TOKEN"

Verify Exit IP

Test from inside container:

# Via hoody-terminal
curl ifconfig.me

# Should show VPN IP, not server IP

Best Practices

1. Use SOCKS5 for Universal Routing

Hoody DNATs all container TCP egress regardless of proxy type, but a SOCKS5 upstream natively forwards ANY TCP protocol (SSH, databases, custom protocols) without relying on CONNECT tunneling. Use SOCKS5 unless your environment specifically requires an HTTP/HTTPS forward proxy.

2. Test Config Before Production

Test in dev container first:

PATCH Test proxy configuration in dev container

/api/v1/containers/{container_id}/network

Click "Run" to execute the request

Verify exit IP with curl ifconfig.me from inside the container, test app connectivity, then apply to production.

3. Document Your Routing

# ✅ Good comment
{"comment": "UK VPN for BBC API - geo-restricted content"}

# ❌ Vague comment
{"comment": "vpn"}

4. Combine with Firewall for Defense-in-Depth

Route through VPN + restrict allowed destinations = complete traffic control.

Useful Questions

Does Network Configuration affect container service URLs?

No. Hoody Proxy service URLs (terminal, files, display) remain accessible. Network Config only affects outbound connections FROM the container.

What happens if SOCKS5 proxy goes down?

Container cannot make outbound connections. Update config with different proxy or DELETE /network to revert to direct connection.

Can I use multiple proxies simultaneously?

One proxy per container via Network Configuration. For multi-hop, configure first SOCKS5 via Network Config, then run second SOCKS5 client inside container. Or spawn multiple containers, each with different proxy.

Does this work with WireGuard or OpenVPN?

Not yet—currently supports SOCKS5/HTTP/HTTPS proxy routing only. WireGuard routing is planned for a future update. Many VPN providers offer SOCKS5 endpoints as an alternative.

Do changes require container restart?

No. Changes apply immediately to new connections. Existing connections may continue using old route.

Can containers communicate with each other in `block` mode?

Yes—via Hoody Proxy service URLs (HTTP-based). Block mode prevents outbound INTERNET connections, not container-to-container communication.

Troubleshooting

Cannot Access Internet After Configuring VPN

Solutions:

Verify network service running: GET /containers/{id}/network → check "status": "running"
Test proxy from host: curl --proxy socks5://user:pass@vpn.com:1080 https://ifconfig.me
Check proxy URL format: socks5://username:password@host:port
Remove config and test direct: DELETE /containers/{id}/network

DNS Resolution Fails

Solutions:

Configure custom DNS:

PATCH Configure SOCKS5 with custom DNS servers

/api/v1/containers/{container_id}/network

Click "Run" to execute the request

Ensure firewall allows DNS:

POST Allow DNS traffic (UDP port 53)

/api/v1/containers/{container_id}/firewall/egress

Click "Run" to execute the request

Proxy Authentication Fails

Check:

Credentials correct
Special characters URL-encoded (@ = %40, : = %3A)
VPN subscription active
Test from host: curl --proxy socks5://user:pass@vpn.com:1080 https://ifconfig.me

Exit IP Not Changing

Verify:

Network service running: GET /network → check remote_status.is_running is true (or status is running)
Test from container: curl ifconfig.me (should show proxy IP, not server IP)
Check DNS leaks: curl -4 ifconfig.me (force IPv4)

What’s Next

Complete networking setup:

Firewall → - Granular traffic rules
SSH Access → - Secure shell and SFTP
IPv4 Management → - Dedicated IPs (coming soon)

Understanding gained:

✅ Network Configuration controls OUTBOUND traffic (exit IP)
✅ Hoody Proxy controls INBOUND traffic (service URLs)
✅ SOCKS5 routes ANY TCP protocol (most versatile)
✅ Host-level routing = zero in-container configuration
✅ Block mode = complete internet isolation

Change your exit IP with one API call.
SOCKS5 with credentials = maximum flexibility.

Network routing that just works—configured at host level, invisible to applications.

Network Configuration

API Endpoints Summary

Two Different “Proxies” on Hoody

Four Routing Types

1. SOCKS5 Proxy (Recommended)

2. HTTP Proxy

3. HTTPS Proxy

4. Block (Complete Isolation)

Host-Level Routing Power

Common Use Cases

Change Exit IP for Geo-Restricted APIs

Route Through Corporate Proxy

Secure AI Code Sandbox

Multi-Region Testing

Network + Firewall + Permissions

Managing Network Configuration

Get Current Config

Remove Config (Restore Default)

Start / Stop Network Proxy

Verify Exit IP

Best Practices

1. Use SOCKS5 for Universal Routing

2. Test Config Before Production

3. Document Your Routing

4. Combine with Firewall for Defense-in-Depth

Useful Questions

Does Network Configuration affect container service URLs?

What happens if SOCKS5 proxy goes down?

Can I use multiple proxies simultaneously?

Does this work with WireGuard or OpenVPN?

Do changes require container restart?

Can containers communicate with each other in block mode?

Troubleshooting

Cannot Access Internet After Configuring VPN

DNS Resolution Fails

Proxy Authentication Fails

Exit IP Not Changing

What’s Next

Can containers communicate with each other in `block` mode?