Persistent AI Agent Laptop to VPS Handoff

A developer outlined an architecture for handing off long-running AI coding agent tasks between a laptop and a VPS by treating agent runs as stateless compute over durable shared state. The approach persists task metadata, checkpoints, branch identities and next actions in JSON or YAML state files, uses an ownership lock to keep handoffs idempotent, and requires committing and pushing the branch with a recorded commit hash before the remote runner resumes.

A local coding session is interactive and responsive, but it disappears entirely when your laptop goes to sleep. A virtual private server VPS is always on and ready for long-running jobs, but it lacks the transient context and immediate feedback loop of your local environment. The hard part of maintaining an always-on assistant is not spinning up the remote server, but preserving task state, work ownership, and resumability across different runtimes. Many developers try to solve the always-on agent problem by running a tmux session on a remote server and attaching to it from anywhere. This approach keeps the process alive, but it couples your active session to a single machine. If you want to start a complex coding task on your laptop while traveling and let your VPS finish the heavy test suites overnight, you need an architecture where compute is entirely separate from task state. For a related implementation, see Always On Ai Agent Architecture https://raylabs.app/articles/always-on-ai-agent-architecture/ . An agent run should be treated as stateless compute operating over durable shared state. When you decouple the runner from the data, you can stop a process on one machine and pick it up on another without losing progress or corrupting your codebase. To resume an interrupted session successfully, specific files and metadata must persist outside the local memory of the agent process. Task metadata, intermediate checkpoints, generated artifacts, branch identities, and next planned actions must all be written to a durable location. Consider a scenario where your laptop runner creates a feature branch, generates an implementation plan, and executes the first three steps of a refactoring task before the battery dies. For the VPS to resume the work seamlessly, it needs access to the exact Git commit, the active worktree, and a structured ledger showing which steps are complete and which remain. LLM chat history is a fragile medium for tracking long-running tasks. Replaying thousands of tokens of conversation to remind an agent where it left off is expensive, slow, and prone to context drift. For a related implementation, see Ai Agent Handoff Fallback Context https://raylabs.app/articles/ai-agent-handoff-fallback-context/ . Instead, use explicit JSON or YAML state files stored in a shared volume or synchronized repository to record progress. Below is an example of a durable task state file that an agent updates after completing each discrete step: { "task id": "task-8891-refactor", "status": "paused", "current step": 3, "total steps": 6, "branch": "feature/auth-cleanup", "last checkpoint commit": "a1b2c3d", "next action": "run test suite for auth middleware" } When a runner starts up on the VPS, it reads this file, verifies the Git reference, and immediately executes the next action without parsing historical chat logs. When moving tasks between machines, a race condition can occur if both your laptop and your VPS attempt to process the same task simultaneously. To prevent duplicate execution and conflicting writes, handoffs must be strictly idempotent. Implement an ownership lock using a distributed lock manager, a database transaction, or a simple atomic file lock in your storage layer. A runner must acquire the lease on the task ID before executing any state changes. If the lock acquisition fails because another runner is active, the process must safely abort or wait. State files alone are insufficient if the underlying codebase is out of sync. Before any handoff occurs, the local runner must commit all changes or stash them cleanly, push the branch to a remote repository, and record the exact commit hash in the task state file. When the VPS picks up the task, it pulls the latest changes, checks out the recorded commit, and validates that the local working tree is clean before resuming execution. This guarantees that file modifications made on the laptop are fully visible to the remote environment. Designing resilient AI agents requires shifting away from continuous interactive sessions toward discrete, resumable tasks. By storing state in explicit checkpoints, enforcing strict task ownership locks, and synchronizing code via version control, you can move workloads between your local development machine and a remote server safely and predictably.