--- title: "Sandboxes" description: "How the isolated dev environments behind every thread work" canonical_url: "https://hoplite.sh/docs/sandboxes" markdown_url: "https://hoplite.sh/docs/sandboxes.md" --- # Sandboxes URL: /docs/sandboxes LLM index: /llms.txt Description: How the isolated dev environments behind every thread work Related: /docs/sandboxes/scripts, /docs/sandboxes/previews, /docs/sandboxes/environment-variables, /docs/sandboxes/resources # Sandboxes Every [thread](/docs/threads) gets a **workspace** backed by an isolated sandbox runtime. Your repository is cloned, your [environment variables](/docs/sandboxes/environment-variables) are injected, and your [setup script](/docs/sandboxes/scripts) is applied. The agent installs dependencies, runs your tests, starts your dev server, and drives a browser against it. ## What the agent can see Each sandbox comes preconfigured with: - **Your repository**, cloned on the branch the thread targets - **A Git identity** scoped to the repo, with the `gh` CLI when the sandbox image provides it - **Your environment variables**, injected into every command the agent runs - **A persistent browser** the agent uses to verify its work ## What the agent cannot see The raw sandbox shell never receives a GitHub App credential, so agent-authored `git` and `gh` commands cannot inherit repository authority. First-party GitHub tools and supported worker-owned Git operations broker fresh, repository-scoped installation tokens inside Hoplite's trusted worker for the exact fetch or publication operation. Those tokens never reach the remote URL, Git configuration, workspace filesystem, or agent-authored shell. Preview access is brokered the same way: sandbox-provider tokens and Hoplite session cookies never reach the sandbox. See [Preview your app](/docs/sandboxes/previews). ## Lifecycle The workspace is durable product state; its provider runtime is replaceable. Depending on the provider, archiving may suspend the runtime or save a filesystem artifact before terminating it, and the next thread operation resumes or restores it behind the same thread. Modal snapshot-replace workspaces (the default for new workspaces) archive after the organization's idle policy and before the provider's maximum runtime, then transparently restore the worktree for the next thread operation. Native suspension remains an alternate provider behavior. While active work is running, Modal also keeps a baseline recovery snapshot and refreshes it periodically. If Hoplite confirms that the runtime died or the worktree became invalid, it restores the latest retained snapshot automatically rather than requiring a destructive reset. A recovery returns the workspace to its last snapshot, so unpushed changes made after that point can be lost. Normal archive and restore remains the durable path for later thread operations. For a Daytona compatibility workspace, the provider may confirm during archive that the runtime is already gone. Hoplite then retires the stale resource as archived and records that no fresh persistence artifact could be captured. Git-pushed work is unaffected, but unpushed work that was not present in an earlier artifact may be unrecoverable. If a runtime gets into a bad state, the agent — or you, via the thread's Terminal panel — can restart it. Disruptive operations require approval because they can kill running processes. ## Docker Compose workspaces The autoscaling standard runtime remains the default. You can explicitly select **Docker Compose** under **Settings → Project → Sandbox**, and that setting always wins. When no runtime profile is selected, Hoplite inspects the effective setup and run commands at the exact repository revision being provisioned. Decisive local Docker, Docker Compose, or local Supabase commands select an isolated VM runtime with a private Docker daemon; other repositories stay on the standard runtime. If setup or managed Preview recovery later exposes a requirement that the bounded initial inspection missed, Hoplite can replace the runtime behind the same thread. It preserves the repository worktree, including uncommitted and ignored files, but machine-global state and running processes do not carry across. Setup completes on the replacement before agents or managed Previews continue. The daemon is not exposed directly to agents or project commands, and Hoplite continues to provide application access through its authenticated preview. ## In this section - **[Setup and run scripts](/docs/sandboxes/scripts)** — `.hoplite/settings.json`: setup, run, and archive scripts, ports, and how overrides resolve - **[Environment variables and secrets](/docs/sandboxes/environment-variables)** — encrypted per-project secrets, injected into every command - **[Resources and scaling](/docs/sandboxes/resources)** — CPU, memory, and disk, and how the agent scales them - **[Preview your app](/docs/sandboxes/previews)** — live preview URLs, plus the in-thread Preview and Terminal panels ## Sitemap See the full [sitemap](/docs/sitemap.md) for all pages. Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).