Environments

Environments are built from a Dockerfile into a sandbox image. See versions and build logs in the dashboard, then open a browser terminal and git pane on a running sandbox.

An environment is the computer a coding agent runs on. It bundles five things.

Part	What it is
Image	A Dockerfile that Helios builds and stores. Every build is a version.
Secrets	Key-value pairs injected into the sandbox at boot.
Cloud-init	A script that runs when the sandbox starts.
Integrations	Connected apps the agent can reach from inside the sandbox.
Coding agent	The harness to start. Claude Code is the only option. See Claude Code.

Environments are different from the sandboxes that chats and workflows use. Those come from a fixed Helios image. See sandboxes. Environments are yours to define.

Create an image

Open Environments in the dashboard.
Choose Create sandbox image.
Give it a name, for example node-20-chromium.
Paste a Dockerfile.

Helios builds the sandbox image in the cloud. The list shows the build status of every image. Search filters the list by name.

You can also define images as YAML and apply them from the CLI. See IaC.

What the Dockerfile needs

The image must contain two things for Helios to attach to it.

helios-agent. The terminal broker and event daemon. The browser terminal and the CLI connect to it on port 7681.
The coding harness. For Claude Code that is the @anthropic-ai/claude-code package.

For detach and reattach from the terminal app, install a session manager. shpool or tmux both work. Set the one you use in the environment.

The starter Dockerfile from helios code iac scaffold installs all of these on Ubuntu 24.04 with Node 20. Start from it and add your own toolchain.

The image page

Open an image to see three tabs.

Overview. The current build and its status. A failed build is marked here.
Versions. Every build, newest first, with logs. A build that is still running streams its log live.
Dockerfile. The Dockerfile the image was built from.

Rebuild from the CLI at any time.

helios code images build <id> --label "node 22"

Pass --dockerfile to build a new Dockerfile without opening the dashboard.

Versions

Each build creates a new version. Environments point at the image by id. Helios only rebuilds when the Dockerfile changes. helios code apply --force rebuilds anyway.

Create an environment

Create one from the CLI.

helios code environments create --alias starter --image-id <image-id> --agents claude_code

Add secrets, a cloud-init script, and integrations with the matching flags.

helios code environments update <id> --secrets '{"NPM_TOKEN":"..."}' --integration-ids <id>,<id>

List and inspect environments.

helios code environments list
helios code environments get <id>

Delete one when it is no longer used.

helios code environments delete <id> --yes

The terminal and git panes

Launch a sandbox from the CLI, then open the Code page for its image to work with it in the browser. The page also lets you stop the sandbox.

The terminal pane is a shell in the sandbox. It connects to helios-agent.
The git pane lists changed files in the working repository, split into staged and unstaged.

From the terminal app, the same session shows the harness in one tab and a live diff per repository in a files tab.

Launch from the CLI

helios code launch <environment-id> --attach

Add --git-repo <url> to clone a repository into ~/workspace before the harness starts. Add --timeout <ms> to cap the session.

Watch the boot from another terminal.

helios code logs <agent-id> --follow

Stop an agent.

helios code kill <agent-id> --yes

Secrets set on the environment are injected at boot and never written into the image. The starter image includes vals, so a secret value can be a reference such as ref+infisical://... that is resolved when the sandbox starts.

On this page