Environments

Overview

An environment is your app's services, shared by many desks. The services 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 desk. 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 desks can connect to one environment.

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

States

Lifecycle

• Idle stop. An environment runs while a connected desk is awake. After 5 minutes with none awake, it stops and sets idle_since. Using a connected desk 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 desk, awake or idle, is in use and is never deleted.
• Delete. The services and the disk are removed. Connected desks are disconnected, not ended. Snapshots stay.
• Machine loss. If the machine that runs an environment fails or is reclaimed, the platform starts the services on another machine. Processes and memory are lost. Data that the services synced to disk is kept.
• Storage failure. If a storage machine fails, the storage serves the volume from its second copy and the services keep running.

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 makes a copy of the source in seconds. It has the owner and the region of the source. The answer has based_on: snapshot names the copy, age_seconds is always 0, and interrupted is always false.

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 desks, the intercepts, or the time to live of its source. The new environment has no connected desk. A clone counts as a new environment against the quota of the owner.

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

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 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. The check looks only at services and their folders. A service in rolled_back is never in lost: its rows written after the snapshot are gone without a 409.

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.

Databases

A database in a service writes to the disk of the environment. The platform keeps every write that the database synced to disk, also when a machine fails. A write that stays in memory is lost.

A database restarts as after a power cut. It replays its own log. A snapshot and a clone hold the same state that a power cut leaves.

A SQLite database needs a safe setting to keep its last commit when a machine fails abruptly. Use PRAGMA synchronous=EXTRA, or use WAL mode with PRAGMA journal_mode=WAL. The setting synchronous=FULL in rollback-journal mode lost the last acknowledged commit in 2 of 7 abrupt kills. The setting synchronous=EXTRA lost it in 0 of 6.

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 Kodekl = 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"}]}],)print(env["id"], env["state"])

   TypeScriptCopy

   import { Kode } 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" }],  }],})) 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" }] }],)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"))    ));

   CLICopy

   kode environments create acme-dev --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. kode 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

   kode 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

   kode 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

   kode environments stop acme-dev

Close-out

1. Make sure that state is stopped.

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

   kode 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

   kode environments delete acme-dev

Close-out

1. Make sure that the environment is no longer listed. A warning in the response names a desk 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, kode 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

   kode environments list

Close-out

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

Clone an environment

Reason for the task

Create 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 List 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

   kode 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.

   PythonCopy

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

   TypeScriptCopy

   const created = (await kl.environments.clone({  environment: "acme/dev",  to: "dev-before-migration",  snapshot: "env-1f2e3d4c5b6a7988-8a7b6c5d",})) 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")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")    );System.out.println(created);

   CLICopy

   kode environments clone acme/dev --to dev-before-migration --snapshot env-1f2e3d4c5b6a7988-8a7b6c5d

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

   kode 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

   kode 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