feat(cloudify): Add instant remote coding-agent cloud sessions with workspace/PTY handoff

[matdev83]

Assessment: 9.8/10

Expected SWE-user value: exceptional
Strategic/product value: exceptional — makes AIProxer an optional compute/runtime provider in addition to an LLM control plane
Proxy/product fit: very high because AIProxer already owns agent integration, model routing, session identity, auth, accounting and streaming concerns
Implementation complexity: high; this is a new remote-execution plane and should become its own milestone/workstream

Proposed milestone

AIProxer Cloud / Remote Agent Execution

The GitHub connector used to create this FR cannot create milestone objects, so this issue is intentionally left without an unrelated existing milestone. Once the milestone is created, this issue should be its anchor/tracker and the implementation should be split into smaller chronological child issues/specs.

---

Summary

Add an optional AIProxer Cloud / cloudify execution mode that lets a developer move coding-agent execution from their local machine onto an AIProxer-owned/leased bare-metal Linux worker with almost no workflow change.

Primary desired UX:

cd ~/src/my-project

aiproxer cloudify codex

Instead of starting Codex locally, cloudify should:

1. inspect and capture the exact current workspace state;
2. select a nearby/capable AIProxer worker;
3. create/fork an ultra-fast isolated remote execution environment;
4. reconstruct the current repository/branch/dirty working tree there;
5. start the requested coding agent in the remote environment;
6. attach the user's existing local terminal to the remote agent PTY;
7. route the agent's model traffic through AIProxer using an ephemeral scoped session identity;
8. preserve/reconcile resulting workspace changes according to the selected synchronization mode;
9. destroy, sleep or retain the remote environment according to explicit lifecycle policy.

The user should feel that they launched their normal coding agent locally, while CPU/RAM/build/test/tool execution happens on AIProxer infrastructure.

Example target UX:

$ aiproxer cloudify codex

AIProxer Cloud
region: fra
workspace: main@8b37f01 + 3 local changes
runtime: codex / go

> ...normal Codex TUI starts here...

This is not a browser IDE and should not require the developer to learn a separate remote-workspace product.

---

Product motivation

Coding agents increasingly perform expensive local work:

• large builds/tests;
• package installation;
• repository indexing/search;
• multiple sub-agents;
• parallel implementation/review attempts;
• long-running autonomous tasks;
• workloads that exceed laptop RAM/CPU;
• workloads users want to detach from and resume later.

The highest-value UX is not "rent a VM, SSH into it, clone the repo, install Codex, copy credentials, configure AIProxer, then work." It is:

aiproxer cloudify codex

AIProxer can eliminate almost all setup because it already understands the agent, LLM routing/auth, user/session identity and future client-integration surfaces.

This also creates a credible commercial product surface around AIProxer-owned/leased compute without making the user abandon their preferred coding harness.

---

Two user-entry flows

Flow A — launch the agent remotely from the start

This is the primary V1 and is highly feasible:

aiproxer cloudify codex [codex args...]

Possible later examples:

aiproxer cloudify claude
aiproxer cloudify opencode
aiproxer cloudify pi

Conceptually:

local terminal
     |
     v
AIProxer CLI
     |
     +-- workspace manifest/delta ------------------+
     |                                               |
     +-- create cloud session -----------------------+----> AIProxer Cloud control plane
                                                     |             |
                                                     |             v
                                                     |      bare-metal worker
                                                     |             |
                                                     |        warm sandbox fork
                                                     |             |
                                                     |             v
                                                     |          microVM
                                                     |             |
local terminal <---- encrypted PTY stream -----------+-------- coding agent
                                                                   |
                                                                   v
                                                              AIProxer LLM
                                                                 gateway

The local terminal remains the UI. Rendering of ANSI/TUI output remains local.

Flow B — request cloud handoff from inside an already-running agent

Desired convenience UX:

# inside Codex / another harness with shell escape
> !aiproxer cloudify

There is an important OS/process-model limitation:

terminal
  -> local Codex
       -> shell tool
            -> aiproxer cloudify

The aiproxer command is a child of the already-running agent. It cannot generically migrate its parent process memory/TUI state to another machine or replace the parent's process image remotely.

Therefore literal live process migration is a non-goal.

The feasible implementation is workspace + resumable agent-session handoff:

local agent
   -> !aiproxer cloudify
        -> provision remote sandbox
        -> replicate exact workspace
        -> export/import supported agent session state
        -> start remote agent with resume semantics
        -> return/activate handoff

For an unmanaged agent the initial UX may be:

