Web service

A web service is a containerized HTTP application running continuously on ComputeSphere. You give it an image (or a Git repo), tell it which port your app listens on, and the platform terminates TLS at the edge, hands traffic to your spherelets, and load-balances across them.

One request, end to end

Public Internet

A browser, an API client, anything making an HTTPS request.

HTTPS URL

silver-cobra.computesphere.appTLS terminated at the edge.

Serviceapi

3 spherelets — load-balanced.

Web service is the right kind for: APIs, full-stack web apps, single-page app servers, gRPC services (over HTTP/2), reverse proxies — anything that wakes up on a request and writes a response.

What you configure

Field	What it does
Name	Identifier for the service — unique within the project.
Plan	Spherelet shape: flex, standard, or performance. See Spherelets for the CPU/memory and pricing for each.
Spherelets	How many copies to run (1–100). Traffic load-balances across them.
Port	The port your app listens on — bound to 0.0.0.0 (not localhost). Required, or the platform can't route requests.
Build source	image to pull a pre-built image from a registry, or git to build from a connected repo.
Image	The registry path (when build_source: image) — e.g. ghcr.io/acme/api:1.0.0.
Dockerfile	Path to the Dockerfile (when build_source: git) — defaults to Dockerfile.
Branch	Git branch to deploy from (when build_source: git) — defaults to main.
Custom domain	Optional. Your own hostname instead of (or alongside) the auto-generated *.computesphere.app URL. See Custom domains.
Health check	Optional. An HTTP path the platform polls to know your service is ready. Without it, the rollout assumes "started = healthy".
Autoscaling	Optional. CPU-based. Set min/max spherelets and a target. See Auto-scaling.
Environment variables	Configuration passed into the container — plain values and secret values. See Environment variables.

Build sources

You ship one of two ways:

• From an image — you (or your CI) build the image and push it to a registry. ComputeSphere pulls it on deploy. Pairs with the GitHub Actions workflow or any other CI.
• From Git — you connect a GitHub repo and pick a branch. ComputeSphere builds the image for you on every push using the Dockerfile in the repo.

Either way, what runs on the platform is the same: your container, executed with the platform's runtime environment. Image-builds keep the build pipeline in your hands; Git-builds skip the CI step.

Networking

Listen on 0.0.0.0, not localhost

Your server must bind to 0.0.0.0 on the port you set for the service — not 127.0.0.1 or localhost. The platform forwards traffic to your spherelet on that port; an app bound only to loopback is reachable from inside the spherelet but not from the platform's router, so requests fail with 502 / connection-refused even while the spherelet shows as running. Most frameworks bind to loopback by default in development — set the host explicitly for production:

• Node / Express — app.listen(port, "0.0.0.0")
• Python / Flask — app.run(host="0.0.0.0", port=port) (or flask run --host 0.0.0.0)
• Gunicorn / Uvicorn — --bind 0.0.0.0:<port> / --host 0.0.0.0
• Go — http.ListenAndServe(":"+port, ...) — the empty host already binds all interfaces

• Default URL. Every web service gets a stable *.computesphere.app subdomain (e.g. silver-cobra.computesphere.app) the moment it's created. TLS is provisioned automatically.
• Custom domain. Bring your own — api.example.com, app.mycompany.io. TLS certs auto-renew. See Custom domains.
• Private network. Inside the environment, services can reach each other by service name (http://api, http://worker:9000) once private network is enabled on the environment. The public URL is unchanged either way. See Private network.

Health checks

Set a health check path (e.g. /health) and the platform uses it to gate rollouts. New spherelets only take traffic once they return 200. Old spherelets keep serving until then — that's how zero-downtime deploys actually work.

Without a health check the rollout assumes "container started → ready," which is fine for short-startup apps but skips the safety net for slow-boot frameworks (Rails, Spring, Django with heavy startup). See Health checks.

Scaling

Two ways to size a web service:

• Manual. Pick a count, traffic load-balances across that many spherelets. Adjust any time without a redeploy.
• Autoscaling. Set a min/max and a CPU target (e.g. 80%). The platform adds spherelets when sustained CPU climbs past the target and removes them when it settles down.

Both bounded by your account capacity. See Spherelets and Auto-scaling.

Lifecycle controls

A web service supports every lifecycle verb — deploy, redeploy, restart, stop, start, rollback, and scale. See Service actions for what each one does, what it preserves, and when to reach for it.

Create a web service

1. Open the project and environment where the service should run.
2. Click New service → Web service.
3. Pick a build source: Image or Git.
   • For Image, paste the image path (e.g. ghcr.io/acme/api:1.0.0).
   • For Git, connect a GitHub account if you haven't, then pick a repo and branch.
4. Fill in name, port, and a compute plan (Flex / Standard / Performance).
5. (Optional) Add environment variables and secrets, set a health check path, turn on autoscaling.
6. Click Create.

The service appears in the Services tab. The first deploy starts immediately; you'll see status transitions and the live URL when it finishes.

Outputs

When a web service is running, the platform surfaces two URLs:

Output	Where it points
Public URL	https://<subdomain>.computesphere.app (and any custom domains you've attached). What the world reaches.
Internal URL	Reachable from other services in the same environment when private network is on. Format: http://<service-name> on the service's port.

Honest limits

• Port is required. A web service exposes exactly one container port. For multi-port apps (e.g. an HTTP server + a metrics server), front them with a single reverse proxy or run each as its own service.
• One image per service. Multi-container patterns (sidecars, init containers) aren't exposed today. Run the second container as a separate web service or background worker.
• HTTP/HTTPS only. Custom protocols (raw TCP, WebSockets-over-TCP, UDP) aren't supported at the edge. WebSockets over HTTPS work — the platform terminates TLS and passes the upgraded connection through.
• Region comes from the environment. A service runs in its environment's region; you can't place one service in a different region from the rest of its environment.

What's next

• Background worker — the service kind for continuous workers with no public URL.
• Cron jobs — the service kind for scheduled, exit-when-done work.
• Spherelets — how the compute behind your service is sized and billed.
• Custom domains — bring your own hostname.
• Health checks — gate rollouts on real readiness.