Managed environments

A managed environment is a VM that codai creates, enrols and looks after. You pick a provider and a size; a worker that runs every minute provisions the machine, installs codaid through cloud-init, stops it when idle and bills it per second of runtime.

Providers and regionsCopy Anchor Link

The local provider value exists in the schema but is reserved; it is not provisioned.

SizesCopy Anchor Link

Each provider bills the RAM it actually gives you.

Rate = vCPU × €0.01/h + GB RAM × €0.005/h, stored on the environment at creation (hourlyRateMicroEur). The server type is a preference: if a provider retires it, codai picks the cheapest live type with at least the same vCPU and RAM and still bills the size's rate. Disk is whatever the flavor or server type ships with (OpenStack 20 / 40 / 80 GB, Hetzner 40 / 80 / 160 GB); while the machine is stopped or archived, the kept disk costs €0.05 per GB-month — see storage. GPU environments are coming soon.

Creating or starting a managed environment needs a wallet balance of at least one hour at its rate, otherwise 402 insufficient_balance (details).

Compute reserve and graceCopy Anchor Link

Set a compute reserve in Hub → Billing: LLM usage never spends the wallet below it, so a busy chat session cannot starve your VM. If a 10-minute bucket still cannot be paid, the environment enters a 30-minute grace period (shown in Hub and the desktop app with the stop time); a top-up during grace pays the missed bucket and clears it. After 30 minutes the environment is snapshot-stopped — nothing is lost.

Create oneCopy Anchor Link

The environment starts in creating. The worker creates the server (creating → enrolling once it has a public IP), cloud-init installs codaid as a system service and enrols it with a token the worker mints, and the environment becomes running. On both providers this took about two to three minutes in production. At enrolment the daemon of a managed machine receives its own API key under the environment owner; destroying the environment revokes it.

That daemon key is scoped to its own environment: it may call inference, drive the shared session of a task it runs, read its own environment (and its project), and list its own environment's secret names — nothing else. Any other route answers 403 key_scope_forbidden, so a compromised machine cannot reach your other environments, keys or wallet.

The worker never destroys a machine on an error path; you decide.

An environment in error whose server still exists is billed like a running one; after 30 minutes in error the worker snapshot-stops it, so a broken machine does not keep charging.

LifecycleCopy Anchor Link

Anything else answers 409 invalid_transition. Hub buttons, codaid env start|stop|destroy and POST /v1/environments/{id}/{action} all go through the same transition table.

What stop and start do on each provider:

archive runs the same stop path and parks the machine in archived; the only way out of archived is destroy. destroy deletes the server (and on Hetzner its snapshot) and revokes the daemon key.

Idle auto-stopCopy Anchor Link

Every environment has idle_timeout_minutes (default 30, 5–1440; change it with PATCH /v1/environments/{id} or in the hub). The worker stops a running managed environment when

now − max(last_activity_at, started_at) > idle_timeout_minutes

with reason idle. Activity is:

• any exec, terminal or port-stream byte from an attached client, through the relay;
• daemon heartbeats reporting human or agent activity — an idle heartbeat never counts;
• requests the daemon itself makes to the gateway with its key (for example an agent loop running inside the machine);
• your own start/stop/archive/destroy requests.

Open preview traffic from third parties counts only as port-stream bytes, so a public preview with visitors keeps the machine awake. Activity is recorded at most once a minute.

The machine can also be stopped for billing reasons — insufficient_funds, billing_error or budget_exceeded; see billing. The reason is shown on the environment page and returned as stateReason.

PrebuildsCopy Anchor Link

A project can keep a pool of up to 5 ready machines so a new environment starts from a warmed snapshot instead of a fresh install:

curl -X PATCH https://ai.codai.ro/v1/projects/$PROJECT_ID \
  -H "Authorization: Bearer $CODAI_API_KEY" -H 'content-type: application/json' \
  -d '{"prebuild_pool_size": 2, "prebuild_provider": "openstack", "prebuild_size": "small"}'

• Only the project owner or an org owner/admin can set it. The worker tops the pool up every minute, runs only the devcontainer's onCreateCommand and updateContentCommand, then stops each machine.
• The project owner pays the warm-up compute and the storage of the stopped pool machines (the normal storage rate). The pool is not topped up while the owner's wallet holds less than one hour of a pool machine.
• POST /v1/environments with the same provider and size (and no slug) claims a ready machine: ownership moves to you, it starts right away and the response carries prebuild_claimed: true. From then on you pay for it. The one-hour balance check still applies.
• Unclaimed pool machines are visible only to the project owner. Lowering prebuild_pool_size, or changing the provider/size, destroys the extra unclaimed machines.

Coming soonCopy Anchor Link

GPU environments and choosing the region in the hub are not available yet.