Cloud session ready: cld_83ef...
Exit this local agent and run:
    aiproxer attach cld_83ef

Much better path when AIProxer launched the local agent

If #392 / the launcher work starts the agent through an AIProxer supervisor, e.g.:

aiproxer wrap codex

then AIProxer can own the outer PTY/process lifecycle:

terminal
   -> AIProxer supervisor
        -> local Codex

An in-agent !aiproxer cloudify can signal that supervisor through local IPC. The supervisor can:

1. freeze/coordinate a handoff point;
2. provision the remote successor;
3. export supported resumable agent state;
4. start codex resume ... / equivalent remotely;
5. switch the PTY backend from the local process to the remote stream;
6. terminate the local successor only after the remote session is confirmed ready.

That is still restart/resume, not process-memory migration, but to the user it can approach an in-place transition.

This is a strong reason for wrap and cloudify to share one generic agent launcher/supervisor adapter rather than becoming unrelated implementations.

---

Architectural principle

Treat this as remote agent-session handoff, not generic "Docker in the cloud".

AIProxer Cloud should own:

session admission / auth
worker scheduling
workspace synchronization
sandbox lifecycle
PTY transport
agent launch/resume adapters
short-lived model credentials
network/egress policy
compute accounting
attach/detach/reconnect
lifecycle/cleanup

The existing LLM proxy remains the authority for:

model routing
provider credentials
LLM usage/accounting
budgets/policy
compatibility transforms
session-facing proxy features

Do not put remote execution concerns into the inference hot path.

---

Execution substrate: recommend Firecracker-class microVM isolation

Earlier local-sandbox research identified very lightweight namespace-based projects such as Bubblewrap/ai-jail/devsandbox. Those are attractive for single-user local isolation because startup is nearly process-class latency.

For AIProxer-operated infrastructure, however, the threat model changes materially.

A customer coding agent may execute arbitrary repository/native code:

npm install <malicious-package>
make
./unknown-binary
python repo-script.py

AIProxer should assume the guest may eventually execute hostile code.

For a paid multi-tenant compute service, ordinary shared-kernel namespaces should not be the primary tenant security boundary.

Preferred direction

Use a Firecracker-class microVM boundary on bare-metal Linux/KVM hosts while keeping container-like UX and startup behavior.

Candidate architecture:

immutable prepared rootfs / profile
            |
        warm snapshot
            |
     reflink/COW clone
            |
     Firecracker + jailer
            |
          netns
            |
        guest kernel
            |
     AIProxer guest agent
            |
          PTY
            |
        Codex/etc.

Requirements:

• bare-metal Linux workers with KVM;
• no Docker daemon dependency;
• no Kubernetes dependency for sandbox creation/scheduling;
• no public-cloud runtime dependency;
• one guest-kernel boundary per untrusted customer execution environment;
• jailer/namespace/cgroup/uid isolation around the VMM as an additional layer;
• default-deny or tightly controlled network posture;
• no arbitrary host filesystem bind mounts into mutually untrusted tenants.

Strong research/reference candidate: Crucible

Reference:

• https://github.com/gnana997/crucible

Crucible is unusually close to the lower half of this proposed system:

• Go implementation;
• Firecracker + jailer;
• self-hosted single-binary daemon/client model;
• coding-agent/untrusted-code focus;
• snapshot/fork as first-class primitives;
• vsock guest command channel with streamed output;
• per-sandbox network namespaces and egress controls;
• OCI-image/rootfs support without requiring Docker as the runtime;
• cross-platform thin client driving a remote Linux host.

Its README currently reports, on reflink-capable storage, approximately:

warm fork p50             ~125 ms
64-way fork throughput    ~41/s
exec roundtrip            ~3 ms
snapshot wake             ~125 ms

These are project-reported measurements and must be independently benchmarked on AIProxer target hardware before becoming product SLOs.

Crucible also explicitly warns that it is pre-1.0 and not yet hardened for production untrusted multi-tenant use. Therefore:

• do not blindly ship it as the production security boundary today;
• evaluate it as a prototype dependency and architecture/code reference;
• compare direct Firecracker integration vs adopting/hardening/contributing upstream;
• perform an explicit security review before production use.

Other useful references:

• Firecracker: https://github.com/firecracker-microvm/firecracker
• libkrun: https://github.com/containers/libkrun
• Bubblewrap (useful local primitive, not preferred cloud tenant boundary): https://github.com/containers/bubblewrap

---

Warm snapshots, not cold provisioning

