# Network Configuration

**Page:** foundation/networking/network

[Download Raw Markdown](./foundation/networking/network.md)

---

# 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](/api/container-network/)** - Get current network config
- **[PATCH /api/v1/containers/\{id\}/network](/api/container-network/)** - Configure proxy/VPN/block mode
- **[DELETE /api/v1/containers/\{id\}/network](/api/container-network/)** - Remove config (restore default)
- **[POST /api/v1/containers/\{id\}/network/start](/api/container-network/)** - Start container network proxy/blocking
- **[POST /api/v1/containers/\{id\}/network/stop](/api/container-network/)** - Stop container network proxy/blocking

---

## Two Different "Proxies" on Hoody

**⚠️ CRITICAL:** Don't confuse these two systems:

| System | Direction | Purpose |
|--------|-----------|---------|
| **[Hoody Proxy](/foundation/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:**


  
    ```bash
    # 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"
    ```
  
  
    ```typescript
    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'],
    });
    ```
  
  
    ```bash
    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


  
    ```bash
    # Route container traffic through HTTP proxy
    hoody network update --container $CONTAINER_ID \
      --type http \
      --proxy "http://user:pass@corporate-proxy.com:8080"
    ```
  
  
    ```typescript
    await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
      type: 'http',
      proxy: 'http://user:pass@corporate-proxy.com:8080',
    });
    ```
  
  
    ```bash
    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


  
    ```bash
    # Route container traffic through HTTPS proxy
    hoody network update --container $CONTAINER_ID \
      --type https \
      --proxy "https://user:pass@secure-proxy.com:443"
    ```
  
  
    ```typescript
    await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
      type: 'https',
      proxy: 'https://user:pass@secure-proxy.com:443',
    });
    ```
  
  
    ```bash
    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)


  
    ```bash
    # Block all outbound internet traffic
    hoody network update --container $CONTAINER_ID --type block
    ```
  
  
    ```typescript
    await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
      type: 'block',
    });
    ```
  
  
    ```bash
    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:

```bash
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:


  
    ```bash
    # Configure SOCKS5 proxy for all container traffic
    hoody network update --container $CONTAINER_ID \
      --type socks5 \
      --proxy "socks5://user:pass@proxy.example.com:1080"
    ```
  
  
    ```typescript
    await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
      type: 'socks5',
      proxy: 'socks5://user:pass@proxy.example.com:1080',
    });
    ```
  
  
    ```bash
    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:


  
    ```bash
    # 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"
    ```
  
  
    ```typescript
    await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
      type: 'socks5',
      proxy: 'socks5://user:pass@us-proxy.example.com:1080',
    });
    ```
  
  
    ```bash
    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


  
    ```bash
    # Route through corporate HTTP proxy for compliance
    hoody network update --container $CONTAINER_ID \
      --type http \
      --proxy "http://employee:pass@corporate-proxy.com:8080"
    ```
  
  
    ```typescript
    await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
      type: 'http',
      proxy: 'http://employee:pass@corporate-proxy.com:8080',
    });
    ```
  
  
    ```bash
    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


  
    ```bash
    # Block all outbound traffic for AI sandbox
    hoody network update --container $CONTAINER_ID --type block
    ```
  
  
    ```typescript
    await client.api.containers.updateNetworkConfig(CONTAINER_ID, {
      type: 'block',
    });
    ```
  
  
    ```bash
    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:







**Test your API from multiple regions simultaneously.**

---

## Network + Firewall + Permissions

**Three-layer defense for complete traffic control:**

**Step 1:** Route through VPN:



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





**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](./firewall/)** | Packet filtering (ingress/egress) | [Firewall →](./firewall/) |
| **[Proxy Permissions](/foundation/proxy/permissions/)** | HTTP service access (inbound) | [Permissions →](/foundation/proxy/permissions/) |

**Layer all three for defense-in-depth.**

---

## Managing Network Configuration

### Get Current Config


  
    ```bash
    # View current network configuration
    hoody network get --container $CONTAINER_ID
    ```
  
  
    ```typescript
    const config = await client.api.containers.getNetworkConfig(CONTAINER_ID);
    console.log(config.data); // { type, proxy, dns_servers, status, remote_status }
    ```
  
  
    ```bash
    curl "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network" \
      -H "Authorization: Bearer $TOKEN"
    ```
  


### Remove Config (Restore Default)


  
    ```bash
    # Remove network config, restore direct connection
    hoody network delete --container $CONTAINER_ID
    ```
  
  
    ```typescript
    await client.api.containers.removeNetworkConfig(CONTAINER_ID);
    ```
  
  
    ```bash
    curl -X DELETE "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/network" \
      -H "Authorization: Bearer $TOKEN"
    ```
  


### Start / Stop Network Proxy


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

    # Stop network proxy/blocking
    hoody network stop --container $CONTAINER_ID
    ```
  
  
    ```typescript
    // Start network proxy/blocking
    await client.api.containers.startNetwork(CONTAINER_ID);

    // Stop network proxy/blocking
    await client.api.containers.stopNetwork(CONTAINER_ID);
    ```
  
  
    ```bash
    # 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:**

```bash
# 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:



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

### 3. Document Your Routing

```bash
# ✅ 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:**

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

### DNS Resolution Fails

**Solutions:**

1. Configure custom DNS:



2. Ensure firewall allows DNS:



### Proxy Authentication Fails

**Check:**

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

### Exit IP Not Changing

**Verify:**

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

---

## What's Next

**Complete networking setup:**
- **[Firewall →](./firewall/)** - Granular traffic rules
- **[SSH Access →](./ssh/)** - Secure shell and SFTP
- **[IPv4 Management →](./ipv4/)** - 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.**