Skip to content

One command to real protection: run the agent in a container, the signer outside #591

Open

Description

@LoopGlitch26

Today, a stranger's first hour with Tracekit ends at Assurance: dev, isolation: same-user. The README says plainly that this "protects nothing against an agent that runs as you". The protected setups each take days:

  • system mode needs root and a second, non-admin OS user for the agent, and it's experimental on macOS;
  • Compose builds images from source;
  • Kubernetes needs an image build and Helm.

On a Mac the person is usually an admin, so the agent running as them can't be separated from a signer by users alone.

Goal: one command that ends with a real separation between the agent and the signer, on macOS and Linux, shown by tracekit doctor and in every bundle as something other than same-user.

Design to evaluate first: the agent in a container, the signer outside.

  • tracekit up --isolated starts or reuses the signer on the host.
  • It then runs the coding agent (Claude Code first) in a container. The container gets the project mounted, and no access to the signer's data, keys or the Docker socket.
  • The agent's hooks reach the host signer over a forwarded socket or loopback TCP with a per-run token. The signer records the isolation it can establish itself, never what the container says.
  • This is also the safe way to let a coding agent run unattended: it acts inside the box, and the record and the holds stay outside.

Alternatives to compare:

  • a one-command system mode with a dedicated signer user (and how admin rights on a Mac undercut it);
  • a published signer image for servers.

Done when:

  • A design note picks one path, with its honest limits. For example: a person who gives the container the Docker socket, or runs the agent outside it, loses the separation.
  • A working prototype runs on a Mac with colima.
  • Tests cover the new command.
  • The limits rows are updated.

