Skip to main content

Managing hosted environments

A hosted erun platform gives your tenant its own environments over an API — create one, deploy it, stop it when idle, delete it when you're done — the same lifecycle erun open/erun stop/erun delete give a local or cloud-context environment, driven instead through erun platform once you're signed in.

For the full concept and spec, see Agent reference · Hosted platform.

The examples below use the CLI, but every action — previewing, registering, deploying, stopping, deleting — has an equivalent in the desktop app's tenant dashboard, on its Registration tab. Open the tenant dashboard and switch to Registration to see what's already registered on the platform, alongside the local tenant and environments the sidebar already shows: those are two separate objects, and creating one does not create the other. Registering a new tenant, or enrolling its first user, still needs erun platform tenant create/erun platform user enroll from the CLI or console — the Registration tab points there rather than half-configuring it through a form.

Each section of the hosted web console — Overview, Environments, Cloud contexts, and the rest of the sidebar — has its own URL. Reloading the page, sharing a link, or using the browser's Back and Forward buttons all keep you on the section you were viewing rather than dropping you back to Overview. A link naming a section your tenant type doesn't have (for example a non-operations tenant following a Users link) lands on Overview instead of a panel the API would refuse.

Sign in once​

erun cloud init erun --api-url https://api.erunpaas.com
erun cloud login --alias erun+api.erunpaas.com@erun

https://api.erunpaas.com is erun's own hosted platform — a single apex host serving every tenant, not a per-tenant or per-environment address. A self-hosted platform has its own single API URL the same way; ask whoever runs it what that is.

login opens a device-code sign-in (or a browser tab if your issuer has no device flow) and confirms you're in by printing your tenant.

In the desktop app, the same alias can be created without a terminal: the tenant dashboard's Connect action, or Settings → Cloud aliases → Add erun platform, both ask for just the API URL and sign in the same way.

Create and deploy an environment​

erun platform env register --name prod --type runtime --runtime-version 1.4.2

The platform starts a server-side deploy immediately; poll its status until it settles:

erun platform env get <environment-id>

status moves registered → provisioning → running (or failed, with a provisionError explaining why). A running environment is already reachable at its MCP hostname — the platform wires exposure (DNS + Ingress) into the same deploy, so there is no separate step to run once status settles. See Hosted platform · Automatic exposure for when that wiring runs and how it fails safely on a platform not configured for it.

New to erun and haven't run erun push yet? Registering an environment still works: it bootstraps on the canonical ERun runtime image instead of a project image you haven't published. Once you publish your own <tenant>-devops image at a version, deploying that version gets your own image and plan instead. See Hosted platform · Provisioning lifecycle for the mechanism.

Re-deploy at a different version later with:

erun platform env deploy <environment-id> --version 1.5.0

In the desktop, the Registration tab's "Register an environment" form registers, and each row in its environments list carries its own Deploy control (with an optional version field) for a later re-deploy.

Preview before you commit​

erun platform provision resolves the full plan — quota, placement, namespace, and deploy — without creating anything, so you can check it before registering for real:

erun platform provision --env-name staging --env-type runtime

The Registration tab's "Register an environment" form previews the same way: a "Preview provisioning plan" button resolves and shows the plan before "Register environment" is even enabled to click, so a register action is never one click past a preview you have not seen.

Stop and delete​

erun platform env stop <environment-id>     # scale to zero; state survives
erun platform env delete <environment-id>   # start tearing down the namespace; irreversible

delete is irreversible, and it returns as soon as the platform has accepted it — the teardown itself runs in the background, because a namespace stuck on an unsatisfiable finalizer can sit in Terminating for a long time. The command prints the environment at status deleting; poll it the same way you polled the deploy:

erun platform env get <environment-id>

It converges one of two ways: the environment is gone (env get reports it as not found), or it lands on deletion-blocked with the reason — the stuck namespace's own conditions — printed on the same line. The platform re-attempts a blocked delete on its own every few minutes, so a namespace that finishes terminating converges without you doing anything; re-running erun platform env delete retries it immediately.

The Registration tab's environments list carries Stop and Delete alongside Deploy on each row. Delete additionally asks you to type the environment's name to confirm before it will send the request — the same confirmation every other unrecoverable action in the desktop app requires.

Where an environment lands​

