An Environment is the project a harness starts every task from.

What it is

An environment is a project and its installed packages, built once, that every task of a harness starts from. The task finds the project at a fixed path, read only, with its Python, Node and system packages already in place, and writes its own results beside it.

Nothing is uploaded or installed at the start of a task, and two tasks never see each other's work. Without an environment a task starts from an empty working directory and installs what it needs every run.

When to use one

• A task needs a codebase, data files or templates that do not change between tasks.
• A task needs packages, such as pandas, a TypeScript compiler or ffmpeg, that would otherwise be installed on every run.
• Several harnesses, or many tasks of one harness, should start from the same project.

What a task gets

The environment's interpreter and packages are the ones the agent's shell runs: python3 is the environment's virtualenv, node sees its node_modules, and system packages from apt are on PATH. The agent's instructions name the path, say that it is read only and that the dependencies are installed, and say where to write.

The environment

At /env/<slug>, also $PROJECT_ROOT. Read only, and shared by every task that names it.

The task's working directory

The current directory. Writable, private to the task, and the source of the files it returns.

Creating one

• Open Environments in the console and choose New environment. Its name gives the path tasks will see, so name it after the project.
• Add the project by uploading files, importing an archive or importing a git repository. The tree is kept, and dependency directories such as node_modules and .venv are never imported.
• Declare packages on the Packages tab, one list per manager: pip, npm and apt, with or without a pinned version. Each name is checked against its registry as you add it, so a typo or a version that was never published is refused where you type it. The project's own requirements.txt, pyproject.toml and package.json are installed too.
• Choose the Python version when the project needs a specific one.
• Save changes builds the environment. A pop up shows the build's step, its elapsed time and the installers' own output, and the packages show their installed versions once it is ready.

Versions and rollback

Every build is a version. A new build becomes the active one only when it succeeds, so a failed build never breaks tasks that are already running, and an earlier version can be made active again with one click.

Attaching it to a harness

Open the harness settings and choose the environment in the Workspace field. From then on every task of that harness starts with the project in place. The session records which environment and version it read, and the response carries it as metadata.environment.

From the API

A harness names its environment with "environment": "henv_...". A task may name a different one for itself with "metadata": {"environment": "henv_..."} on the request, the same place the harness id travels.

POST   /v1/environments                              create: {"name": "Content Studio"}
PUT    /v1/environments/{id}/files/{path}            write one file, the body is its bytes
POST   /v1/environments/{id}/import                  an archive, or {"git_url": "..."}
PUT    /v1/environments/{id}                         declare packages: {"packages": {"pip": [], "npm": [], "apt": []}}
POST   /v1/environments/{id}/build                   build the next version
GET    /v1/environments/{id}/builds/{n}              its status, step and log while it runs
POST   /v1/environments/{id}/versions/{n}/activate   roll back to an earlier build
GET    /v1/environments/packages/check               what the registry says, before a build

Isolation

• The environment is read only for every task.
• It is readable only by tasks of harnesses that name it, and invisible to every other task.
• Package installs run during the build, never inside a task.
• A task's own files stay in its working directory and are downloadable as before.

Limits

Declared packages

Up to 200 per manager.

Build time

A wall clock of 30 minutes.

Tree listing

Up to 20,000 entries are returned.

One file

Up to 64 MiB.

One import

Up to 512 MiB per archive.

A built version

Up to 1536 MiB.