Activity

  1. khushi-git-7 commented on Nov 13, 2026

    @khushi-git-7
    Contributor

    I'd like to take this one, design first as the issue asks.

    1. Design note comparing the three paths: the agent in a container with the signer on the host; a one-command system mode with a dedicated signer user (and what admin rights on a Mac do to it); and a published signer image. For the container path, it would cover:
      • how the hooks reach the host signer: a forwarded Unix socket, or loopback TCP with a per-run token;
      • what the signer can establish about the isolation itself. Since it starts the container, it knows the mounts and that the Docker socket isn't one of them, rather than taking the container's word;
      • the honest limits: handing the container the Docker socket, or running the agent outside it, loses the separation.
    2. Prototype: tracekit up --isolated with Claude Code first, tests for the new command, and the limits rows.

    One thing up front: I'm on Windows and Linux, not a Mac. I can run the prototype on Linux (Docker) and on GitHub's macOS runners, but colima on the arm64 runners has no nested virtualization, so the Mac/colima check may need a Mac. I'll say exactly what was and wasn't run.

    I'll post the design note here before writing the command, so you can pick the path.

  2. LoopGlitch26 commented on Nov 13, 2026

    @LoopGlitch26
    MemberAuthor

    It's yours, design note first as the issue asks. Post the note here before writing code; I'll answer it.

  3. LoopGlitch26 commented on Nov 13, 2026

    @LoopGlitch26
    MemberAuthor

    One more thing before the design note: #601 is an earlier attempt of ours at this (tracekit up --isolated, the agent in a container and its signer outside), open since 11-04. Read it and its thread first; the note can say what to keep from it, what to change, and whether to continue on that branch or start fresh.

  4. khushi-git-7 commented on Nov 13, 2026

    @khushi-git-7
    Contributor

    I've read #601 and its design note (docs/design/isolated-up.md at 5cceb58). My proposal is to continue it rather than start fresh: the path, the threat list and the review fixes are right, and most of the remaining work is what its own limits list says, "Linux is written but not yet run."

    Keep, as it is

    • Path (a): the agent in a container, a signer of its own outside it (<dev data dir>-box), and the dev signer untouched.
    • Hooks the box can't redirect:
      • Tracekit's hooks in Claude Code's managed settings, with TRACEKIT_SIGNER* pinned;
      • a root-owned /etc/tracekit/client.json;
      • the box's own tailer.
    • What the host runs stays read-only: .git, .claude, the hook frameworks' configs, the coding agents' project configs, .mcp.json, .vscode and .idea. A symlink among them stops up, and the files changed at exit are listed.
    • The internal network and its relay as the only way out, with --network opt-in.
    • Token handling: revoked on SIGTERM and SIGHUP, and on the next up after a kill; D-BOX-TOKENS and D-BOX-MOUNTS.
    • The label: unknown plus a signed, non-critical ext.box, with the verifiers' "proof against the boxed agent, not against a process of the signer's own user". That's the honest claim for a token, and I wouldn't add a container label (I'd suggested one before reading tracekit up --isolated: the agent in a container, its signer outside it (prototype, #591) #601).

    Change or add

    1. Rebase onto main. Main is 184 commits ahead of tracekit up --isolated: the agent in a container, its signer outside it (prototype, #591) #601's base, and it now has its own box channel (test_box_channel.py, findings_box.py, and signer_isolation: "unknown" with the daemon's identity in ext.box for boxed runs in register_run). That's Tracekit Box's agent channel from Signer: per-box identity and a signer-written box label for Tracekit Box (#602) #603, with its signer-written box label. So the rebase has to reconcile tracekit up --isolated: the agent in a container, its signer outside it (prototype, #591) #601's token box with Signer: per-box identity and a signer-written box label for Tracekit Box (#602) #603's: one ext.box, not two meanings of it. I'd read Signer: per-box identity and a signer-written box label for Tracekit Box (#602) #603 first and propose how the two schemas fit here before changing code.
    2. Run Linux for real. I'd run the live tests (BoxInDocker) and box_probe.py on ubuntu-latest (Docker Engine, cgroup v2), plus the relay-only network and the "token taken only from the relay's address" check, and fix whatever fails. GitHub's runners make this a CI job, not just a manual step. A Mac re-run after the rebase would still need you or someone with colima, since GitHub's arm64 macOS runners can't run it.
    3. A stronger label on Linux (optional, your call). On Docker Engine, a Unix socket bind-mounted read-only reaches a host signer without a token. If the box runs as a uid of its own, the signer reads that uid from SO_PEERCRED, and _isolation already labels it separate-user: established by the kernel, with nothing that a process of your user could copy. The cost is file ownership in the project: the box's uid isn't yours, so it needs a shared group, --userns or ACLs. I'd keep tracekit up --isolated: the agent in a container, its signer outside it (prototype, #591) #601's token path as the default and offer this as a follow-up flag, with numbers, only if you want it.
    4. Agents beyond Claude Code. Not in this PR. The box image takes --agent claude only. With Kiro (Coding agents: hooks for Kiro CLI #798) and the other harnesses' hook files, a later --agent could write their hooks into the image the same way.

    How to continue

    I can't push to agent/issue-591, so I'd rebase #601's six commits onto main on my fork, keeping your authorship, add mine on top, and open the PR from there. You'd close #601 once it supersedes it. If you'd rather keep the PR, I can send you the rebased branch instead.

    Questions for you:

  5. LoopGlitch26 commented on Nov 14, 2026

    @LoopGlitch26
    MemberAuthor

    Thanks, this is a careful read of #601, and continuing it rather than starting over makes sense. Please hold off on rebasing it for now: #601 is still in progress on our side, and your (b), how its token box and #603's box channel share ext.box, is a format question we need to settle first. I'll answer (a) to (c) here once that's decided. Until then, #698 and #825 are the better use of your time.

  6. khushi-git-7 commented on Nov 14, 2026

    @khushi-git-7
    Contributor

    Understood, I'll hold off until (b) is settled, and work on #698 and #825 meanwhile.

    In case it helps when you decide: I'd already rebased #601's commits onto main on my fork (agent/issue-591, not opened as a PR). There, BoxInDocker, box_probe.py and the relay-only network check pass on ubuntu-latest. I'll leave that branch as it is until you've answered.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions