bot-bottle/docs/research/remote-docker-vm-isolation.md

# Remote Docker VM as an isolation upgrade for claude-bottle

Note on the cheapest practical path to stronger isolation than local
Docker: run claude-bottle unchanged on a remote Linux VM that has
dockerd. Complements `stronger-isolation-alternatives.md` (which
surveys runtime swaps like gVisor, Kata, Firecracker, Apple Container)
and `local-vs-remote-agent-execution.md` (which surveys the
local-vs-remote decision broadly).

## Summary

If the goal is "stronger isolation than Docker-on-my-laptop without
rewriting the runtime," the cleanest answer is to keep claude-bottle
exactly as it is and run it on a remote Linux VM where you can install
dockerd. The v1 design — pipelock as a separate container on a
`--internal` network, ephemeral agent containers, OAuth-token
forwarding — works as-is. The only thing that changes is that the
"host" is now a disposable VM you provisioned for the session, not your
laptop.

This is structurally equivalent to a Firecracker rewrite (Rung 3 in
`stronger-isolation-alternatives.md`), but the cloud provider operates
the runtime for you. It is also strictly cheaper than adopting a cloud
sandbox SDK (Vercel Sandbox, E2B, Cloudflare Sandbox SDK) because you
keep the existing Docker-shaped abstractions instead of swapping them
for a vendor API.

## The argument

### What changes in the threat model

The agent's blast radius shrinks from "developer laptop + everything
on the LAN" to "this disposable VM." Concretely, what's no longer
reachable on container escape:

- `~/.ssh/`, `~/.aws/credentials`, `~/.config/gh`, the macOS Keychain
- Browser cookies and session state
- Other dev machines on the home/office LAN
- NAS, printers, smart-home devices, anything else on the local network

What replaces it on the remote side: only what the operator chose to
ship to the VM for the session. Typically the OAuth token, optional SSH
keys for the bottle, the manifest, and the workspace if the agent needs
one. None of which are on the laptop after the VM is destroyed.

### Why the boundary is equivalent to v1, not weaker

A natural objection — raised in the design discussion that produced
this note — is that running pipelock and the agent on the same VM
collapses a network boundary into a kernel-namespace boundary, which
sounds weaker. It is not, *if you reuse Docker for the inner topology.*

Docker on the remote VM gives the agent and pipelock their own network
namespaces by default, with the agent attached to a `--internal`
network and pipelock straddling it and an egress bridge. That is the
same v1 topology. Bypassing pipelock from the agent requires the same
class of attack as bypassing it on a laptop: a kernel-level netns
escape inside the VM. The only difference is that the kernel under
attack belongs to a disposable VM, not the developer's machine.

In other words: the "weaker because colocated" framing only applies if
you naively run agent and pipelock as two processes in the same
namespace. With Docker on the VM, you don't.

### Why this is cheaper than the alternatives

| Path | Effort | Where the VM-grade boundary comes from |
| --- | --- | --- |
| gVisor (`runsc`) per bottle | ~1–2 days | Userspace syscall barrier; not a full VM |
| Kata Containers per bottle | ~1–2 days, Linux-only | Kata's microVM-per-container |
| Firecracker rewrite | 2–4 weeks | Self-operated Firecracker |
| Apple Container (macOS) | ~1 week spike + integration | Apple's Virtualization.framework, per-container |
| Cloud sandbox SDK (Vercel, E2B, …) | Days–weeks of API rewrite + lock-in | Provider-operated Firecracker / equivalent |
| **Remote Docker VM (this note)** | **0 lines of code** | **Cloud-provider hypervisor under the VM** |

The "stronger isolation alternatives" doc concludes that gVisor is the
right today-step and Apple Container is probably the right v2.
This note adds a third option that sits orthogonal to both: don't
change the runtime, change the host. Use it when the failure mode you
care about is "agent compromises my laptop" specifically, rather than
"agent escapes Docker into a kernel I share with other workloads."

## What the provider has to give you

Not every cloud sandbox is suitable. The minimum for this approach to
work:

- Root or rootless-Docker capability inside the VM. Rules out
  Fargate-style locked-down container hosts and most "function" tier
  FaaS. Verify before committing — Vercel Sandbox specifically may or
  may not allow installing dockerd depending on tier; Fly Machines,
  EC2, GCE, Hetzner, Linode, and self-hosted hypervisors give you full
  control.
