Env Vars

Description and operation

General

A process reads its settings from environment variables. You give the variables of a workspace, a sandbox, a service or a pipeline job in its env field. A variable holds its value in plain text, or refers to a secret.

A secret is a named value that the platform keeps for an owner, such as a password, a token or a connection string. You set it once and refer to it by name. The platform puts the value in the variable when the process starts. The value never shows in a definition, a document or a log.

Personal secrets in a team

A personal secret in a team is a secret that you keep for yourself inside one team, for example your own access token. Only you can set it, show its name or delete it. See Set a personal secret in a team.

Only your own resources in that team read it: your team workspaces, benches and sandboxes. Resources that the team shares never read it, so your value never goes to another member.

A reference in your resource of the team finds the value in this order.

Use a variable for a setting such as LOG_LEVEL. Use a secret for a password, a key or a token.

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

Reference syntax

A reference is a variable value that is exactly this text, where NAME is the name of a secret.

${{ secrets.NAME }}

Owner and scope

A resource reads the secrets of its own owner. A personal resource reads only your secrets. A team resource reads the secrets of the team. Your own team workspace, bench or sandbox reads your personal secrets in the team first. A name is unique in one store, so you, your team and your personal secrets in the team can each have a secret DB_URL.

Delivery

A reference is valid in these fields. The value reaches the process as an environment variable.

The SSH sessions of a workspace start from the tool server, so they have the same variables as its processes.

When a new value takes effect

A resource reads a secret when its processes start. A replaced value does not change a process that runs, and the platform does not restart it. To apply the value, restart the resource, or set restartOnEnvChange to true to restart it each time.

Pipelines

Quota and limits

Secrets do not count against the quota of the owner. See also Limits.

Tasks

Use a secret in a workspace

Reason for the task: Give a workspace the value of a secret as a variable.

Job set-up

• Access: you.
• Conditions: the secret exists for the owner of the workspace. See Set or replace a secret.
• References: PUT /v1/workspaces/{id}/env, kloudlite workspaces set-env.

Procedure

1. Send the complete list of variables, with the reference.

   PythonCopy

   from kloudlite import Kloudlitekl = Kloudlite()kl.workspaces.set_env(workspace="acme/api", env={"DB_URL": "${{ secrets.DB_URL }}"})

   TypeScriptCopy

   import { Kloudlite } from "./index.ts";const kl = new Kloudlite();await kl.workspaces.setEnv({ workspace: "acme/api", env: { DB_URL: "${{ secrets.DB_URL }}" } });

   GoCopy

   kl := kloudlite.New(kloudlite.Options{})if _, err := kl.Workspaces.SetEnv("acme/api", map[string]string{"DB_URL": "${{ secrets.DB_URL }}"}); err != nil {    log.Fatal(err)}

   RubyCopy

   require_relative "kloudlite"kl = Kloudlite::Client.newkl.workspaces.set_env(workspace: "acme/api", env: { "DB_URL" => "${{ secrets.DB_URL }}" })

   JavaCopy

   var kl = new Kloudlite();kl.workspaces().setEnv("acme/api", Map.of("DB_URL", "${{ secrets.DB_URL }}"));

   CLICopy

   kloudlite workspaces set-env acme/api --env 'DB_URL=${{ secrets.DB_URL }}'

2. Stop the workspace, then start it. See Stop a workspace and Start a workspace.

Close-out

1. Run test -n "$DB_URL" && echo set in the workspace. Make sure that the output is set.

Use a secret in a service

Reason for the task: Give a service of an environment the value of a secret as a variable.

Job set-up

• Access: you. A team environment needs team membership.
• Conditions: the secret and the service exist. See Set or replace a secret and Add a service.
• References: PATCH /v1/environments/{id}, kloudlite environments set-services.

Procedure

