HELIOS DOCS

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.

PartWhat it is
ImageA Dockerfile in the project's Library at images/<name>/Dockerfile. Every saved version builds, and the environments on it switch over.
SizeCPU count and memory of the environment's sandboxes.
Coding agentThe agent that runs in the sandbox: OpenCode, Claude Code or Codex. See coding agents.
VariablesVariables and secrets of the environment. They override the project's and arrive as environment variables in the sandbox.
Coding agent settingsSettings the coding agent in the sandbox starts with.
IntegrationsWhat 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@10

public.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 agentRuns on
OpenCodeHelios credits. Built into Helios, nothing to connect.
Claude CodeEach person's own Claude subscription.
CodexEach person's own ChatGPT subscription.

To use Claude Code or Codex:

  1. Open Integrations in the project and connect your Claude account or Codex account. Each person connects their own.
  2. Create an environment with that coding agent, or pick one in a new chat.
  3. 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