Import trust model
hlix treats repository content as untrusted input until a specific action authorizes its use. Import discovers how your project is set up, but it runs nothing on your machine, and it activates nothing that could change agent behavior until you ask it to.
Trust boundaries at a glance
Section titled “Trust boundaries at a glance”| Phase | Reads repository files | Executes repository commands | Makes data active |
|---|---|---|---|
hlix init |
yes | no | local binding only |
hlix import --dry-run |
yes | no | nothing |
hlix import |
yes | no, locally | cloud project, revision, encrypted protected data, declarative environment plan |
| Cloud task setup | the project snapshot and protected files | yes, inside the project’s Coding Workspace | the installed environment for that task |
skill/agent/mcp import |
selected resource | no local shell execution | the explicitly selected project resource |
Scanner containment
Section titled “Scanner containment”The local scan:
- resolves and stays inside the selected real directory;
- imports a symlink as a symlink, exactly as Git stores one — its path plus its raw target text. The target is never read, resolved, or uploaded, so a linked skill folder or instruction file contributes no bytes and a link pointing nowhere or back into the project is ordinary data.
pulland the Coding Workspace recreate the link. An ignore file is never read through a link either, which is Git’s own behaviour; - imports nested repository and submodule working files without their own Git metadata or history;
- considers tracked files even if a new ignore rule would hide them;
- applies
.gitignore,.hlixignore, and conservative built-in ignores to untracked files; - limits file count, individual size, total size, protected-file size, and protected total;
- parses environment sources without running their commands;
- hashes every included and protected file;
- binds local branch and tag names to their approved object IDs;
- rechecks snapshot files after the scan to detect concurrent changes.
Paths that traverse outside the project, absolute protected paths, duplicate manifest paths, malformed base64, size mismatches, and hash mismatches are refused both by the API and inside the sandbox.
Environment configuration
Section titled “Environment configuration”hlix prefers explicit environment sources—including Cursor environment JSON and Dev Container configuration—then fills gaps from language and package-manager evidence. The result is a declarative plan containing:
- runtime/toolchain versions;
- install and build commands;
- a start command and terminal processes;
- private ports;
- explicitly required secret key names and non-blocking source observations;
- source evidence, confidence, and warnings.
The scanner does not claim that an inferred command is safe or correct; it records evidence. Setup runs only inside the project’s Coding Workspace, never on hlix’s servers and never during the local scan.
Quarantine and activation
Section titled “Quarantine and activation”Agent instructions, skills, and MCP configuration are high-impact resources. Automatic project import encrypts and preserves their exact bytes but does not activate them.
Activation requires an explicit, resource-specific command:
hlix skill import …hlix agent import …hlix mcp import …
MCP adds two additional gates: remote endpoints require HTTPS, while stdio execution requires --allow-stdio and a direct executable without shell interpretation.
See Skills, agents & MCP for the exact review path.
Workspace and tenant isolation
Section titled “Workspace and tenant isolation”The saved project binding names both the API and the Workspace, and the CLI refuses to reuse it under a different selection. Import records, revisions, protected files, projects and access checks are all scoped to the authenticated Workspace.
A Workspace is your tenant. A Coding Workspace is one project’s execution environment. They are different boundaries: tenant access decides who can act; the Coding Workspace contains where untrusted project execution occurs. Tenancy & isolation covers where that first boundary is enforced.
Revision safety
Section titled “Revision safety”Each accepted import or push creates an immutable revision. The mutable project head advances only through compare-and-swap against the caller’s expected revision and generation.
This prevents:
- a stale local push from replacing newer cloud agent work;
- an interrupted retry from creating duplicate revisions;
- a failed upload from becoming the project head;
- a push from finalizing while tasks are actively mutating the same project.
hlix sync handles only uncontested one-sided change. Divergence is surfaced to a person instead of being auto-merged.
Remaining responsibilities
Section titled “Remaining responsibilities”hlix cannot determine whether every instruction, dependency, remote server, or credential is appropriate for your organization. You remain responsible for:
- authorization to upload source and history;
- license and customer-data obligations;
- rotating credentials already exposed elsewhere;
- reviewing setup commands and dependency lifecycle scripts;
- approving agent/skill/MCP behavior;
- choosing least-privileged provider credentials;
- validating application behavior after environment recreation.
Verify the boundary
Section titled “Verify the boundary”Before the first cloud task:
hlix import . --dry-run --json > /tmp/hlix-import-report.jsonhlix projects listhlix syncReview the report locally. Do not attach it to a public issue: it contains no secret values, but it does include project paths and secret key names.
Expected result: no scan blocker, the intended project appears in the intended workspace, and sync reports no change after import.
If the boundary check surprises you
Section titled “If the boundary check surprises you”- A file you expected in the snapshot is missing. It was recognised as protected or quarantined, and user ignore rules do not override that. The dry-run report names it and why it was set aside.
- A skill or agent the scan found is not influencing runs. That is the design: import preserves it inert. Activate it explicitly with
hlix skill importorhlix agent import. scan_blockedon a repository you consider clean. History findings and nested repositories do not block. Check the reported protected-file limits and environment values. Ordinary file limits degrade to a smaller snapshot. Never delete.gitfolders or files to get past this; use.hlixignoreinstead.- A setup command in the trust prompt you do not recognise. Do not approve it. It is shown verbatim because it will run inside the Coding Workspace with access to project secrets.
- A client collaborator can see less than you expected. That is a second, restrictive layer beneath the Workspace boundary, not a bug.