Local Project Mode

chaser dev is Chaser’s local-first workflow for development. Keep your editor, local files, and local Git workflow on your machine, while shell commands and agents run inside a remote sandbox.

This mode is designed for the case where your local checkout is the source of truth and the sandbox is the execution mirror.

When to use it

Use chaser dev when:

• You already have a project checked out locally.
• You want to keep editing files with your existing editor and local tooling.
• You want builds, installs, tests, and agent work to happen in an isolated remote sandbox.
• You want sandbox-originated file changes to sync back locally with a ledger and rollback path.

Use Remote Workspace Development instead when the remote workspace itself should be the canonical copy of the project.

Quickstart

From a project directory:

$
chaser login
$
cd ~/code/my-project
$
chaser dev

chaser dev:

• resolves the project scope from the Git root when one exists, otherwise from the current directory
• preserves the nested launch directory as the remote working directory under /workspace
• creates or reuses a project-scoped sandbox workspace by default
• falls back to an ephemeral sandbox when persistent workspaces are unavailable
• syncs the local project into the sandbox before attaching a shell

When you reconnect later, Chaser reuses the same project-scoped workspace when possible so remote caches and toolchains survive across shell sessions.

How it works

Local Project Mode is sync-based, not a shared filesystem mount.

The local project stays authoritative. Chaser keeps a mirrored copy in the sandbox and reconciles changes in both directions with a short polling loop.

Local project (authoritative)
    |
    |  bootstrap + incremental sync
    v
Sandbox /workspace (execution mirror)

This model keeps local editors and Git workflows unchanged while still running code in a remote microVM.

What syncs

Bootstrap and incremental sync reuse your local ignore rules and add Chaser-specific defaults:

• .gitignore is respected during local scanning
• .chaserignore adds project-specific exclusions for Local Project Mode
• .chaser/ is always local-only metadata
• heavy generated directories such as node_modules, target, .venv, .next, .turbo, and similar remain remote-only by default

Git metadata is treated specially:

• the local Git state is authoritative
• Git metadata is pushed from local to remote for read-oriented tooling
• remote .git mutations do not sync back to the local checkout

This means remote git status can stay useful for inspection, while Chaser avoids silently rewriting local Git history.

Metadata, ledger, and rollback

Each project gets a local metadata directory:

.chaser/
  state.json
  ledger.ndjson
  objects/
  conflicts/

Key files:

• state.json tracks the current project-mode session, workspace, sync base, and paused conflicts
• ledger.ndjson records sandbox-originated mutations applied locally
• objects/ stores preimages used for rollback
• conflicts/ stores remote copies for paths that need manual resolution

Useful commands:

$
chaser dev status
$
chaser dev log
$
chaser dev undo <tx_id>
$
chaser dev doctor

If you omit <tx_id>, chaser dev undo targets the most recent reversible sandbox-originated transaction.

Conflict handling

When the same path changes locally and remotely since the last synced base, Chaser does not overwrite your local file.

Instead it:

• leaves the local file in place
• stores the remote version under .chaser/conflicts/<tx_id>/...
• records the conflict in the ledger
• pauses syncing for that path until you resolve it locally

Once you edit the local file to the version you want to keep, Chaser treats the local result as the resolution and syncs it back to the sandbox.

Commands

$
# Start project mode from the current project
$
chaser dev
$
$
# Explicit shell form
$
chaser dev shell
$
$
# Force a disposable remote sandbox
$
chaser dev shell --ephemeral
$
$
# Inspect state and health
$
chaser dev status
$
chaser dev doctor
$
$
# Review and undo remote-applied edits
$
chaser dev log
$
chaser dev undo tx_...

Compatibility shim

chaser-sh remains available as a compatibility path for tools that insist on driving a shell via the SHELL environment variable.

Example:

$
export SHELL=/usr/local/bin/chaser-sh

The recommended surface is still chaser dev shell. The shim exists so shell-oriented tools can route through the same project-mode engine when needed.

Free vs paid behavior

• Paid accounts default to a persistent project-scoped workspace for chaser dev
• Free accounts fall back to ephemeral sandbox sessions when persistent workspace creation is unavailable
• Your local files and .chaser ledger stay safe on the local machine either way
• The main difference is whether remote caches and long-lived workspace state persist between runs

Choosing the right surface

Related

• Quickstart — fastest path to your first chaser dev session
• CLI Reference — full command syntax
• Remote Workspace Development — remote-first workflow
• Sandbox Sessions — sandbox lifecycle and exec details