The feature will fail its UX goal if every cloudify invocation does this:

allocate machine
-> boot Linux
-> apt install packages
-> install coding agent
-> git clone
-> install toolchains
-> start agent

Instead maintain prepared profiles/snapshots, for example:

generic
codex-generic
codex-go
codex-node
codex-python
codex-rust
claude-generic
...

Profile preparation:

minimal Linux
  -> standard tools
  -> selected toolchain(s)
  -> coding agent binary/runtime
  -> AIProxer guest agent
  -> boot to ready state
  -> quiesce
  -> snapshot

Session creation becomes:

warm snapshot
  -> lazy/COW restore
  -> reflink rootfs clone
  -> fresh VM/machine identity
  -> fresh netns/resource limits
  -> materialize workspace delta
  -> inject short-lived session capability
  -> exec agent under PTY

Worker filesystem recommendation

Benchmark and strongly prefer XFS or btrfs with reflink support for the sandbox/rootfs work area.

Crucible's measurements show a very large difference between reflink-capable storage and ext4 because ext4 requires byte-copying rootfs data for the tested fork path. The SDD should explicitly benchmark filesystem choice rather than treating it as an incidental deployment detail.

---

Exact workspace reconstruction

cloudify must reproduce the developer's actual current working tree, not merely git clone <branch>.

A real local state may contain:

origin/main:     A---B---C
                         \
local commits:            D---E
                               \
dirty tracked files:             *
untracked nonignored files:      +

The remote environment must reproduce E + current dirty state.

Suggested git-aware transfer model

Create a canonical bounded workspace manifest containing approximately:

repository identity/remotes
base/reference commit
HEAD commit/tree
branch/detached state
submodule metadata where supported
file mode/symlink metadata
working-tree fingerprints

Then transfer only what the worker does not already have:

cached bare repo / object store on worker
       +
missing Git objects / pack/bundle
       +
dirty tracked-file deltas
       +
untracked non-ignored files

Use streaming compression (e.g. zstd) and content hashes.

Do not upload the entire repo for every invocation.

After first use, a cached repository plus small working-tree deltas should make repeat cloudification very cheap.

Security/privacy defaults

• .gitignore-ignored files should not be uploaded by default;
• do not recursively sync the user's home directory;
• do not copy local environment variables/secrets by default;
• explicit secret/file mappings require a separate opt-in policy;
• bounded file count/bytes/path depth;
• traversal/symlink safety;
• preserve executable bits and supported symlinks correctly;
• detect case-sensitivity/path incompatibility rather than silently corrupting a workspace;
• support private repo/object fetch only through explicit scoped auth.

Git LFS/submodules

Define explicit behavior rather than silently producing incomplete trees:

• submodule recursion on/off + auth policy;
• Git LFS object acquisition using scoped credentials where configured;
• missing external object failure should be actionable.

---

Workspace changes during/after the cloud session

This is a key product requirement: after Codex edits code remotely, the developer must get those edits back safely.

V1: snapshot + conflict-safe sync-back

Simplest robust V1:

1. initial local workspace becomes the session base;
2. remote agent is the expected writer during the cloud session;
3. on exit/detach/explicit sync, compute a Git-aware changed-file delta from the initial base;
4. apply it locally only if the corresponding local file still matches its expected base revision;
5. if local edits raced with remote edits, never overwrite silently — surface a conflict/handoff state.

This supports a terminal-centric workflow without immediately building a full remote-development filesystem.

Later: live mirror mode

For stronger local-IDE continuity, add a bidirectional or remote-to-local workspace mirror protocol:

remote tracked/nonignored source changes
       -> change journal/hash
       -> local CLI
       -> conflict-safe apply
       -> local editor sees file change

and optionally local edits back to the remote session.

Do not sync generated node_modules, build trees, caches or other ignored artifacts by default merely because they changed remotely.

A sync journal should give each path/version a clear expected predecessor so concurrent local/remote edits cannot silently last-write-win.

This is valuable but should follow the basic snapshot/sync-back vertical slice if necessary to keep V1 manageable.

---

PTY / terminal transport

The user's current terminal should remain the UI.

Architecture:

local terminal emulator
      |
      | stdin / stdout / resize / signals
      v
AIProxer CLI/supervisor
      |
      | authenticated encrypted persistent stream
      v
session gateway
      |
      v
worker runtime
      |
      v
vsock / guest channel
      |
      v
guest PTY
      |
      v
Codex / Claude / OpenCode

Required semantics:

