# Container Network

**Page:** api/container-network

[Download Raw Markdown](./api/container-network.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



The Container Network API lets you manage outbound network behavior for individual containers — including configuring proxy profiles, blocking all traffic, starting/stopping the underlying bridge, and inspecting live status. Use these endpoints when you need to route a container through a specific proxy, geo-pin its egress, or cut off its network entirely.

## Get container network configuration

`GET /api/v1/containers/{id}/network`

Returns the current network configuration and runtime status for a container, including the bridge details used to enforce the proxy or block rule.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Unique identifier of the container to retrieve network configuration for |



```bash
curl -X GET "https://api.hoody.com/api/v1/containers/507f1f77bcf86cd799439012/network" \
  -H "Authorization: Bearer <token>"
```


```typescript
const result = await client.api.containers.getNetworkConfig({
  id: "507f1f77bcf86cd799439012"
});
```


```json
{
  "statusCode": 200,
  "message": "Network configuration retrieved successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439012",
    "configured": true,
    "type": "socks5",
    "proxy": "socks5://user:pass@proxy.example.com:1080",
    "country": "US",
    "city": "New York",
    "region": "North America",
    "comment": "Production proxy configuration",
    "dns_servers": ["1.1.1.1", "8.8.8.8"],
    "status": "running",
    "configured_at": "2025-01-15T10:00:00.000Z",
    "last_status_check": "2025-01-15T20:00:00.000Z",
    "remote_status": {
      "is_running": true,
      "last_check": "2025-01-15T20:00:00.000Z",
      "bridge_details": {
        "bridge_name": "br-hoody-507f",
        "bridge_ip": "10.20.0.1",
        "gost_listener_ip": "10.20.0.2",
        "port": 1080
      }
    }
  }
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid container ID format"
}
```


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}
```


```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Access denied to this container"
}
```


```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}
```


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to retrieve network configuration"
}
```



## Update container network configuration

`PATCH /api/v1/containers/{id}/network`

Configures or updates the network proxy/blocking settings for a container. The `type` field selects between a proxy protocol (`socks5`, `http`, `https`) and `block`, which drops all egress traffic.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Unique identifier of the container to configure network for |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | Yes | Network configuration type. One of: `socks5`, `http`, `https`, `block` |
| `proxy` | string | No | Proxy server URL (required for non-block types, e.g. `socks5://user:pass@proxy.example.com:1080`) |
| `country` | string | No | Optional country for geographical proxy selection |
| `city` | string | No | Optional city for geographical proxy selection |
| `region` | string | No | Optional region for geographical proxy selection |
| `comment` | string | No | Optional comment describing the network configuration |
| `dns_servers` | array | No | Custom DNS servers (max 4, defaults to `["1.1.1.1", "8.8.8.8"]`) |



```bash
curl -X PATCH "https://api.hoody.com/api/v1/containers/507f1f77bcf86cd799439012/network" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "socks5",
    "proxy": "socks5://user:pass@proxy.example.com:1080",
    "country": "US",
    "city": "New York",
    "region": "North America",
    "comment": "Production proxy for US traffic",
    "dns_servers": ["1.1.1.1", "8.8.8.8"]
  }'
```


```typescript
const result = await client.api.containers.updateNetworkConfig({
  id: "507f1f77bcf86cd799439012",
  data: {
    type: "socks5",
    proxy: "socks5://user:pass@proxy.example.com:1080",
    country: "US",
    city: "New York",
    region: "North America",
    comment: "Production proxy for US traffic",
    dns_servers: ["1.1.1.1", "8.8.8.8"]
  }
});
```


```json
{
  "statusCode": 200,
  "message": "Network configuration updated successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439012",
    "type": "socks5",
    "proxy": "socks5://user:pass@proxy.example.com:1080",
    "country": "US",
    "city": "New York",
    "region": "North America",
    "comment": "Production proxy for US traffic",
    "dns_servers": ["1.1.1.1", "8.8.8.8"],
    "status": "configured",
    "configured_at": "2025-01-15T21:00:00.000Z",
    "bridge_details": {
      "bridge_name": "br-hoody-507f",
      "bridge_ip": "10.20.0.1",
      "gost_listener_ip": "10.20.0.2",
      "port": 1080
    }
  }
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Proxy URL required for non-block type"
}
```


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}
```


```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Cannot configure network for this container"
}
```


```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}
```


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to update network configuration"
}
```



## Start container network proxy/blocking

`POST /api/v1/containers/{id}/network/start`

Starts the network proxy or blocking service for a container. The container must already have a network configuration in place before this endpoint can activate it.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Unique identifier of the container to start network for |



```bash
curl -X POST "https://api.hoody.com/api/v1/containers/507f1f77bcf86cd799439012/network/start" \
  -H "Authorization: Bearer <token>"
```


```typescript
const result = await client.api.containers.startNetwork({
  id: "507f1f77bcf86cd799439012"
});
```


```json
{
  "statusCode": 200,
  "message": "Network service started successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439012",
    "status": "running",
    "is_running": true,
    "last_check": "2025-01-15T21:05:00.000Z",
    "bridge_details": {
      "bridge_name": "br-hoody-507f",
      "bridge_ip": "10.20.0.1",
      "gost_listener_ip": "10.20.0.2",
      "port": 1080
    }
  }
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Network not configured for this container"
}
```


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}
```


```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Cannot start network for this container"
}
```


```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}
```


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to start network service"
}
```



## Stop container network proxy/blocking

`POST /api/v1/containers/{id}/network/stop`

Stops the network proxy or blocking service for a container. The configuration is preserved and can be re-started later.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Unique identifier of the container to stop network for |



```bash
curl -X POST "https://api.hoody.com/api/v1/containers/507f1f77bcf86cd799439012/network/stop" \
  -H "Authorization: Bearer <token>"
```


```typescript
const result = await client.api.containers.stopNetwork({
  id: "507f1f77bcf86cd799439012"
});
```


```json
{
  "statusCode": 200,
  "message": "Network service stopped successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439012",
    "status": "stopped",
    "is_running": false,
    "last_check": "2025-01-15T21:10:00.000Z",
    "bridge_details": {
      "bridge_name": "br-hoody-507f",
      "bridge_ip": "10.20.0.1",
      "gost_listener_ip": "10.20.0.2",
      "port": 1080
    }
  }
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Network not configured for this container"
}
```


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}
```


```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Cannot stop network for this container"
}
```


```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}
```


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to stop network service"
}
```



## Remove container network configuration

`DELETE /api/v1/containers/{id}/network`

Removes the entire network proxy or blocking configuration for a container. After this call the container returns to its default (unfiltered) network behavior.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Unique identifier of the container to remove network configuration from |



```bash
curl -X DELETE "https://api.hoody.com/api/v1/containers/507f1f77bcf86cd799439012/network" \
  -H "Authorization: Bearer <token>"
```


```typescript
const result = await client.api.containers.removeNetworkConfig({
  id: "507f1f77bcf86cd799439012"
});
```


```json
{
  "statusCode": 200,
  "message": "Network configuration removed successfully"
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid container ID format"
}
```


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}
```


```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Cannot remove network configuration from this container"
}
```


```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container or network configuration not found"
}
```


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to remove network configuration"
}
```




The typical workflow is: call `PATCH` to define the proxy/blocking configuration, then `POST /network/start` to activate it. Use `POST /network/stop` to pause without losing the configuration, and `DELETE` to remove it entirely.