Skip to main content

​
Environments

An environment is one running instance of a template, leased by your organization. It runs on a hot node in its own container under gVisor, with its own network and volumes. Deleting it removes the container and its data; the node keeps running for the next lease. Every environment has:
  • a name, such as linux-build-3f2a, which is also its name on the tailnet, and an ID such as env_…;
  • a state: pending, starting, ready, stopping, stopped or failed;
  • labels, key=value pairs you set with --label to find it again;
  • an idle timeout and a hard limit. An environment nobody uses stops after its idle timeout, and every environment stops at its hard limit, at most 24 hours.
Your organization can run 10 environments at once unless an admin sets other limits.

​
Templates

A template is what an environment is made from: an image, the command it runs, the services it exposes, the folders it shares, and its CPU, memory and timeouts. envctl templates lists them. Nodes keep a warm slot of each template: a container that’s created but not yet started. A new environment usually starts from one in three to four seconds.

​
The sandbox

The sandbox is the machine you work from: your laptop, a CI runner, or an agent-sandbox. envctl sandbox up runs envd there and joins it to your organization’s tailnet. Each environment you lease is wired to your sandbox, and only to it:
  • its services appear on your sandbox’s localhost;
  • its shares sync folders between the two;
  • envctl exec runs commands in it.
Another organization’s environments are on a different tailnet and can’t be seen or reached.

​
Shares

A share is a folder that syncs one way. Templates name their shares:
  • in shares go from your sandbox to the environment, like src for linux-build, which maps a folder you name to /work;
  • out shares come back, like out, which brings /work/out to .remote/<environment>/out/ on your sandbox.
Files travel as content-defined chunks: an edit sends only the chunks it touched. .gitignore files are honoured, and secret files never leave your machine unless you name them one at a time. See File sync.

​
Services

A template’s exports are the services it offers, such as postgres on port 5432. When you lease one with a sandbox, envd listens on your sandbox’s 127.0.0.1 at the same port, or the next free one, and carries each connection over the tailnet. Nothing listens on a public address.

​
Projects and keys

Everything an environment’s files are stored as is sealed under a project key. The project is named after your folder’s git remote and path, such as github.com/acme/app/tools/cli, or whatever you pass with --project. Each organization’s key wraps its projects’ keys, and a KMS key wraps every organization’s key. Two projects never share a key, so one project’s data is useless to another. See Encryption.

​
Snapshots

A snapshot is a share’s files, saved in object storage under a key such as main when an environment ends. A later environment can start from it, and its first sync then sends only what changed. See Snapshots.

​
Artifacts

An artifact is a file you keep for people to fetch, such as a build’s binary, with an expiry and signed download links. See Artifacts.

​
Organizations and tokens

You belong to an organization. Everything you lease, store and see belongs to it. You authenticate with a CLI token from the console (Settings → CLI tokens), one per machine, which you can revoke. Admins can also create organization API keys.