> For the complete documentation index, see [llms.txt](https://docs.run.claw.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.run.claw.cloud/clawcloud-run/architecture/devbox-architecture.md).

# Devbox Architecture

Clawcloud Run Devbox is an advanced development environment solution that leverages cloud-native containers and Kubernetes technology to deliver a unified and flexible development runtime. Its core feature lies in simulating a traditional virtual machine experience while retaining the advantages of containerization.

### Architectural Overview

Clawcloud Run Devbox employs a layered architecture comprising the following core components:

* Access Layer: Provides entry points via WebPage, VS Code Extension, JetBrains Gateway, and Direct API for seamless integration with developer workflows.
* Manage Controller Layer: Orchestrates lifecycle operations (Create/Delete, TurnOn/Shutdown/Reboot), configuration management (Update/Commit), ingress access control, database metadata handling, and collaboration features (Release/Share).
* Cluster Layer: Implements infrastructure abstractions through Kubernetes API Server, Container-Shim for runtime isolation, and a Devbox Registry interfacing with containerd and Object Storage for persistent artifact management.

<figure><img src="/files/ee94ZR8GZccJv1TrrxLt" alt=""><figcaption><p>Devbox Architecture</p></figcaption></figure>

### Control Flow

Devbox implements a decoupled frontend-backend design:

1. User Action: Operations are triggered by users via the web interface or IDE plugins (e.g., VS Code, JetBrains).
2. Request Handling: The Devbox Controller receives and processes these requests.
3. Kubernetes Integration: The controller translates processed instructions into Kubernetes API calls.
4. Execution: Kubernetes executes corresponding container operations based on the API directives.

<figure><img src="/files/1SMCP8krNBZNfI2QDpoo" alt="" width="451"><figcaption><p>Devbox Control Flow</p></figcaption></figure>

### State Persistence Mechanism

Devbox implements an intelligent state preservation system to ensure user environment consistency:

#### **Automatic Snapshotting**

* System automatically preserves environment changes under predefined conditions
* Modifications are packaged as image layers
* New layers are appended as commits to the base image
* Updated images are securely stored in an isolated internal registry

#### **Environment Restoration**

* During environment relaunch, the system initializes from the latest persisted image
* Preserves the complete change history through incremental layer stacking

#### **Optimization**

Container-shim layer provides automated maintenance:

* Periodically merges image layers for storage efficiency
* Automatically purges redundant data artifacts
* Optimizes image size and layer count to maintain optimal system performance

<figure><img src="/files/FNjwxXdEoMD8sy1ReYm8" alt=""><figcaption><p>Devbox State Persistence Mechanism</p></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.run.claw.cloud/clawcloud-run/architecture/devbox-architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.