Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.suga.app/llms.txt

Use this file to discover all available pages before exploring further.

Suga provides two networking modes: Private Networking for internal service communication, and Public Networking for exposing services to the internet.

​
Networking Overview

TypePurposeConfigurationSecurity
PrivateService-to-service communicationAutomaticInternal only
Public HTTPSWeb traffic with TLSPort 443Automatic TLS
Public TCPNon-HTTP protocolsCustom portNo TLS by default

​
Private Networking (Service Discovery)

All services in the same environment can communicate privately using automatic service discovery. Private traffic stays inside the environment and is never exposed to the internet.

​
How It Works

Automatic DNS:
  • Every service gets an internal hostname
  • Internal DNS resolves service hostnames to addresses within the environment
  • No manual configuration required
Format: 
hostname:port
Examples:
  • PostgreSQL: postgres:5432
  • Redis: redis:6379
  • API service: api:3000
  • WebSocket server: websocket:8080

​
Configuring Hostname and Ports

Each service has a Private Networking section in its Config tab where you can set:
  • Hostname: the name other services use to reach this service. Defaults to the service identifier. Override it to use a friendlier name like postgres or api. Hostnames must be unique within an environment.
  • Ports: the ports this service listens on internally. Add every port you want reachable from other services in the same environment.
Public networking ports (HTTPS endpoints, TCP proxies, custom domains) are automatically reachable on the private hostname as well, so you don’t need to list them twice.

​
Connection Strings

Use service names in connection strings: 
// PostgreSQL
const connectionString = `postgresql://user:pass@postgres:5432/database`;

// Redis
const redisUrl = `redis://:password@redis:6379`;

// HTTP API
const apiUrl = `http://api:3000/endpoint`;
Private networking currently only works within the same environment. Services in “production” cannot reach services in “staging”.

​
Public Networking

Public networking exposes services to the internet. Suga offers two modes: HTTPS and TCP Proxy.

​
HTTPS Endpoints

HTTPS endpoints provide secure web access with automatic TLS certificates. All HTTPS traffic goes through Cloudflare’s global CDN. Features:
  • Port 443 (HTTPS)
  • Automatic TLS certificates via Cloudflare
  • Cloudflare CDN, WAF, and DDoS protection
  • Auto-generated domain names
  • Load balancing across replicas
Auto-Generated Domains: Suga generates unique domains for your HTTPS endpoints. Example: 
https://9xyz5abc1def-production.ghi3jkl8.suga-2mno6pqr.com
You can also use your own domain, see Custom Domains. Configuration:
1

Select Service

Click on the service you want to expose.
2

Open Config Tab

In the properties panel, open the Config tab.
3

Enable Suga Domain

In the Public Networking section, click Enable next to Suga Domain. Specify the target port your application listens on (e.g., 3000, 8080). Public HTTPS traffic on port 443 routes to this port.
4

Deploy

Click Deploy Changes. Your service will be accessible at the auto-generated URL.

​
TCP Proxy

TCP proxy exposes non-HTTP protocols to the internet. Use Cases:
  • Direct database access (PostgreSQL, MySQL)
  • SSH connections
  • Custom protocols (MQTT, gRPC, WebSocket)
  • Game servers
Features:
  • Any TCP port
  • Allocated load balancer port
  • No automatic TLS (use application-level encryption)
Configuration:
1

Select Service

Click on the service to expose.
2

Open Config Tab

In the properties panel, open the Config tab.
3

Add TCP Proxy

In the Public Networking section, click + TCP Proxy. Enter the port your application listens on (e.g., 5432 for PostgreSQL).
4

Deploy

Click Deploy Changes. Note the allocated hostname and port in the Public Networking section.
5

Connect

Use the Suga hostname and allocated port:
psql -h proxy.fgh2ijk6.suga-9lmn4opq.com -p 46345 -U user
TCP proxy does not provide TLS encryption by default. Use application-level encryption (like PostgreSQL’s SSL mode) or consider keeping the service private.

​
Connection Timeouts

Suga Cloud applies explicit, predictable timeouts to all public traffic so connection behaviour is consistent across deployments.
TimeoutApplies ToValueWhat It Means
Request header timeoutHTTPS endpoints15 secondsClients must finish sending HTTP request headers within 15 seconds of connecting. Protects shared edge infrastructure from slow or stalled clients.
Stream idle timeoutHTTPS endpoints5 minutesAn HTTP request, WebSocket, or SSE stream with no traffic in either direction for 5 minutes is closed.
TCP idle timeoutHTTPS endpoints, TCP Proxy1 hourA TCP connection with no application data sent in either direction for 1 hour is closed.
Dead-peer detectionHTTPS endpoints, TCP Proxy~2.5 minutesSuga Cloud probes idle connections and closes any whose peer has gone away (network partition, crashed client, etc.) within roughly 2.5 minutes.
These limits apply equally on every plan. A separate per-request total timeout applies on the Free plan only — see Request Timeout under Services.

​
Keeping Long-Lived Connections Alive