• raw-mode TTY;
• stdin/stdout/stderr or PTY combined stream as appropriate;
• terminal-size changes (SIGWINCH equivalent);
• Ctrl-C / Ctrl-D / signal handling;
• alternate-screen/TUI behavior;
• UTF-8 and binary-safe framing;
• backpressure;
• keepalive;
• clean exit status;
• attach/detach;
• reconnect after transient local network loss;
• bounded output buffering/replay for reconnect;
• explicit idle/lease semantics.

Do not multiplex raw PTY bytes into the existing LLM inference event protocol. The lifecycle/reliability/backpressure semantics are different.

The implementation can initially reuse proven SSH-style PTY semantics or a compact dedicated protocol; do not invent complexity merely for novelty.

---

Agent integration adapters

Do not hard-code all harness logic into the cloud scheduler.

Create a small agent adapter/supervisor contract conceptually responsible for:

Detect/Resolve executable and version
BuildLaunchSpec(args, env, workspace)
BuildProxyIntegrationSpec()
ExportResumeState()           # optional capability
ImportResumeState()           # optional capability
BuildResumeSpec()             # optional capability
Health/ready detection

Capability examples:

codex       launch=yes   resume=strong
claude      launch=yes   resume=adapter-specific
opencode    launch=yes   resume=TBD
pi          launch=yes   resume=TBD
unknown     launch=generic command   resume=no

Reuse #392's agent launch/wrapping knowledge and #453/#466's first-class Codex/Claude integration work rather than maintaining separate config/endpoint-injection code in cloudify.

Codex should be the first vertical slice

Reasons:

• important SWE user base;
• existing AIProxer integration work;
• process-scoped provider/base-URL integration is tractable;
• Codex exposes explicit resume/session concepts that can support later handoff.

---

LLM authentication and routing inside the guest

The guest should normally not receive the user's/provider's raw OpenAI/Anthropic API keys.

Preferred flow:

Codex in guest
     |
     | short-lived AIProxer cloud-session credential
     v
AIProxer gateway
     |
     +-- routing
     +-- policy/budget
     +-- audit/observability
     +-- provider credential ownership
     +-- backend failover
     v
provider

Cloud-session token should be scoped approximately to:

tenant/principal
cloud session id
allowed route/model policy
expiry
compute/LLM budget refs
possibly agent/workspace identity

It should expire/revoke when the cloud session ends.

Do not make a durable general-purpose user API key the guest's permanent credential if a narrower ephemeral capability can work.

---

Other secrets and developer credentials

Remote coding needs more than model access, but secret synchronization must be explicit.

V1 principles:

• no wholesale environment copy;
• no copying ~/.ssh, ~/.aws, browser tokens, GitHub tokens, etc.;
• support explicitly selected secret references/mappings later;
• prefer short-lived delegated Git/SCM credentials;
• provider model credentials remain in AIProxer, not guest;
• secrets should be mounted/injected only for the session and removed on teardown;
• never include secret values in workspace manifests, diagnostics, PTY metadata or ordinary logs.

#483 external secret-manager work can later provide a strong authority for server-side secret references, but should not be a hard blocker for a minimal Codex-only prototype that does not need arbitrary user secrets.

---

Network / egress model

Remote coding agents need network access for package managers, Git, docs and tools, so a permanent blanket no-network sandbox is not useful.

However AIProxer should not expose unrestricted host/VPC reachability.

Recommended model:

• per-session network namespace;
• no reachability to host management plane;
• block metadata/link-local/private infrastructure by default;
• DNS and egress policy controlled at host/gateway boundary;
• LLM-provider traffic forced/redirected through the intended AIProxer integration rather than leaking provider credentials directly;
• optional public Internet egress policy/profile;
• optional hostname/CIDR allowlists for enterprise posture;
• bounded connection/rate limits;
• explicit handling for package registries/Git hosts;
• no tenant-to-tenant direct network path.

Do not trust guest DNS resolution alone as an SSRF boundary.

---

Bare-metal worker and scheduler architecture

This workstream should not require Docker or Kubernetes on execution workers.

A worker can be a dedicated/leased Linux host with:

KVM
Firecracker runtime
reflink-capable work filesystem
AIProxer worker daemon
local prepared snapshot/profile cache
local Git object/workspace cache
network namespace/nftables authority
resource accounting

The control plane schedules based on bounded immutable/periodic capacity evidence:

region/zone
host health
authorized tenant pools
available CPU/RAM/disk
profile/snapshot cache hits
repo/object cache locality
worker version/security generation

