SphereShell

SphereShell is an interactive shell into a running spherelet — for the moments when logs aren't enough and you need to look at the actual container. Browser-based, short-lived token, no SSH key to manage.

Use it for debugging: inspect a config file your service rendered at boot, run a one-off database CLI inside a managed datastore's spherelet, check what's actually on a SphereStor mount path, or trace a process tree.

How it works

Step	What happens
1. You pick a spherelet	In the console, on the deployment's Spherelets tab. Each spherelet is one running container.
2. Platform mints a token	A short-lived (~30 minute) token bound to that one spherelet. Mint counts as a state change and is recorded in Activity.
3. Browser opens a shell	The console launches the shell in a new tab, attached to the spherelet's stdin/stdout/stderr.
4. Token expires	The session closes when the token expires. Mint a new one to continue.

The shell runs inside the spherelet — same filesystem, same env vars, same network reachability as the workload. There's no SSH bastion to provision and no key material to rotate; the token is the credential and it expires on its own.

Open a SphereShell

1. Open the deployment in the console and go to the Spherelets tab.
2. Pick the spherelet you want to inspect and click Open shell.
3. The console mints a token and opens the shell in a new tab.

If you don't see Open shell, you don't have the project role required (see permissions).

Permissions

SphereShell requires Admin on the service's project. The bar is intentionally high:

• An interactive shell can execute arbitrary code inside the workload.
• It can read environment variables and secret variables mounted into the container.
• It can read any SphereStor the spherelet has mounted.

That's the same risk profile as reading raw secrets, so SphereShell sits at the same authorization bar. Viewable and Editable can't open one.

There are two ways to have Admin on a project:

How	Reach
Be an Owner or Admin of the account	Every project in the account.
Be in a team that has Admin on the project	That project only.

To give someone a terminal on one project without making them an Admin of the account, put them in a team and give the team Admin on that project. An account Owner or Admin has to do that.

If you open the Shell tab without Admin, the console says you don't have permission and who can grant it.

Every shell-token mint is logged in Activity with the actor, the deployment id, and the spherelet id. The shell session itself isn't recorded as a transcript — that's a deliberate scope limit (see Honest limits).

What you can do inside

The shell is a normal interactive terminal — ls, cat, ps, env, your application's CLI, the datastore client for that operator (psql, valkey-cli, rabbitmqctl), etc. Whatever's available in the container image is what you have.

Use case	Notes
Inspect a rendered config file	Useful when env-var templating gave you something unexpected.
Run the database CLI on a managed datastore	The operator's CLI is on the path — psql on PostgreSQL, valkey-cli on Valkey, etc.
Walk a SphereStor mount	Confirm what your service wrote to disk, find an upload that vanished, etc.
Capture a stack trace from a stuck process	ps, kill -QUIT, language-specific dump tools.
Trace a flaky outbound call	curl from inside the network namespace your service sees.

If you need to move bytes (upload a fixture, download a report), reach for Spherefiles instead — it's the file-transfer surface and is purpose-built for that, without needing Admin.

Honest limits

• One spherelet at a time. A token binds to a single spherelet. To shell into a second one (e.g. another replica), mint another token.
• No persistent session. The token TTL is short by design (~30 minutes). Long debugging sessions need to be re-minted; tokens can't be extended.
• Admin-only. Viewable and Editable can't open a SphereShell, and there is no terminal-only level: a team given Admin on a project also gets the rest of what Admin allows there. See Permissions.
• No session transcript. The platform logs every mint, not every keystroke. If you need a full session recording (compliance, on-call review), capture it on the client side (e.g. script(1) in the browser shell, or your own terminal recorder); the platform doesn't keep one.
• Anything you change is ephemeral. The shell modifies the current spherelet's filesystem. The next deployment, restart, or autoscaling event boots a fresh container from your image — your edits don't survive. To persist, change your image or write to a mounted SphereStor.
• No file upload through the shell. Pasting binary data into a terminal is a recipe for corruption. Use Spherefiles when you need to push or pull files.
• Cron jobs only have a shell while they're running. A cron spherelet exits when the job finishes — you can't shell into a stopped one. To debug, deploy as a background worker temporarily, or shell in mid-run.
• No multi-spherelet broadcast. SphereShell talks to one container; there's no exec across all replicas mode.

When to reach for something else instead

You want to…	Use
Read logs without changing anything	Runtime logs (less risky, no Admin required)
See metrics across services or time	SphereOps
Upload or download files from a SphereStor	Spherefiles
Roll back a bad deploy	Service actions (you don't need a shell to redeploy)
Read or write env / secret variables	The Environment surface — versioned, audited, doesn't require shelling in

A shell is the right answer when none of the above works. It's the most powerful and most logged tool in the kit; treat it that way.

What's next

• Spherelets — the unit SphereShell connects to.
• Environment variables — read/write env + secrets without shelling in.
• Spherefiles — move files without shelling in.
• Activity — every shell-token mint is recorded here.
• Security → Access controls — the full role model behind the Admin gate.