Name a cloud context you've already registered with contextId and a hosted runtime environment deploys there instead of the platform's own cluster; leave it unset and the platform auto-selects one of your own registered contexts with room, or falls back to its own cluster if you haven't registered any. See Placement for the full decision and what an unresolvable request looks like (a clear, immediate error rather than a silently-wrong deploy).

Register a cloud context first with:

erun platform context create --name prod --alias aws-main --region eu-west-2 --preview
erun platform context create --name prod --alias aws-main --region eu-west-2

--preview resolves and returns the bootstrap plan without creating anything, the same way the desktop's Registration tab's "Preview context plan" button does before its "Register context" button is used for real.

Checking an environment's MCP edge from the console​

The console's MCP access panel mints a per-environment MCP bearer token (POST /v1/environments/{id}/mcp-token — see Agent reference · API protocol) for you to present to the environment's MCP edge with your own MCP client. A Token capability selector controls what that token can do: Operate (the default — deploy an already-published version, start/stop the cloud context, resize the runtime pod) or Admin (every tool, including raw, delete, and terraform). Operate needs no special entitlement; requesting Admin does — it takes the same permission as deleting the environment outright, so it is an explicit escalation rather than the default.

It needs the environment's MCP hostname, which the panel does not resolve for you:

  • A runtime environment already has one — the platform wires exposure into the same deploy (see Automatic exposure above), at mcp.<tenant>-<env>.<services-zone>.
  • Any other environment type needs it exposed first: erun expose <tenant> <env> mcp prints the hostname to paste into the panel.

With an Admin-scoped token, paste that hostname in and click Call the version tool as a connectivity check: a JSON result confirms the edge is reachable and the token is accepted, and a network error most often means the hostname isn't exposed yet or the platform has no MCP signing key configured (the panel's mint step already reports that case with a 501). This is a connectivity check, not a general MCP client: it only ever calls the one read-only tool — and it needs Admin because reading (version) is not part of what Operate grants.

An Operate-scoped token skips that connectivity check (calling version would always be refused) and instead shows a Drive an operate tool form: pick deploy, context_start, context_stop, or resize, fill in that tool's own inputs (a version to deploy, the cloud context's name, a runtime-pod size), and call it against the same hostname — no external MCP client needed. Preview is checked by default on every call, so the first attempt against a real environment resolves and traces the plan without changing anything; uncheck it once the plan looks right.

The same panel's Attach to a live session control opens a live terminal to a session already running in the environment's pod (the one erun open --ai or a linked desktop orchestrator started), directly in the browser — no port-forward, no separate SSH or attach client. It mints its own narrower token (erun:attach, not the erun:admin the tool-driving form above uses). The session id field discovers what the environment has actually reported: it prefills the most recently active live session and offers a quick-pick button for every other one, so you no longer need to already know the id from wherever the session was started; you can still type one by hand, including for an environment that has not reported any sessions yet. Type a line and press Send; output streams into the scrollback as it arrives. This is a minimal, line-based view rather than a full terminal (no cursor-addressed rendering yet), and Disconnect ends only this browser's view — the session itself keeps running for the next attach.

Quotas​

Your tenant has a cap on how many environments it may register at once. erun platform env register reports a clear conflict at the cap; erun platform provision shows you the same quota decision in its preview before you commit. An environment you have asked to delete stops counting against that cap as soon as the delete is accepted — a teardown that gets stuck can't lock you out of your own allowance. In the desktop, hitting the cap shows the same message inline on the register form rather than a raw error — it names the cap and the fix (delete or stop another environment first), the same recoverable state the CLI reports.

Each of your environments also runs inside a namespace capped on CPU, memory, and storage — enforced by Kubernetes itself, not just recorded. On top of that, your tenant has an aggregate CPU/memory/storage budget across all of your runtime environments combined: registering (or redeploying) one that would push your total past that budget is refused the same way, naming which resource and by how much. If your platform operator has set either cap unusually low, registering a new runtime environment is refused with a clear conflict naming the cap, rather than succeeding and failing to actually come up.

You can see your own tenant's full quota — the environment-count cap, the per-environment ceiling, and the aggregate budget — at any time via the API's GET /v1/quota (no operator role required); there is no CLI command for it yet. All caps are set by your platform operator (operations-only); reach out to them to raise any of them. See Hosted platform · Quotas for the full spec.

Where next​