Do not turn scheduling into a database/network lookup in AIProxer's inference request hot path. Cloud-session creation is its own control-plane operation.

#514 Enterprise HA/fleet coordination contains useful generic fleet ideas, but Cloud compute workers are a distinct workload pool and this feature must not inherit #514's Kubernetes-first discovery suggestion as a runtime requirement. Bare-metal worker registration/heartbeat plus a simple scheduler is sufficient for this milestone's first target.

---

Resource controls

Every session must have hard limits independent of agent behavior:

vCPU
RAM
rootfs/workspace bytes
open files/PIDs
disk IOPS/throughput where practical
network bandwidth/connections
max session duration
idle timeout
PTY buffer/replay bytes
workspace sync bytes

Resource classes may later become product SKUs, e.g.:

small     2 vCPU / 4 GiB
medium    8 vCPU / 16 GiB
large    16 vCPU / 32 GiB

The guest cannot self-upgrade its limits.

---

Session lifecycle

Define an explicit state machine rather than a collection of ad-hoc worker RPCs:

requested
-> admitted
-> worker_assigned
-> workspace_materializing
-> sandbox_starting
-> agent_starting
-> ready/attached
-> detached
-> stopping
-> syncing_back
-> terminal

Failure states should preserve a stable reason category.

Useful commands eventually:

aiproxer cloudify codex
aiproxer cloud list
aiproxer cloud attach <session>
aiproxer cloud detach <session>
aiproxer cloud stop <session>
aiproxer cloud sync <session>
aiproxer cloud status <session>

The CLI remains a client. The server/control plane owns authoritative session state.

Detach/reconnect

A local network interruption should not kill a productive remote Codex process immediately.

Support:

• bounded reconnect lease;
• attach token scoped to the principal/session;
• output replay from a bounded ring/journal;
• explicit terminal cleanup after expiry;
• one authoritative writer attachment unless multi-attach is deliberately designed later.

---

Atomic handoff semantics for Flow B

A migration/handoff must not create two agents concurrently mutating diverged workspaces accidentally.

Safe sequence:

1. request cloud handoff
2. local agent reaches controlled/blocking point
3. capture exact workspace + resumable state
4. provision/start remote successor
5. prove remote agent is ready
6. switch/offer attach
7. only then retire local agent

If remote provisioning fails before step 5, the local session remains authoritative.

If the user changes local files after the captured handoff revision, sync/conflict rules must detect the divergence.

Never terminate the local process first and hope remote resume succeeds later.

---

Compute accounting and commercial model

LLM usage accounting and cloud compute accounting are related but different evidence planes.

A cloud session should produce authoritative bounded compute evidence such as:

session id
principal/project
worker/region class
resource class
started/stopped/active duration
vCPU reservation/usage class
RAM reservation class
persistent/ephemeral storage bytes-time
network egress if billed
snapshot/cache class where relevant
terminal outcome

Do not pretend model-token accounting represents compute cost.

AIProxer can later price:

compute duration/resource class
+
storage/network
+
ordinary LLM usage

Admission should be able to enforce compute quota/budget before creating a session.

This has strong Enterprise/hosted-product synergy with existing user/project/budget/accounting work, but cloud compute should have a dedicated typed ledger/evidence model rather than being squeezed into provider COGS records.

---

Observability

Instrument the remote-session critical path with bounded phases:

admission latency
scheduler latency
workspace manifest time
workspace bytes sent/cache hit
rootfs/snapshot fork latency
agent process start latency
PTY first-byte/ready latency
PTY RTT/backpressure
reconnects
guest/sandbox crashes
sync-back bytes/conflicts
session duration/resource class

Target questions:

Why did cloudify take 2.1 s?
Was it workspace transfer, scheduler wait, VM fork, or Codex startup?

Do not record raw terminal content by default merely because transport passes through AIProxer. Enterprise audit capture, if ever offered, must be an explicit privacy/retention feature.

#502 semantic tracing can later link cloud-session admission/worker provisioning to the agent's inference traces, but tracing is not required for the first proof.

---

Performance goals

The product objective is local-like startup, especially after the first use of a repository/profile.

Measure cold and warm paths separately.

Suggested initial targets to validate rather than promise blindly:

Warm path

cached repository/object base
cached prepared agent snapshot
reflink-capable worker storage
nearby healthy worker with free capacity

Goal:

• sandbox fork/start: low hundreds of milliseconds or better;
• command -> usable remote PTY: sub-second p50 is the aspirational product target for small workspace deltas;
• exec/PTY interaction after attachment should add only low network + gateway overhead.