- Enough disk + RAM to host the claude-bottle image, the agent
  container, and the pipelock sidecar. Headroom of ~2–4 GB RAM and
  ~5 GB disk is comfortable; less works for short sessions.
- An interactive reach path. SSH is fine. The launcher uses
  `docker exec -it`, so any TTY-capable session works.

## What you give up

- **Typing latency.** Interactive Claude sessions over SSH have visible
  per-keystroke latency; usually fine on wired/fiber, less fine on
  Wi-Fi-to-cloud. Mosh helps if it's bothersome.
- **Token shipping.** `CLAUDE_BOTTLE_OAUTH_TOKEN` has to live on the
  remote box for the launcher to forward it into containers. Use the
  provider's secret-injection path (cloud-init user-data,
  `flyctl secrets`, Tailscale-served local file, etc.). Never echo the
  token onto the SSH command line; it ends up in the local shell
  history and possibly the SSH server's auth log.
- **Idle cost.** Unless the VM is torn down between sessions, you pay
  for it sitting idle. Ephemeral provisioning (one VM per session,
  destroyed on exit) is the cheaper and more secure pattern; see
  `local-vs-remote-agent-execution.md` on why ephemeral is also
  recommended for credential-concentration reasons.
- **Source code goes to the VM.** Same as any remote-execution
  topology. If the project is under NDA, the VM provider matters.
- **Provider trust.** Multi-tenancy side channels, supply-chain
  compromise of the provider, insider risk. Generally smaller than
  laptop-kernel-CVE risk, but the failure mode (provider-wide breach)
  is correlated across all your sandboxes.

## Operational shape

The minimum-viable workflow, no claude-bottle code changes:

1. `terraform apply` / `flyctl machine run` / `gcloud compute
   instances create` — provision a fresh Linux VM.
2. Install dockerd via the provider's image or a one-liner
   (`curl -fsSL https://get.docker.com | sh`).
3. SSH in.
4. `git clone` claude-bottle on the VM, drop a manifest in place,
   inject `CLAUDE_BOTTLE_OAUTH_TOKEN` via the provider's secrets path.
5. `./cli.py start <agent>` — the existing launcher handles the rest.
6. On exit: destroy the VM. No host artifacts persist.

For the "VPN pivot" failure mode, see
`local-vs-remote-agent-execution.md`. Short version: never VPN the
remote VM back to your LAN. If the agent needs LAN resources, expose
those through a narrow API instead.

## Optional ergonomics direction

A future addon — not architecturally necessary, just nicer:

- `cli.py start --remote=user@host <agent>` that:
  - rsyncs the manifest and (optionally) cwd to the remote
  - SSHes in with the OAuth token forwarded via `SendEnv`
  - runs `cli.py start <agent>` on the remote
  - forwards the TTY for the interactive session
  - on exit, optionally tears down the remote VM via a provider hook
    (`flyctl machine destroy`, `terraform destroy`, etc.)

This is roughly a day of work and would make the remote pattern feel
like a single launcher invocation. It is the only piece of remote
support that would benefit from being upstreamed; everything else is
operator workflow.

## Recommendation

For users who want stronger isolation than local Docker without
rewriting the runtime, this is probably the right answer. Cleaner than
gVisor (which only adds a syscall barrier on the same kernel), cleaner
than a Firecracker rewrite (which is weeks of work), cleaner than
adopting a cloud-sandbox SDK (which trades the v1 design for a vendor
API). The pre-existing `local-vs-remote-agent-execution.md` decision
heuristics still apply for *whether* this is worth the operational
overhead in any given setting.

If we wanted to land this as a real project direction:

1. Add a short "Running claude-bottle on a remote Docker VM" section
   to the README pointing at this doc.
2. Optionally: prototype the `--remote=user@host` launcher subcommand.
3. Update `stronger-isolation-alternatives.md` to mention the remote
   Docker VM as a fourth path, since the survey is otherwise
   incomplete.

## Caveats

- "Just install Docker" isn't free on every provider; some lock down
  what kernel modules and caps the VM has. Spike-test before committing.
- Multi-tenant cloud hypervisors (EC2, GCE, Vercel) have their own
  side-channel and supply-chain risk surfaces, separately bounded from
  the laptop-kernel risk this approach addresses.
- The remote-VM topology still does not protect source code or secrets
  from the cloud provider — it protects them from a kernel exploit
  reaching the developer's laptop. Different fear, different fix.
- Research conducted 2026-05-10.