For long-lived connections — WebSockets, Server-Sent Events, persistent database connections via TCP Proxy — make sure the client or server emits traffic more often than the relevant idle timeout:
  • WebSockets: send a ping frame every 1–2 minutes (well under the 5 minute stream idle timeout). Most WebSocket libraries can do this automatically.
  • Server-Sent Events: emit a comment line (: keepalive\n\n) or heartbeat event every 1–2 minutes.
  • TCP Proxy (e.g. databases): enable the protocol-level keepalive your client supports (PostgreSQL keepalives_idle, MySQL wait_timeout, etc.), or expect to reconnect once an hour.
Dead-peer detection and the TCP idle timeout are independent. Dead-peer detection only closes connections whose peer is gone — it does not reset the idle timer for healthy-but-quiet connections.

​
Load Balancing

For services with multiple replicas, Suga automatically load balances traffic: HTTPS Endpoints:
  • Round-robin load balancing across replicas
TCP Proxy:
  • Round-robin load balancing
  • Connection-level distribution
Private Networking:
  • Internal service load balancing across all replicas
  • Connections are distributed automatically with no client-side configuration required
Load balancing is automatic. You don’t need to configure it manually.

​
WebSocket Support

WebSockets work automatically with HTTPS endpoints: Setup:
  1. Configure your application to listen for WebSocket connections
  2. Enable HTTPS on the service
  3. Deploy
  4. Connect using wss:// (secure WebSocket)
Idle WebSockets are closed after 5 minutes. Have your client or server send a ping frame every 1–2 minutes to keep the connection open — see Connection Timeouts.
Example: 
// Client
const ws = new WebSocket('wss://9xyz5abc1def-production.ghi3jkl8.suga-2mno6pqr.com');

// Server (Node.js with ws library)
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 3000 });

wss.on('connection', (ws) => {
  console.log('Client connected');
  ws.send('Welcome!');
});

​
Network Isolation

Every environment runs inside its own isolated network boundary on Suga Cloud. Services in one environment cannot reach services in another over private networking, and the platform applies a default-deny security posture with explicit allow rules.

​
Environment Boundaries

Between Environments:
  • Services in different environments (production, staging, dev) cannot communicate privately, even within the same project
  • Each environment has its own isolated network with its own private DNS
  • For cross-environment communication, use public networking
Between Projects:
  • Services in different projects cannot communicate privately
  • Use public networking (HTTPS/TCP) for cross-project communication
Suga Cloud does not provision a dedicated VPC per project, and there is no cross-environment private routing. Environment isolation is enforced by network policy, not by separate networks.

​
Default-Deny Posture

Every environment starts with a default-deny policy and only the traffic listed below is permitted. Anything not explicitly allowed is dropped. Ingress (incoming connections to your services):
SourceAllowed
Other services in the same environmentYes
Suga Cloud management traffic (TLS, ingress routing, health checks)Yes
Services in other environments or projectsNo
The public internet (direct)No. Must go through a public endpoint
Egress (outbound connections from your services):
DestinationAllowed
DNS resolutionYes
Other services in the same environmentYes
Public internet (any external API or service)Yes
Private IP ranges outside the environment (RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)No
Cloud provider metadata endpointsNo
Blocking RFC 1918 ranges prevents services from reaching internal infrastructure they shouldn’t see, including other tenants’ private IPs. Blocking metadata endpoints prevents workloads from harvesting cloud credentials or instance identity from the underlying host.

​
Public vs Private

  • Private networking is internal-only and never exposed to the internet. It’s the only way services in the same environment talk to each other privately.
  • Public networking (HTTPS endpoints, TCP proxies, custom domains) requires explicit configuration on each service and routes through Suga’s managed ingress with automatic TLS for HTTPS.

​
Common Patterns

​
Web Application

Frontend talks to backend, backend talks to database: Configuration:
  • frontend: HTTPS enabled (public)
  • api: HTTPS enabled (public)
  • postgres: No public networking (private only)
  • api connects to postgres via postgres:5432

​
Microservices

Multiple services communicate privately, one acts as public gateway: Configuration:
  • gateway: HTTPS enabled (public)
  • users, orders, products: No public networking (private only)
  • Gateway connects to services via private networking

​
Common Questions

No, HTTPS always uses port 443. You specify your container port (e.g., 3000), and Suga routes port 443 to your container port automatically.
No, Suga automatically provisions and renews certificates for all HTTPS endpoints. Traffic is encrypted end-to-end through Cloudflare’s CDN.
Yes, using TCP proxy. However, it’s not recommended for security reasons. Keep databases private and access them via your application or a bastion host.
Not via private networking. Use public networking (HTTPS/TCP) or deploy related services in the same project.
Currently, public endpoints are accessible by anyone. Implement authentication in your application. IP allowlisting is planned for a future release.
The Free plan caps each HTTP request at 15 seconds total. Long-polling, large uploads or downloads, slow database queries served synchronously, and Server-Sent Events streams will be terminated at 15s. WebSockets are not affected — only the upgrade handshake is bounded by this timeout, and once established the connection is governed by the 5-minute stream idle timeout. Pro and Enterprise plans have no per-request total cap. See Request Timeout under Services.