Cold path

Cold image/profile/repository preparation may take seconds and should be represented honestly as a separate state/progress path.

Do not ruin the warm architecture by rebuilding rootfs/images synchronously on every request.

Independently benchmark:

• direct Firecracker implementation;
• Crucible current implementation;
• XFS vs btrfs vs ext4;
• snapshot profile sizes;
• 1/16/64/100+ concurrent starts;
• memory sharing/COW behavior;
• repo delta transfer at common sizes.

---

Security requirements

This is a compute-provider boundary, not merely a convenience wrapper.

At minimum:

• mutually untrusted sessions must not rely solely on a shared userspace/container namespace boundary;
• Firecracker/microVM + jailer hardening or equivalently reviewed isolation;
• no host management socket/device exposure to guest;
• minimum guest devices/interfaces;
• per-VM network namespace and firewall policy;
• host kernel/VMM patch/update policy;
• cgroup/resource ceilings around VMM;
• unprivileged/dropped VMM uid where supported;
• tenant-scoped session authorization;
• worker/control-plane mTLS or equivalent strong node identity;
• signed/versioned guest/snapshot artifacts;
• bounded workspace archives/path handling;
• ephemeral session credentials;
• no provider master keys inside guest;
• no secret values in metrics/logs;
• teardown/reaping after daemon/host failures;
• orphan VM/netns/resource cleanup;
• threat model + security review before production multi-tenancy.

Do not market a pre-1.0 external runtime as "secure multi-tenant" solely because it uses Firecracker.

---

Open-Core / hosted-product boundary

Design this with the intended AIProxer Open-Core split in mind.

A reasonable boundary is:

OSS/client-side reusable pieces

• generic agent launch/supervisor interfaces;
• process wrapping shared with feat(wrapper): Add a feature which allows to "wrap" network traffic of some apps/agents and pass it through this proxy #392;
• workspace manifest/delta protocol types where useful;
• PTY client/attach protocol if keeping interoperability is valuable;
• local CLI command surfaces.

Closed/hosted AIProxer Cloud

• worker scheduler/control plane;
• bare-metal fleet management;
• production sandbox runtime/hardening;
• hosted compute billing/admission;
• tenant isolation policy;
• managed snapshot/profile catalog;
• cloud workspace/cache services;
• region/capacity placement;
• production cloud session APIs/UX.

Do not make ordinary OSS AIProxer inference depend on the cloud service.

---

Relationship to existing work

#392 — agent traffic wrapper

Complementary, not duplicate.

#392 owns local process launch/interception/redirection patterns such as:

aiproxer wrap codex

This issue owns:

remote worker scheduling
workspace transfer
sandbox creation
PTY attachment
compute lifecycle
remote agent launch/resume

Share one launcher/supervisor/agent adapter rather than implementing two independent Codex/Claude launch stacks.

The supervised wrap flow is also the best foundation for near-seamless in-agent !aiproxer cloudify handoff.

#348 — thin AIProxer CLI

Cloud commands should follow the same principle: CLI is a thin authenticated client over server/control-plane APIs, not a second state authority.

#453 / #466 — Codex / Claude first-class integration

Reuse client-specific endpoint/model/auth integration and capability detection. Do not duplicate config mutation or launcher semantics.

#483 — secrets

Useful later for controlled server-side secret references. Do not block the no-arbitrary-secret Codex prototype on full external secret-manager support.

#514 — Enterprise fleet HA

May supply generic membership/lease/topology ideas for the AIProxer service/control plane. Do not require Kubernetes for bare-metal cloud sandbox workers. Compute-worker scheduling should remain a distinct bounded domain.

#394 — high-concurrency performance

Remote-session work must not contaminate the existing inference hot path with scheduler/DB/filesystem operations. Cloud admission/provisioning is a separate API/control plane.

#478/#343 — tool approval/destructive safety

Remote isolation does not make destructive actions harmless; it changes the blast radius. Proxy/harness guardrails remain useful. Conversely, cloud sandbox isolation protects AIProxer infrastructure even when a tool policy misses a hostile repository/native binary.

---

Suggested staged implementation

This is too broad for one implementation PR/spec. Use this FR as the milestone anchor and split execution chronologically.

Phase 0 — architecture/performance/security spike

