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

cURL

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

SDK

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

200

{
  "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
      }
    }
  }
}

400

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

401

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

403

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

404

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

500

{
  "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"])

cURL

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"]
  }'

SDK

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"]
  }
});

200

{
  "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
    }
  }
}

400

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

401

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

403

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

404

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

500

{
  "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

cURL

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

SDK

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

200

{
  "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
    }
  }
}

400

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

401

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

403

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

404

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

500

{
  "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

cURL

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

SDK

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

200

{
  "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
    }
  }
}

400

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

401

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

403

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

404

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

500

{
  "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

cURL

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

SDK

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

200

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

400

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

401

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

403

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

404

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

500

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

Tip

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.