1. Send the service list with the reference in the env of the service, here api.

   PythonCopy

   env = kl.environments.get(environment="acme-dev")services = [    {**sv, "env": {**sv["env"], "DB_URL": "${{ secrets.DB_URL }}"}} if sv["name"] == "api" else sv    for sv in env["services"]]kl.environments.set_services(environment="acme-dev", services=services)

   TypeScriptCopy

   import { type Service } from "./index.ts";const env = (await kl.environments.get({ environment: "acme-dev" })) as { services: Service[] };const services = env.services.map((sv) =>  sv.name === "api" ? { ...sv, env: { ...sv.env, DB_URL: "${{ secrets.DB_URL }}" } } : sv,);await kl.environments.setServices({ environment: "acme-dev", services });

   GoCopy

   env, err := kl.Environments.Get("acme-dev")if err != nil {    log.Fatal(err)}var services []kloudlite.Serviceraw, _ := json.Marshal(env["services"])if err := json.Unmarshal(raw, &services); err != nil {    log.Fatal(err)}for i := range services {    if services[i].Name == "api" {        if services[i].Env == nil {            services[i].Env = map[string]string{}        }        services[i].Env["DB_URL"] = "${{ secrets.DB_URL }}"    }}if err := kl.Environments.SetServices(kloudlite.SetServices{Environment: "acme-dev", Services: services}); err != nil {    log.Fatal(err)}

   RubyCopy

   env = kl.environments.get(environment: "acme-dev")services = env["services"].map do |sv|  sv["name"] == "api" ? sv.merge("env" => sv["env"].merge("DB_URL" => "${{ secrets.DB_URL }}")) : svendkl.environments.set_services(environment: "acme-dev", services: services)

   JavaCopy

   // Replaces the list: describe every service, with the reference in api.var api = new Kloudlite.Service().name("api").image("ghcr.io/acme/api:1.0").port(8080)    .env("DB_URL", "${{ secrets.DB_URL }}");kl.environments().setServices(new Kloudlite.SetServices().environment("acme-dev").services(api));

   CLICopy

   # Replaces the list: send every service, with the reference in api.kloudlite environments set-services acme-dev --services '[  {"name": "api", "image": "ghcr.io/acme/api:1.0", "ports": [8080], "env": {"DB_URL": "${{ secrets.DB_URL }}"}}]'

Close-out

1. Get the environment again. Make sure that service_status shows api as ready.

Use a secret in a pipeline

Reason for the task: Give the steps of a pipeline job the value of a secret as a variable.

Job set-up

• Access: you. For a team, an admin.
• Conditions: the secret exists for the owner of the pipeline. See Set or replace a secret.
• References: Pipeline definition.

Procedure

1. Add the name of the secret to the secrets list of the job. The variable has the same name.

   jsonCopy

   { "jobs": { "deploy": { "secrets": ["KUBECONFIG_PROD"] } } }

2. Give a secret to one step under another variable name. Put the reference alone in the value.

   jsonCopy

   { "steps": [{ "run": "./deploy.sh", "env": { "TOKEN": "${{ secrets.DEPLOY_TOKEN }}" } }] }

3. Send the definition as the next version of the pipeline.

Close-out

1. Start a run and read the log. Make sure that it shows *** for each secret value.

Use a secret in a sandbox

Reason for the task: Give the main process of a sandbox the value of a secret as a variable.

Job set-up

• Access: you. A team sandbox needs team membership.
• Conditions: the secret exists for the owner of the sandbox. See Set or replace a secret.
• References: POST /v1/sandboxes, kloudlite sandboxes create.

Procedure

1. Create the sandbox with the reference in env. Add team for a team sandbox.

   PythonCopy

   sb = kl.sandboxes.create(cmd=["sh", "-c", 'test -n "$DB_URL" && echo set'], env={"DB_URL": "${{ secrets.DB_URL }}"})

   TypeScriptCopy

   const sb = await kl.sandboxes.create({ cmd: ["sh", "-c", 'test -n "$DB_URL" && echo set'], env: { DB_URL: "${{ secrets.DB_URL }}" } });

   GoCopy

   sb, err := kl.Sandboxes.Create(kloudlite.CreateSandbox{Cmd: []string{"sh", "-c", `test -n "$DB_URL" && echo set`}, Env: map[string]string{"DB_URL": "${{ secrets.DB_URL }}"}})if err != nil {    log.Fatal(err)}

   RubyCopy

   sb = kl.sandboxes.create(cmd: ["sh", "-c", 'test -n "$DB_URL" && echo set'], env: { "DB_URL" => "${{ secrets.DB_URL }}" })

   JavaCopy

   var sb = kl.sandboxes().create(new Kloudlite.CreateSandbox().cmd(List.of("sh", "-c", "test -n \"$DB_URL\" && echo set")).env(Map.of("DB_URL", "${{ secrets.DB_URL }}")));

   CLICopy

   kloudlite sandboxes create --env 'DB_URL=${{ secrets.DB_URL }}' -- sh -c 'test -n "$DB_URL" && echo set'

Close-out

1. Read the output of the sandbox as in Read the output and the exit code. Make sure that the output is set.

Troubleshooting