1. Prototype direct Firecracker vs Crucible-like runtime on one dedicated Linux/KVM box.
2. Benchmark cold boot vs warm snapshot fork.
3. Benchmark XFS/btrfs reflink vs ext4.
4. Validate vsock command/PTY transport options.
5. Write initial multi-tenant threat model.
6. Decide adopt/harden Crucible vs build the smaller required runtime directly.

Phase 1 — single-worker Codex vertical slice

local CLI
-> workspace snapshot/delta
-> one remote worker
-> warm sandbox
-> start Codex
-> PTY attach
-> LLM through AIProxer ephemeral token
-> exit
-> conflict-safe workspace sync-back

No multi-region scheduler, no live migration, no arbitrary secret sync.

Phase 2 — production session control plane

• authenticated cloud session API;
• worker registration/heartbeat;
• capacity-aware scheduler;
• lifecycle state machine;
• attach/detach/reconnect;
• orphan cleanup;
• resource limits;
• compute usage evidence/budget admission;
• snapshot/profile management;
• repo/object caching.

Phase 3 — workspace UX improvements

• optimized Git pack/object delta transport;
• live remote-to-local change mirror;
• optional bidirectional sync with conflict versioning;
• LFS/submodule/private repository polish;
• cache locality scheduling.

Phase 4 — resume/handoff

• Codex resumable-state adapter;
• !aiproxer cloudify --prepare-handoff generic path;
• supervisor IPC when launched through feat(wrapper): Add a feature which allows to "wrap" network traffic of some apps/agents and pass it through this proxy #392;
• terminal backend switch;
• Claude/other harness adapters after Codex is proven.

Phase 5 — production multi-tenant hardening

• independent security review;
• snapshot/image supply-chain signing;
• egress controls;
• rate/resource abuse controls;
• worker upgrade/drain;
• fault injection/host crash recovery;
• density/performance qualification;
• regional placement and capacity operations.

---

Suggested first API/CLI surface

Names are illustrative; exact API design belongs in SDD.

# launch remotely
aiproxer cloudify codex [-- <codex args>]

# lifecycle
aiproxer cloud list
aiproxer cloud status <id>
aiproxer cloud attach <id>
aiproxer cloud stop <id>
aiproxer cloud sync <id>

Potential later:

aiproxer cloudify --profile go-large codex
aiproxer cloudify --region fra codex
aiproxer cloudify --resume-current

Avoid making users choose implementation concepts like Firecracker snapshot IDs.

---

Acceptance criteria for the first useful vertical slice

• On Windows/macOS/Linux, the local AIProxer CLI can launch a remote Codex session on an AIProxer-managed Linux worker while the user continues to interact through their local terminal.
• The worker runtime requires no Docker or Kubernetes for sandbox execution.
• A remote session is isolated by a reviewed Firecracker/microVM-class boundary rather than ordinary shared-kernel namespaces alone.
• A warm prepared runtime can be forked/started without reinstalling the OS/toolchain/agent for every session.
• cloudify reproduces the local Git HEAD including local unpublished Git objects/commits plus dirty tracked and eligible untracked files.
• Gitignored files/secrets are not uploaded implicitly.
• Codex model traffic uses a short-lived AIProxer cloud-session credential; raw provider master keys are not copied into the guest.
• Local terminal raw/TUI behavior, resize, Ctrl-C, exit status and backpressure work through the remote PTY.
• Losing the local network temporarily can permit bounded reattach without immediately killing the remote agent.
• On session end, remote source changes can be synchronized back without silently overwriting concurrently changed local files.
• Per-session CPU/RAM/disk/time/network limits are enforced outside guest control.
• Worker/control-plane loss cannot leave indefinitely orphaned VMs/netns/session reservations.
• Provisioning telemetry decomposes scheduler/workspace/sandbox/agent/PTY latency.
• Warm-start performance is benchmarked on target hardware and clearly separated from cold preparation time.
• Disabling/not configuring AIProxer Cloud leaves ordinary local proxy/agent operation unchanged.

---

Acceptance criteria for later resumable handoff

• For a supported harness such as Codex, AIProxer can export/import the bounded resumable session state required to start a remote successor.
• !aiproxer cloudify does not claim to migrate live process memory.
• An unmanaged local agent receives a safe explicit attach/resume handoff when automatic terminal takeover is impossible.
• An agent originally launched through an AIProxer supervisor can request cloudification through IPC and have the supervisor switch from local process PTY to remote successor only after the remote session is confirmed ready.
• Failed remote provisioning leaves the local agent/workspace authoritative.
• No two successors are allowed to mutate the same logical workspace silently due to a handoff race.

---

Non-goals

