Environments

Description and operation

General

An environment is a set of services that run together, for example an API, a database and a cache. It gives workspaces the real dependencies of an application, so code is developed against them, not against mocks.

A workspace connects to an environment through a session. It then reaches each service by name, for example postgres://db:5432. An intercept sends a service's traffic to a workspace, so a change runs against the rest of the environment before it is merged.

Each environment has its own isolated network, and one disk shared by its services. It belongs to you or to a team; many sessions can connect to one environment.

To do these tasks with an AI agent, see Environments and intercepts with an agent.

States

Lifecycle

• Idle stop. An environment runs while a connected session is awake. After 5 minutes with none awake, it stops and sets idle_since. Using a connected session starts it again; an environment that you stopped stays stopped.
• Time to live. The platform deletes an environment that is unused for ttl_secs (600 to 2592000). An environment with a connected session, awake or idle, is in use and is never deleted.
• Delete. The services and the disk are removed. Connected sessions are disconnected, not ended. Snapshots stay.
• Interruption. If the machine that holds a running environment fails, start and clone return 409 until it returns. You can clone a snapshot into a new environment.

Clone

A clone is a new environment that starts with a copy of an environment. A clone is not a snapshot. The copy is independent: changes in the clone do not change the source, and changes in the source do not change the clone. The clone call answers 202 and starts the new environment at once.

A clone of the present state copies the live data of the source to a new disk. It has the owner and the region of the source. It has no based_on, because the platform makes no snapshot for it. It is refused with 409 while the source is interrupted.

A clone from a snapshot moves the expiry of the snapshot to a full default lifetime from now. With snapshot, the owner is the owner of the snapshot, you, or a team that you belong to.

A clone does not take the variables, the sessions, the intercepts or the time to live of its source. The new environment has no connected session. A clone counts as a new environment against the quota of the owner.

To do these tasks with an AI agent, see Agentic workflows – Volumes.

Restore

A restore puts the same environment back to one of its own snapshots. You name the snapshot by its id, and the snapshot must be ready. A restore moves the expiry of the snapshot to a full default lifetime from now. To make a new environment from a snapshot, clone it with snapshot_id.

The data and the service list return to the snapshot. The disk size becomes the size that the snapshot froze. The platform stops the services, puts back the data and starts the services of the snapshot.

The answer lists what the restore does to each service, by name.

A service can keep data that the snapshot does not have. The restore is then refused with 409 and a list lost. To accept the loss, name exactly those services in discard.

A restore counts the cpu and memoryGb of the services that it adds against the quota. It is refused when the disk of the owner is already above diskGb. It is also refused while a service that it removes has an intercept.

Quota and limits

An environment counts its disk, and the vCPU and memory of its running services, against the owner's quota.

Tasks

Create an environment

Reason for the task: Run the services of an application for workspaces to develop against.

Job set-up

• Access: you. A team environment needs team membership.
• References: POST /v1/environments, Services.

Procedure

1. Create the environment with its services.

   PythonCopy

   from kloudlite import Kloudlitekl = Kloudlite()env = kl.environments.create(    environment="acme-dev",    services=[{"name": "db", "image": "postgres:16", "ports": [5432],               "env": {"POSTGRES_PASSWORD": "dev"},               "mounts": [{"folder": "pgdata", "path": "/var/lib/postgresql/data"}]}],    quota_gb=20,)print(env["id"], env["state"])

   TypeScriptCopy

   import { Kloudlite } from "./index.ts";const kl = new Kloudlite();const env = (await kl.environments.create({  environment: "acme-dev",  services: [{    name: "db", image: "postgres:16", ports: [5432],    env: { POSTGRES_PASSWORD: "dev" },    mounts: [{ folder: "pgdata", path: "/var/lib/postgresql/data" }],  }],  quotaGb: 20,})) as Record<string, unknown>;console.log(env.id, env.state);

   GoCopy

   kl := kloudlite.New(kloudlite.Options{})env, err := kl.Environments.Create(kloudlite.CreateEnvironment{    Environment: "acme-dev",    Services: []kloudlite.Service{{        Name:   "db",        Image:  "postgres:16",        Ports:  []int{5432},        Env:    map[string]string{"POSTGRES_PASSWORD": "dev"},        Mounts: []kloudlite.Mount{{Folder: "pgdata", Path: "/var/lib/postgresql/data"}},    }},    QuotaGb: 20,})if err != nil {    log.Fatal(err)}fmt.Println(env["id"], env["state"])

   RubyCopy

   require_relative "kloudlite"kl = Kloudlite::Client.newenv = kl.environments.create(  environment: "acme-dev",  services: [{ name: "db", image: "postgres:16", ports: [5432],               env: { "POSTGRES_PASSWORD" => "dev" },               mounts: [{ folder: "pgdata", path: "/var/lib/postgresql/data" }] }],  quota_gb: 20)puts env.values_at("id", "state").join(" ")

   JavaCopy

   var kl = new Kloudlite();System.out.println(kl.environments().create(new Kloudlite.CreateEnvironment()    .environment("acme-dev")    .services(new Kloudlite.Service()        .name("db").image("postgres:16").port(5432)        .env("POSTGRES_PASSWORD", "dev")        .mount("pgdata", "/var/lib/postgresql/data"))    .quotaGb(20)));

   CLICopy

   kloudlite environments create acme-dev --quota-gb 20 --services '[  {"name": "db", "image": "postgres:16", "ports": [5432], "env": {"POSTGRES_PASSWORD": "dev"}, "mounts": [{"folder": "pgdata", "path": "/var/lib/postgresql/data"}]}]'

