# 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 |
**Zero setup does not mean zero trust:** hlix can infer an environment and hydrate credentials without asking developers to retype configuration. The source repository still controls setup commands that may run later inside its isolated Coding Workspace. Review repository changes with that power in mind.

## 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](/cli/resources/) 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:

```bash
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 files](/security/secrets/)
  [Import skills, agents & MCP](/cli/resources/)
  [TypeScript SDK](/sdk/typescript/)
  [API & OpenAPI](/api/openapi/)