Skip to main content

Private Network

Private network is an environment-level toggle that lets services inside the same environment talk to each other. With it on, your api service can connect to valkey:6379, your worker can read from postgres, and so on — by service name, over the platform's internal network. With it off, services run side-by-side but can't reach each other directly.

Environmentprod
Private network · Off
apiWeb service
URL
workerBackground
valkeyDatastore

Services here run independently — they can't reach each other.

Environmentprod
Private network · On
apiWeb service
URL
workerBackground
valkeyDatastore

Services here can reach each other by service name.

Same environment, two toggle states. Public ingress is unchanged either way — the toggle only affects whether services inside can reach each other.

What it does (and doesn't)​

  • It enables service-to-service communication inside the environment. When the toggle is on, every service in the environment is reachable from every other service by name and port — api:3000, worker:8080, valkey:6379, postgres:5432.
  • It doesn't change how the internet reaches you. Web services still get auto-generated *.computesphere.app URLs. Custom domains still attach the same way. The toggle is about the internal network, not the public-facing one.
  • It's set when you create the environment. Pick it at creation time. To flip an existing environment, create a new one and redeploy your services into it.

When to turn it on​

Anytime an environment runs more than one service that needs to coordinate. Which is most apps:

  • API + database. The API reads and writes from Postgres or Valkey by service name.
  • API + background worker. The API publishes jobs that a worker picks up — directly via Valkey/RabbitMQ.
  • Multi-tier apps. A front-end web service calls a back-end api service, which in turn talks to a queue and a datastore.

For a single-service app — one container, no internal dependencies — the toggle adds nothing. Leave it off and keep the configuration simple.

How services find each other​

Inside the environment, every service is reachable at its service name on whatever port it exposes:

postgres://api-user@postgres:5432/checkout
http://worker:8080
redis://valkey:6379

Names match the service slugs you set when creating the service in the Console (or via the API). Ports are whatever the service listens on. No DNS configuration on your end — the platform takes care of name resolution within the environment.

Environments are isolated from each other — services in prod can't reach services in staging, regardless of the private-network toggle. See Security for the full isolation model.

Enable a private network​

  1. Open the project where the new environment should live.
  2. Click New environment.
  3. Give it a name and pick a region.
  4. Toggle Private network on.
  5. Click Create.

From here, deploy your services into the new environment. They'll come up with internal name resolution active.

tip

You can't change the private-network setting after the environment exists. If you need to flip it, create a new environment and redeploy.

What's next​

  • Datastores: SphereDB (PostgreSQL), SphereCache (Valkey), SphereQueue (RabbitMQ). Create them in the same environment as the services that use them, and connect with the private connection string.
  • Security — environment isolation, secret scoping, the rest of the network model.
  • Custom domains — attach your own domain to a web service. Independent of the private-network toggle.