Import trust model

Seamless setup needs repository discovery; safe setup needs explicit boundaries. hlix treats repository content as untrusted input until a specific product action authorizes its use.

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	cloud snapshot and protected files	yes, inside the project Coding Workspace	dependency/setup environment for that task
`skill/agent/mcp import`	selected resource	no local shell execution	the explicitly selected project resource

Scanner containment

The local scan:

resolves and stays inside the selected real directory;
never follows symlinks;
refuses nested Git repositories;
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 at both API and sandbox boundaries.

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. Cloud setup executes only inside the durable project Coding Workspace, never in the backend service and never during the local scan.

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

The saved project binding names both API and workspace. The CLI refuses to reuse it under a different selection. The backend scopes import records, revisions, protected files, projects, and access checks to the authenticated workspace.

A workspace is the tenant/organization. A Coding Workspace is the durable per-project execution environment. They are different boundaries: tenant access decides who can act; the Coding Workspace contains where untrusted project execution occurs.

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

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

Before the first cloud task:

hlix import . --dry-run --json > /tmp/hlix-import-report.json
hlix projects list
hlix sync

Review the report locally; do not attach it blindly to a public issue because it includes project paths and secret key names, even though it contains no secret values.

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

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 its lane.
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 import or hlix agent import.
scan_blocked on a repository you consider clean. The blocker list names each finding. --history preserve uploads history despite findings; it does not remove them, and --yes never bypasses a blocker.
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.

Next steps

Secrets & protected filesThe full lifecycle of a protected file, from local scan to Coding Workspace.

Import skills, agents & MCPActivating what import deliberately left quarantined.

TypeScript SDKThe same guarded API behaviour, in automation.

API & OpenAPIThe canonical contract behind every guarded operation above.