Close-out

1. Wait until state is running and every service in service_status is ready.

Show the status of an environment

Reason for the task: Check whether an environment and its services run, and why not.

Job set-up

• Access: you. A team environment needs team membership.
• References: GET /v1/environments/{id}, GET /v1/environments.

Procedure

1. Show the environment. kloudlite environments list lists them all.

   PythonCopy

   env = kl.environments.get(environment="acme-dev")print(env["state"], env.get("service_status"), env.get("idle_since"))

   TypeScriptCopy

   const env = (await kl.environments.get({ environment: "acme-dev" })) as Record<string, unknown>;console.log(env.state, env.service_status, env.idle_since);

   GoCopy

   env, err := kl.Environments.Get("acme-dev")if err != nil {    log.Fatal(err)}fmt.Println(env["state"], env["service_status"], env["idle_since"])

   RubyCopy

   env = kl.environments.get(environment: "acme-dev")puts env.values_at("state", "service_status", "idle_since").inspect

   JavaCopy

   System.out.println(kl.environments().get("acme-dev"));

   CLICopy

   kloudlite environments get acme-dev

Close-out

1. Make sure that state and service_status are what you expect. If not, see Troubleshooting.

Start an environment

Reason for the task: Run a stopped environment.

Job set-up

• Access: you. A team environment needs team membership.
• References: POST /v1/environments/{id}/start.

Procedure

1. Start the environment.

   PythonCopy

   kl.environments.start(environment="acme-dev")

   TypeScriptCopy

   await kl.environments.start({ environment: "acme-dev" });

   GoCopy

   if err := kl.Environments.Start("acme-dev"); err != nil {    log.Fatal(err)}

   RubyCopy

   kl.environments.start(environment: "acme-dev")

   JavaCopy

   kl.environments().start("acme-dev");

   CLICopy

   kloudlite environments start acme-dev

Close-out

1. Wait until state is running and every service is ready.

Stop an environment

Reason for the task: Release the compute of an environment and keep its data.

Job set-up

• Access: you. A team environment needs team membership.
• References: POST /v1/environments/{id}/stop.

Procedure

1. Stop the environment.

   PythonCopy

   kl.environments.stop(environment="acme-dev")

   TypeScriptCopy

   await kl.environments.stop({ environment: "acme-dev" });

   GoCopy

   if err := kl.Environments.Stop("acme-dev"); err != nil {    log.Fatal(err)}

   RubyCopy

   kl.environments.stop(environment: "acme-dev")

   JavaCopy

   kl.environments().stop("acme-dev");

   CLICopy

   kloudlite environments stop acme-dev

Close-out

1. Make sure that state is stopped. A warning in the response means that the machine of the environment is down.

Set the time to live

Reason for the task: Delete an environment automatically after a period without use.

Job set-up

• Access: you. A team environment needs team membership.
• References: PUT /v1/environments/{id}/ttl.

Procedure