• becoming a generic AWS/GCP replacement;
• Docker/Kubernetes as the required sandbox execution substrate;
• public-cloud dependency for worker provisioning;
• live CRIU-style migration of an arbitrary running Codex/Claude process and its memory;
• a browser IDE in V1;
• copying the user's whole home directory to the cloud;
• silently copying ignored secret files or every environment variable;
• rebuilding an OS/container image on every cloudify invocation;
• sharing the host kernel as the sole multi-tenant security boundary merely to save ~100 ms;
• allowing guests to access host/VPC management networks;
• pretending remote workspace sync is conflict-free when the local user edits the same files concurrently;
• putting worker scheduling/filesystem synchronization into the normal inference hot path.

---

References / research starting points

Remote sandbox/runtime:

• Crucible — Firecracker sandbox runtime for coding agents: https://github.com/gnana997/crucible
• Firecracker: https://github.com/firecracker-microvm/firecracker
• libkrun: https://github.com/containers/libkrun
• Bubblewrap: https://github.com/containers/bubblewrap

Related AIProxer work:

• feat(wrapper): Add a feature which allows to "wrap" network traffic of some apps/agents and pass it through this proxy #392 — app/agent wrapper and traffic interception
• feat(cli): Add thin client CLI for proxy control/admin APIs #348 — thin client CLI
• feat(codex-integration): Make proxy routes first-class models in Codex CLI/App/TUI #453 — first-class Codex integration
• feat(claude-code-integration): Make proxy routes first-class models in Claude Code #466 — first-class Claude Code integration
• feat(secrets): Add external secret-manager references with cached rotation-safe resolution #483 — external secrets
• feat(enterprise-ha): Add production multi-node fleet clustering, discovery and singleton coordination #514 — Enterprise fleet HA/coordination
• audit(performance): Reality check for high volume, highly concurrent proxy use #394 — high-concurrency performance discipline

---

Why 9.8/10

This is expensive to implement, but it creates a genuinely distinct product capability rather than another proxy configuration feature:

keep using Codex/Claude/OpenCode in the terminal you already like, but move the compute-heavy and potentially dangerous agent workspace onto near-instant AIProxer infrastructure with one command.

AIProxer is unusually well placed to make this seamless because it can combine the remote execution plane with the same model routing, budgets, credentials, safety, accounting and agent integration already being built at the proxy boundary. The critical design choice is to make session startup a warm workspace + microVM + PTY handoff operation, not conventional cold VM/container provisioning.

[matdev83]

Milestone hygiene

The issue body proposes a dedicated AIProxer Cloud / Remote Agent Execution milestone/workstream and says this tracker should not be placed into an unrelated existing milestone. GitHub currently assigns #525 to Splitted OSS / Enterprise repos, so the issue metadata and its stated sequencing intent are inconsistent.

No dependency edge should be inferred from this mismatch: #525 is not an OSS Base prerequisite and should not be wired to #398 or to any issue in another milestone. Once the dedicated Cloud/Remote Agent Execution milestone exists, move #525 there and use it as the anchor for the staged child specs/issues described above.

The available connector cannot create a new milestone or explicitly clear the current one, so this remains a manual milestone-metadata correction rather than a reason to invent a cross-milestone dependency.

[matdev83]

This is heavy feature meant for further discussion about the product design. Not just software/architectural decisions need to be made here.
Agents are NOT expected to implement this without human product decisions

[matdev83]

Milestone tracking correction

This issue is currently assigned to the existing Splitted OSS / Enterprise repos milestone, even though its own design calls for a separate AIProxer Cloud / Remote Agent Execution milestone/workstream. Treat the current assignment as a temporary holding classification, not as a dependency on post-split Enterprise work.

When the dedicated cloud/remote-execution milestone is created, move #525 there. Do not create cross-milestone blocked by edges in the meantime; relationships to #392/#348/#453/#466/#483/#514/#394 remain architectural/product coordination unless a future same-milestone implementation plan establishes a genuine prerequisite.

[matdev83]

Milestone hygiene

Current GitHub metadata assigns this issue to Splitted OSS / Enterprise repos, which contradicts the issue's own explicit requirement for a dedicated AIProxer Cloud / Remote Agent Execution milestone/workstream. Treat the current milestone-2 assignment as temporary tracking drift, not product sequencing.

The available connector cannot create the requested milestone or clear an existing milestone assignment. Once the dedicated Cloud/Remote Agent Execution milestone exists, move #525 there. Do not create dependencies from #525 to milestone-2 work merely because of its temporary placement.