Environments, images and registries
What agents' environments are, how kosem pulls their images from private registries, and how prepared images make them start faster.
An environment is an isolated Linux machine that an agent works in: it runs the agent's commands, with a disk of its own that keeps your files while it's stopped, except /tmp and /run. Its image supplies the operating system, packages and tools. Registries let kosem pull private images without a credential ever entering an environment, and prepared images let environments start from a large image faster.
Environments
Each agent has one environment, which it creates and starts as its commands need it. People see a project's environments under Environments, where they can stop, purge and restart, or delete them.
- What's in it: an image, such as
node:24or your team's devcontainer image, a number of vCPUs, memory and a disk. Your plan and project policies set the most each can be. - What it keeps: its disk, including
/workspace, your home directory and installed packages, while it's stopped./tmp,/run, processes and memory don't survive a stop. Purge and restart wipes the disk and starts fresh from the image. - When it stops: after 5 minutes unused by default, with no turn step running and no background job that the agent waits to hear the end of. A job it won't hear of, such as a server it left running, doesn't keep the environment running, and ends as it stops. Once stopped, it's deleted after 2 days by default, with its disk and everything on it. The agent's settings can set other times, within the limits.
- What it shows: under Environments, each environment's Last used, and how many background jobs run in it, which don't count as using it.
When an environment starts, kosem pulls its image the way your project's environments are set up to: through the registry that covers it, if there is one, or without signing in.
Registries
A registry tells kosem how to sign in to a container registry to pull private images, such as ghcr.io/acme. Your organization's is set up once and shared with projects; a project can also have its own, for itself alone. It does only that: no environment ever sees its token or credentials.
- Its prefix is what it covers: a host, such as
ghcr.io, and a path in it, such asghcr.io/acme. An image is pulled with the registry of the longest prefix that covers it, among the project's own and those shared with it, and of two with the same prefix, the project's own. - It signs in with a username and a token kept as a secret, or, on Google Artifact Registry and Amazon ECR, with no key at all: your cloud trusts kosem's identity token for the registry, as it would a workload in its own account.
- Projects ask for one, or add their own. Someone who can't create registries requests one for an image, from the project's Registries page. Owners see what's asked, and approve a request by sharing a registry that covers it. A policy, Turn off projects' own registries, keeps projects from adding their own.
Images
An image that kosem prepares starts environments faster, and they read its files faster: kosem pulls it once, builds a copy for environments to run, and keeps it. The image picker lists prepared images, each saying whether it's ready.
- It follows its tag, unless you turn that off. kosem checks the tag every hour and prepares each new version it finds, so your CI only pushes.
- It keeps its newest versions, 3 unless you set 1 to 10. An older version is deleted once no environment runs it.
- An organization's images are shared with all of its projects or the ones you select, as registries are.
- Its size counts against your organization's image storage quota.
Why it works this way
- No credential in an environment. Whatever runs in an environment, including what an agent downloads, could read a credential there. kosem signs in to registries for environments, and keeps the credentials to itself.
- Prepared images trade storage for start time. An environment of a large image waits for its pull at every start; a prepared image is ready for it, and kosem's copy needs nothing of your registry, so it keeps working even after your registry deletes that version.
Who can do what
| To | You need, on the project or the organization |
|---|---|
| See environments, registries and images | Any basic role, Environment Viewer, Environment User or Environment Admin |
| Create, change and delete registries and images, a project's own on the project | Owner, Editor or Environment Admin. A registry's token also takes access to its secret's value |
| Share registries and organization images with projects, and answer registry requests | Owner, on the organization |
| Request a registry for a project | Owner, Editor, Environment User or Environment Admin, on the project |