Environments
An environment runs a sandbox image at its CPU and memory with one coding agent, and carries variables and coding agent settings. Projects set a default environment, and a new chat or an automation can pick another one. A changed Dockerfile builds a new version and the environments on it switch over.
Every agent runs in a sandbox. An environment says what that sandbox starts with. Each project has its own environments, and chats and workflow runs in the project use them.
| Part | What it is |
|---|---|
| Image | A Dockerfile in the project's Library at images/<name>/Dockerfile. Every saved version builds, and the environments on it switch over. |
| Size | CPU count and memory of the environment's sandboxes. |
| Coding agent | The agent that runs in the sandbox: OpenCode, Claude Code or Codex. See coding agents. |
| Variables | Variables and secrets of the environment. They override the project's and arrive as environment variables in the sandbox. |
| Coding agent settings | Settings the coding agent in the sandbox starts with. |
| Integrations | What a chat on the environment starts with. |
An image builds into sandbox templates. The Dockerfile builds once per saved version at 2 vCPU and 4 GB, and that build derives one template per other size the environments on the image use. New sandboxes of an environment start from the build at its image and size. When an environment is created or its image or size changes, the missing build starts. Until it is ready, the environment keeps running its previous build, and a new environment cannot start chats yet. The environment's page shows whether it is ready, updating, or whether its last build failed.
The default environment
A project without an environment uses the Helios default: the base image as it is, with 2 CPUs and 4 GB of memory, on OpenCode. The dashboard shows it under Environments in every project, so you can see what your agents run on before you change anything. Clone to edit gives the project an environment on its own copy of the base image.
Images
An image is a Dockerfile in the project's Library at
images/<name>/Dockerfile. Open Images in a project and choose New image, then edit the
Dockerfile on the image's page or in the Library, with history and diffs. An agent in a chat on the
project can edit it too. The image's page shows the environments that run it and their build status.
Every Dockerfile must start from the Helios base image:
FROM public.ecr.aws/warpbuilds/helios-sandbox:v0.1.0
RUN apt-get update && apt-get install -y --no-install-recommends postgresql-client \
&& rm -rf /var/lib/apt/lists/*
RUN npm install -g pnpm@10public.ecr.aws/warpbuilds/helios-sandbox is the Helios base image: Debian with Node.js, Bun, Git
and the Helios agent runtime. A new image starts from the release Helios is on, such as v0.1.0,
and stays on it until you change the tag. The tag latest follows every release. The
registry lists the releases.
Add your own tools on top with RUN, ENV and WORKDIR. There is no build context, so fetch
files with RUN curl instead of COPY. ENV applies to the build only: later RUN steps see
it, a running sandbox does not. Set sandbox variables under
Variables instead. Do not change the user and do not add a
coding agent. Helios installs the agent at the first start of a sandbox and keeps it current. E2B
builds the Dockerfile; a Dockerfile it cannot build fails, and the build log says why.
Changing a Dockerfile
Every saved version of the Dockerfile, by a person or by an approved agent change, builds. The Dockerfile build runs first, then a build for each size in use. Each environment switches to the build at its size when that build succeeds. Chats that already run keep their sandbox until their next message, which then starts a sandbox from the new build. A failed build leaves the environments on their previous build. The image's page lists the builds and shows their logs. Rebuild on the image builds the current Dockerfile again, for example after a failed build.
Renaming or deleting the Dockerfile in the Library is not followed: environments keep their last build and their next build fails until they point at an image that exists. Deleting an environment's file in the Library deletes the environment. A file that is not valid JSON, or that names an image that does not exist, leaves the environment as it was and shows the reason on its page.
Environments
An environment is a file in the project's Library too, environments/<name>/environment.json,
with its image, size, coding agent, coding agent settings and integration selection. The environment page edits that
file, and so can an agent through a change request. Every saved version is kept: the page's
History tab lists them and Restore makes an older one live again, as a new version. The
same History sits on an image's page for its Dockerfile. A restored Dockerfile that was built
before reuses that build. Variables and secrets are not part of the file.
Open Environments in a project and choose New environment. Pick an image, a size and a coding agent and give the environment a name. The image builds at that size when no such build exists. Then add variables under its Variables tab, and coding agent settings if you need them.
Set a project's default environment under Default environment in the project's settings, or with Use as project default in the environment's menu. New chats and automations in the project use it unless they pick another one. When the new default runs another coding agent, Helios asks first and says which automations switch with it.
A new chat picks its environment in the chat box, next to the model. On Home, one control picks the project and its environment. A chat keeps the environment it started on. To use another one, start a new chat.
An automation has an Environment field when you create it and in its settings. The choice marked Project default follows the project's default environment, also when that changes later. An automation that an agent creates in a chat runs in the chat's environment.
Deleting an environment moves the automations that ran on it to the project's default. The delete dialog lists them first.
Coding agents
The coding agent is the program that works in the sandbox. An environment runs one.
| Coding agent | Runs on |
|---|---|
| OpenCode | Helios credits. Built into Helios, nothing to connect. |
| Claude Code | Each person's own Claude subscription. |
| Codex | Each person's own ChatGPT subscription. |
To use Claude Code or Codex:
- Open Integrations in the project and connect your Claude account or Codex account. Each person connects their own.
- Create an environment with that coding agent, or pick one in a new chat.
- For automations, have a service account that acts as you. The automation runs as it, on your account. A new automation on Claude Code or Codex gets it by itself when you have one.
A chat on Claude Code or Codex stops before it starts when its sender has no connected account, and says how to connect it. The model picker lists the models the environment's coding agent can run.
Integrations
Every chat has its own integration menu, where you attach resources such as a repository or a channel. An environment sets what its chats start with: open its Integrations tab and pick the resources. A new chat on the environment begins with that selection, and the chat can still add or remove integrations afterwards. Every connected integration stays available either way.
Variables
Variables and secrets follow the usual levels. An environment sits between the project and the user: an environment variable overrides the project's value of the same key. The resolved set is passed to the sandbox as environment variables, so tools in the sandbox read them like any other. Secrets are decrypted for the sandbox only.
Permissions
Images and environments are project resources. Reading them needs the viewer role on the project.
Creating, building and changing them needs editor. See
roles and permissions.
Last updated on
Sandboxes
Helios agents run in isolated cloud sandboxes with a shell, a filesystem, code execution, web access, and the Library mounted read-only or read-write.
Context
Helios agents start each run in a fresh sandbox. The Library carries files between runs, and only approved changes reach it. Helios also records how an agent used an API before.