Environment discovery
How hlix reconstructs a local development environment, collects protected configuration, and produces a reviewable cloud setup plan.
hlix import scans the repository, its local configuration and the invoking process environment to prepare a cloud project.
The scan produces a source snapshot and an environment plan. Source files and scanned Git history move through HLIX Repos. Protected files and secret values take a separate encrypted path.
Prerequisites
Section titled “Prerequisites”- The CLI is installed and authenticated
- The shell you run
hlix importfrom holds the environment values the project expects — for a key declared or referenced by the project but absent from a file, the invoking process is where hlix looks
Review the detected environment
Section titled “Review the detected environment”Run hlix import . --dry-run to inspect the source files, setup commands, runtime versions, ports and required configuration. The scan reads project files without running their commands locally. Setup runs in the project’s Cloud Machine.
Use an explicit environment file or development-container configuration when you need to control the result. Otherwise, Hlix fills in the plan from the project’s manifests and lockfiles.
Detection order
Section titled “Detection order”| Priority | Evidence | What hlix uses |
|---|---|---|
| 1 | .cursor/environment.json |
install, start, terminal, and working-directory intent |
| 1 | .devcontainer/devcontainer.json, devcontainer.json |
lifecycle setup, forwarded ports, container/remote variables, and declared secret names |
| 2 | Docker, Compose, .gitpod.yml, Procfile |
explicit platform and process evidence; unparsed commands remain visible for review |
| 2 | project.toml, railpack.json, nixpacks.toml, Aptfile |
Buildpack and build-plan intent |
| 2 | fly.toml, railway.json, render.yaml, vercel.json, netlify.toml |
deployment settings |
| 3 | package.json, lockfiles, Python manifests, go.mod |
package manager, runtime, dependency installation, build, and start inference |
| 4 | .node-version, .nvmrc, .python-version, .tool-versions, mise.toml |
pinned Node.js, Python, and Bun runtime versions |
| 5 | repository references such as ${DATABASE_URL} |
observed environment key names and private-port hints |
Explicit configuration fills the plan first. Lower-priority detectors fill gaps rather than replacing reviewed intent. Repeated install commands are deduplicated.
Project secrets
Section titled “Project secrets”| Source | How it is handled |
|---|---|
| A key declared by environment or MCP configuration | Its value is required before import can proceed |
| A key referenced by project code | A matching local value is collected; a missing value produces a warning |
A protected file, such as .env.local or registry credentials |
Encrypted separately and excluded from the source commit |
| Project skills and MCP configuration | Preserved as protected resources; recognized MCP connections retain their enabled state |
Reports show key names and paths. Values travel through the encrypted protected-file path. See Secrets & protected files for handling and rotation.
Hlix collects values for keys declared or referenced by the selected project, including values resolved in the invoking shell. Login credentials and ambient runtime variables such as HOME, PATH and CI are excluded from that collection.
For .envrc, literal assignments can be read directly. Resolve dynamic values with direnv before importing: the scanner reads the resulting environment value rather than running the assignment.
Review the actual plan
Section titled “Review the actual plan”hlix import . --dry-runFor automation, save the report for review:
hlix import . --dry-run --json > /tmp/hlix-import-plan.jsonThen run the import interactively, or pass --yes in a non-interactive job. Each invocation prepares its own plan. Resolve any scan blockers before uploading.
If the plan is wrong
Section titled “If the plan is wrong”- The wrong dotenv profile is active. Pass
--env-file <path>; every other profile is still preserved encrypted. - A required key is missing and import blocks. Add the value to the declared source, or to the invoking shell, and scan again — a declared key is fatal, an observed one is only a warning.
- A
.envrckey resolved to nothing. A dynamic assignment such as$(op read …)is never executed. Let direnv resolve it into your shell first, then re-run the scan. - A setup command you do not recognise appears in the review. Check the source file and correct the command before approving the import.
- The stack or install command is wrong. Override with
--stack, or add explicit intent in.cursor/environment.jsonor a Dev Container file — explicit configuration outranks every inference. - Confidence is low with no evidence listed. The scanner found no recognised configuration. Add one explicit source rather than relying on inference.