Skip to main content

Concepts

If you've shipped on Heroku, Render, or Vercel, most of this is familiar — skim the mapping table and jump to the lifecycle. Otherwise, read top to bottom. Every other doc page assumes the six concepts on this page.

A real setup, at a glance​

Like nested folders, every level lives inside the one above. Here's what a small but complete ComputeSphere setup looks like — an account that holds one project, with one production environment running two services:

Accountcedar-7x9k2m
Projectcheckout
Environmentprod
Serviceapi
Standard#47
3 spherelets running
Serviceworker
Flex#12
1 spherelet running

Six things, nested in that order. The rest of the page is one section per concept, plus the lifecycle that ties them together.

From another platform?​

ComputeSphereHerokuRenderVercel
accountteamworkspaceteam
projectpipelineprojectproject
environmentstage(env vars only)environment
serviceappservice(mostly implicit)
sphereletdynoinstancefunction / instance
deploymentreleasedeploydeployment

The mappings are close, not exact. Render and Vercel don't have a clean project → environment layer the way Heroku does — ComputeSphere sits closer to Heroku's hierarchy than to theirs.

Account​

The top-level container. Owns billing, members, and everything underneath. One account is one billing entity — one subscription, one payment method, one invoice stream.

  • ComputeSphere creates an account for you on signup with a generated name like cedar-7x9k2m. Rename it whenever you want.
  • You can be a member of many accounts — your employer's, a side project's, a client's. Each one bills separately.
  • A project stays with the account that created it. Moving a project between accounts is not supported today.

Project​

A group of related services. Usually one product or application family — checkout, marketing-site, internal-tools.

  • A project is just a folder for services. It doesn't run anything itself, doesn't have a URL, doesn't cost anything.
  • Granularity rule of thumb: one product per project. The team that owns it usually maps to the membership of the account, not the project.

Environment​

An isolated runtime — typically dev, staging, prod.

  • Environments have their own network, secrets, and resource limits. The prod env can't read staging's database password.
  • Every service lives in exactly one environment. To run the same code in two environments, you deploy it twice — or build it once and promote the tested image from one environment to the other.
  • A default environment is created for you the first time you add a service to a project, so simple setups don't have to pick.

Service​

Your application — a web server, background worker, or cron job.

  • A service is the unit of code: one container image, one set of env vars, one deployment history, one URL (if it's a web service).
  • Three kinds: web service, background worker, cron job. See Service kinds below.
  • Web services get an auto-generated URL like silver-cobra.computesphere.app. Bring your own domain by attaching a custom domain to the service.

Spherelet​

The compute unit. One spherelet = one running instance of your service.

  • A service with sphere_count = 3 runs 3 spherelets. To scale, change that number — no redeploy needed.
  • Each spherelet has a fixed size.
  • Stopping a service frees its spherelets for your other services. You keep paying for the spherelets your account holds until you lower the count in Settings › Spherelets. Your tier subscription is separate and stays flat monthly.

Spherelet shapes​

FLXFlex
vCPU
0.25
RAM
512 MB

Light services, side projects, hobby workloads

MAXStandard
vCPU
1
RAM
2 GB

Production APIs and most workloads

PWRPerformance
vCPU
2
RAM
4 GB

CPU-heavy workloads — image processing, transcoding, high-volume workers

Deployment​

A versioned release of a service. Every push, every container image, every rollback is a new deployment.

  • Deployments are immutable. They capture a specific image + config — they aren't edited, only superseded.
  • Old deployments stay around — that's how rollback works. Pick any prior deployment and redeploy it; no rebuild required.
  • Scaling a service does not create a new deployment. Only code, image, or config changes do.

Lifecycle​

Four verbs move a service from your laptop to a running URL:

From a Git repo
1

Push

Seconds

git push origin main
2

Build

30 sec – 3 min

docker build .
3

Deploy

Under 5 sec

create deployment #47
4

Run

Health check, then live

200 OK
From a container image
1

Push

Seconds

csph deploy --image …
2

Deploy

Under 5 sec

create deployment #47
3

Run

Health check, then live

200 OK
  • push — git push to a connected repo, or csph deploy --image … against a container registry. Seconds.
  • build — if you pushed source, ComputeSphere builds a container image. Typically 30 seconds to 3 minutes depending on your Dockerfile. If you pushed an image, this step is skipped.
  • deploy — a new deployment record is created with the resulting image. Usually under 5 seconds. If the service has a pre-deploy command — a database migration, say — it runs once against the new image here, and a failure stops the release.
  • run — the deployment is rolled out as new spherelets. They have to pass a health check before the old ones are drained, so updates are zero-downtime by default.

A rollback follows the same path, starting from an earlier deployment record. ComputeSphere keeps the prior image, so there's no rebuild.

Service kinds​

A service is your application, but it has a couple of shapes:

Web service

HTTP service with domains, autoscaling, and health checks.

REST APIs, websites, dashboards, internal tools.

Background worker

Runs continuously with no public URL.

Queue consumers, polling jobs, stream processors, ETL.

Cron job

Runs on a schedule, then exits.

Reports, backups, scheduled cleanups, batch jobs.

Both kinds run as spherelets, get versioned deployments, and follow the push → build → deploy → run lifecycle above.

Next​