usestrix/strix · error · ValueError

'{spec}' must land inside the workspace: use a relative dest

Error message

'{spec}' must land inside the workspace: use a relative destination or a path under /workspace

What it means

Raised by _workspace_file_dest() in strix/interface/utils.py when a --workspace-file spec's destination is an absolute path that does not start with /workspace/. The tool requires every injected file to land inside the sandbox's /workspace directory; absolute destinations elsewhere (e.g. /etc/passwd) are rejected to prevent writing outside the workspace.

Source

Thrown at strix/interface/utils.py:1698

        sys.exit(1)

    return path


# --- Workspace files -------------------------------------------------------
#
# ``--workspace-file`` places a single host file into the sandbox workspace,
# outside every target tree. Content rides the same upload as the target
# sources, so a large file makes session bring-up slower.


def _workspace_file_dest(spec: str, source: Path) -> str:
    """Return the workspace-relative destination declared by ``spec``."""
    _, sep, dest = spec.rpartition(":")
    candidate = dest.strip() if sep and dest.strip() else source.name
    if candidate.startswith("/") or Path(candidate).is_absolute():
        if not candidate.startswith("/workspace/"):
            raise ValueError(
                f"'{spec}' must land inside the workspace: use a relative "
                "destination or a path under /workspace"
            )
        candidate = candidate.removeprefix("/workspace/")
    candidate = candidate.strip("/")
    if not candidate:
        raise ValueError(f"'{spec}' has an empty destination path")
    if any(part in ("", ".", "..") for part in candidate.split("/")):
        raise ValueError(f"'{spec}' has an invalid destination path: {candidate}")
    # A control character would let the path span more than the one line it is
    # rendered on in the agent task, so the whole spec is rejected.
    if any(ord(char) < 0x20 or ord(char) == 0x7F for char in candidate):
        raise ValueError(f"'{spec}' has a control character in its destination path")
    return candidate


def resolve_workspace_files(specs: list[str] | None) -> list[dict[str, str]]:
    """Validate ``PATH[:DEST]`` specs into source/destination pairs.

View on GitHub (pinned to 8551339130)

Solutions

1. Use a relative destination: --workspace-file /host/secrets.txt:secrets.txt (file lands at /workspace/secrets.txt)
2. If you need an explicit absolute form, prefix it with /workspace/: --workspace-file /host/f.txt:/workspace/f.txt
3. Drop the destination entirely and let it default to the source file name: --workspace-file /host/f.txt

Example fix

# before
strix --workspace-file /etc/app/settings.ini:/etc/settings.ini -t ./
# after
strix --workspace-file /etc/app/settings.ini:settings.ini -t ./
# or explicitly: --workspace-file /etc/app/settings.ini:/workspace/settings.ini

def safe_workspace_spec(source: str, dest: str) -> str:
    from pathlib import PurePosixPath
    d = dest.strip()
    if d.startswith("/") and not d.startswith("/workspace/"):
        raise SystemExit(f"destination must be relative or under /workspace: {d}")
    d = d.removeprefix("/workspace/").strip("/")
    return f"{source}:{d}" if d else source

try:
    resolve_workspace_files([spec])
except ValueError as e:
    # user-facing message; re-prompt for a corrected spec
    print(e)

When it happens

Trigger: Calling strix with --workspace-file /host/secrets.txt:/etc/creds or any spec whose DEST part (after the last ':') is an absolute path not prefixed with /workspace/. Example: resolve_workspace_files(['/tmp/a.txt:/opt/a.txt']) raises ValueError.

Common situations: User copies a host absolute path into the DEST slot thinking it refers to the host, or tries to place the file next to the target tree (e.g. /app/config.yaml) instead of /workspace. Also triggered by Windows-style paths like C:\\conf\\a.yaml parsed as absolute.

Related errors

• '{spec}' has an empty destination path
• '{spec}' has an invalid destination path: {candidate}
• '{spec}' has a control character in its destination path
• '{source}' is not an existing file
• Cannot read '{source}': {error}

AI-assisted analysis of usestrix/strix@8551339130 (2026-08-15). Data as JSON: /api/errors/7ddc23a70043bd56. Report an issue: GitHub.