Container Network

Configure the network interface for a container: read the current configuration, attach a proxy (SOCKS5, HTTP, or HTTPS), set up traffic blocking, start or stop the service, and remove the configuration entirely. Use these endpoints when you need to route a container’s outbound traffic through a specific proxy endpoint or block outbound traffic altogether.

Note

All endpoints require authentication via a Hoody API token passed in the Authorization header (for example Bearer <token>).

Read and modify configuration

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

Get the current network configuration and status for a container, including the proxy endpoint, geo metadata, DNS servers, and the live remote status.

Parameters

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

Response

200

{
  "statusCode": 200,
  "message": "Network configuration retrieved successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439012",
    "configured": true,
    "type": "socks5",
    "proxy": "socks5://proxy.example.com:1080",
    "credentials_configured": true,
    "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"
    }
  }
}

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

SDK usage

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

const config = await client.api.containers.getNetworkConfig('507f1f77bcf86cd799439012');

PUT /api/v1/containers/{id}/network

Configure or update the network proxy or blocking settings for a container. The request body must include a type. When type is not block, a proxy URL is required. Credentials can be embedded in the proxy URL as userinfo; the API never echoes credentials back, only the boolean credentials_configured.

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), for example socks5://proxy.example.com:1080. Credentials may be embedded as userinfo to set or replace them; omitting userinfo on an unchanged endpoint preserves stored credentials (write-only secret). The response never echoes userinfo back; see credentials_configured.
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"].

Response

200

{
  "statusCode": 200,
  "message": "Network configuration updated successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439012",
    "type": "socks5",
    "proxy": "socks5://proxy.example.com:1080",
    "credentials_configured": true,
    "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"
  }
}

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

SDK usage

cURL

curl -X PUT "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 SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

const updated = await client.api.containers.updateNetworkConfig(
  '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']
  }
);

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

Remove the entire network proxy or blocking configuration for a container. After removal, the container returns to using the default network path with no proxy applied.

Parameters

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

Response

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

SDK usage

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.containers.removeNetworkConfig('507f1f77bcf86cd799439012');

Service lifecycle

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

Start the network proxy or blocking service for a container. The container must already have a network configuration before this endpoint can succeed.

Parameters

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

Response

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

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

SDK usage

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

const result = await client.api.containers.startNetwork('507f1f77bcf86cd799439012');

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

Stop the network proxy or blocking service for a container. The configuration is preserved and can be restarted later.

Parameters

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

Response

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

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

SDK usage

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

const result = await client.api.containers.stopNetwork('507f1f77bcf86cd799439012');