1. Set ttl_secs from 600 to 2592000. Set it to no value (None, null, nil) to clear it.

   PythonCopy

   kl.environments.set_ttl(environment="acme-dev", ttl_secs=86400)

   TypeScriptCopy

   await kl.environments.setTtl({ environment: "acme-dev", ttlSecs: 86400 });

   GoCopy

   ttl := int64(86400)if _, err := kl.Environments.SetTTL("acme-dev", &ttl); err != nil {    log.Fatal(err)}

   RubyCopy

   kl.environments.set_ttl(environment: "acme-dev", ttl_secs: 86400)

   JavaCopy

   kl.environments().setTtl("acme-dev", 86400L);

   CLICopy

   kloudlite environments set-ttl acme-dev --ttl-secs 86400

Close-out

1. Make sure that expires_at shows a time, or no value if you cleared it.

Delete an environment

Reason for the task: Remove an environment that you no longer need.

Job set-up

• Access: you. A team environment needs team membership.
• References: DELETE /v1/environments/{id}, Volumes.

Procedure

1. Delete the environment.

   PythonCopy

   kl.environments.delete(environment="acme-dev")

   TypeScriptCopy

   await kl.environments.delete({ environment: "acme-dev" });

   GoCopy

   if err := kl.Environments.Delete("acme-dev"); err != nil {    log.Fatal(err)}

   RubyCopy

   kl.environments.delete(environment: "acme-dev")

   JavaCopy

   kl.environments().delete("acme-dev");

   CLICopy

   kloudlite environments delete acme-dev

Close-out

1. Make sure that the environment is no longer listed. A warning in the response names a session that was not disconnected.

List environments

Reason for the task: Find the environments that you and your teams can use.

Job set-up

• Access: you.
• References: GET /v1/environments, kloudlite environments list.

Procedure

1. Show the list. Pass an owner to list the environments of one handle or team.

   PythonCopy

   print(kl.environments.list())

   TypeScriptCopy

   console.log(await kl.environments.list());

   GoCopy

   list, err := kl.Environments.List("")if err != nil {    log.Fatal(err)}fmt.Println(list)

   RubyCopy

   p kl.environments.list

   JavaCopy

   System.out.println(kl.environments().list(null));

   CLICopy

   kloudlite environments list

Close-out

1. Make sure that each environment that you expect is listed.

Clone an environment

Reason for the task: Make a new environment from the present state of an environment, or from one of its snapshots.

Job set-up

• Access: you. A team environment needs team membership.
• Conditions: for a clone from a snapshot, you know the id of a ready snapshot of this environment. See Show the lineage.
• References: POST /v1/environments/{id}/clone.

Procedure

1. Clone the present state of the environment. Use a plain name for to.

   PythonCopy

   new = kl.environments.clone(environment="acme/dev", to="dev-copy")print(new["id"], new["state"])

   TypeScriptCopy

   const created = (await kl.environments.clone({ environment: "acme/dev", to: "dev-copy" })) as Record<string, unknown>;console.log(created.id, created.state);

   GoCopy

   created, err := kl.Environments.Clone(kloudlite.CloneEnvironment{Environment: "acme/dev", To: "dev-copy"})if err != nil {    log.Fatal(err)}fmt.Println(created["id"], created["state"])

   RubyCopy

   created = kl.environments.clone(environment: "acme/dev", to: "dev-copy")puts created.values_at("id", "state").join(" ")

   JavaCopy

   // The SDK returns the answer as raw JSON. Read the fields with your own JSON library.String created = kl.environments().clone(new Kloudlite.CloneEnvironment().environment("acme/dev").to("dev-copy"));System.out.println(created);

   CLICopy

   kloudlite environments clone acme/dev --to dev-copy

2. Give the id of a snapshot in snapshot in place of step 1, to clone that snapshot. Add quota_gb to change the disk size.

   PythonCopy

   new = kl.environments.clone(environment="acme/dev", to="dev-before-migration", snapshot="env-1f2e3d4c5b6a7988-8a7b6c5d", quota_gb=40)print(new["id"], new["state"])

   TypeScriptCopy

   const created = (await kl.environments.clone({  environment: "acme/dev",  to: "dev-before-migration",  snapshot: "env-1f2e3d4c5b6a7988-8a7b6c5d",  quotaGb: 40,})) as Record<string, unknown>;console.log(created.id, created.state);

   GoCopy

   created, err := kl.Environments.Clone(kloudlite.CloneEnvironment{    Environment: "acme/dev",    To:          "dev-before-migration",    Snapshot:    "env-1f2e3d4c5b6a7988-8a7b6c5d",    QuotaGb:     40,})if err != nil {    log.Fatal(err)}fmt.Println(created["id"], created["state"])

   RubyCopy

   created = kl.environments.clone(environment: "acme/dev", to: "dev-before-migration", snapshot: "env-1f2e3d4c5b6a7988-8a7b6c5d", quota_gb: 40)puts created.values_at("id", "state").join(" ")

   JavaCopy

   String created = kl.environments().clone(new Kloudlite.CloneEnvironment()    .environment("acme/dev")    .to("dev-before-migration")    .snapshot("env-1f2e3d4c5b6a7988-8a7b6c5d")    .quotaGb(40));System.out.println(created);

   CLICopy

   kloudlite environments clone acme/dev --to dev-before-migration --snapshot env-1f2e3d4c5b6a7988-8a7b6c5d --quota-gb 40

Close-out

1. Wait until the state of the new environment is running.
2. Examine service_status of the new environment. Make sure that each service is ready.

Restore an environment from a snapshot

Reason for the task: Put an environment back to the services and the data of one of its snapshots.

Job set-up

• Access: you. A team environment needs team membership.
• Conditions: you know the id of a ready snapshot of this environment. No service that the restore removes has an intercept.
• References: POST /v1/environments/{id}/restore, Remove an intercept.

Procedure

1. Restore the environment. Use the id of the snapshot for snapshot.

   PythonCopy

   plan = kl.environments.restore(environment="acme/dev", snapshot="env-1f2e3d4c5b6a7988-8a7b6c5d")print(plan)

   TypeScriptCopy

   const plan = await kl.environments.restore({ environment: "acme/dev", snapshot: "env-1f2e3d4c5b6a7988-8a7b6c5d" });console.log(plan);

   GoCopy

   // Environments.Restore keeps only the error, so read the answer with a raw request.var plan anyif err := kl.Request("POST", "/v1/environments/dev/restore", kloudlite.RequestOptions{    Query: url.Values{"owner": {"acme"}},    Body:  map[string]any{"snapshot_id": "env-1f2e3d4c5b6a7988-8a7b6c5d", "discard": []string{}},    Out:   &plan,}); err != nil {    log.Fatal(err)}fmt.Println(plan)

   RubyCopy

   plan = kl.environments.restore(environment: "acme/dev", snapshot: "env-1f2e3d4c5b6a7988-8a7b6c5d")p plan

   JavaCopy

   String plan = kl.environments().restore(new Kloudlite.RestoreEnvironment().environment("acme/dev").snapshot("env-1f2e3d4c5b6a7988-8a7b6c5d"));System.out.println(plan);

   CLICopy

   kloudlite environments restore acme/dev --snapshot env-1f2e3d4c5b6a7988-8a7b6c5d

2. If the call returns 409 with a list lost, restore again. Name those services in discard, or repeat --discard SERVICE in the CLI.

   PythonCopy

   plan = kl.environments.restore(environment="acme/dev", snapshot="env-1f2e3d4c5b6a7988-8a7b6c5d", discard=["redis"])print(plan)

   TypeScriptCopy

   const plan = await kl.environments.restore({ environment: "acme/dev", snapshot: "env-1f2e3d4c5b6a7988-8a7b6c5d", discard: ["redis"] });console.log(plan);

   GoCopy

   err := kl.Environments.Restore(kloudlite.RestoreEnvironment{Environment: "acme/dev", Snapshot: "env-1f2e3d4c5b6a7988-8a7b6c5d", Discard: []string{"redis"}})if err != nil {    log.Fatal(err)}

   RubyCopy

   plan = kl.environments.restore(environment: "acme/dev", snapshot: "env-1f2e3d4c5b6a7988-8a7b6c5d", discard: ["redis"])p plan

   JavaCopy

   String plan = kl.environments().restore(new Kloudlite.RestoreEnvironment().environment("acme/dev").snapshot("env-1f2e3d4c5b6a7988-8a7b6c5d").discard("redis"));System.out.println(plan);

   CLICopy

   kloudlite environments restore acme/dev --snapshot env-1f2e3d4c5b6a7988-8a7b6c5d --discard redis

Close-out

1. Read rolled_back, added, removed and discarded in the answer.
2. Wait until the state of the environment is running.

Troubleshooting