Git and Agent Architecture on Cloudflare

Git operations can run on Artifacts, queryable records can live in D1, and large outputs can be stored in R2. Durable Objects can be used to manage active tasks and concurrent connections.

The queryable fields of a commit record can be kept in D1, while the large file produced by the commit can be stored in R2.

Git layer

Cloudflare’s Artifacts component can be used as a versioned file system that works with Git. Artifacts is currently in open beta and can fork upstream repositories such as GitHub. According to Cloudflare’s Artifacts announcement, repository creation, branch creation, committing, getting diffs, and searching can all be programmed.

Workers can create repositories through an Artifacts binding, fork them, and inspect files and commits. Repository-scoped Git tokens can also be generated through this binding. You should use tokens only for the operation that needs them, since they may be limited to a specific repository and expiration period.

The create() and import() operations directly return a remote repository URL. You can use the returned URL with standard Git commands:

git clone <remote-repo-url>
git clone --depth 1 <remote-repo-url>

Artifacts can also be used as an agent’s workspace. A fork is created from a shared baseline repository, and AGENTS.md instructions are added to the workspace.

Changes made by the agent are committed inside the workspace. These changes can then be compared with the original repository. My suggestion here is to make the boundary between the repostory the agent works in and the target repository explicit from the start. Instead of writing directly to the same repository, keeping the agent’s changes in a separate workspace makes it clearer what ends up in the target branch.

You can subscribe to repository push events:

// A flow that listens for push events inside a Worker
if (event.type === "cf.artifacts.repo.pushed") {
  await runCI(event.repo);
  await startCodeReviewAgent(event.repo);
}

When you subscribe to the cf.artifacts.repo.pushed event, a Worker can connect the push event to a workflow such as CI or a code review. Cloudflare’s Git platform announcement specifically highlights this event-based deployment scenario.

Workers Builds can connect an Artifacts repository to a Worker. A push to the production branch can deploy the current Worker. Pushes to other branches can be shared automatically and used to create isolated Workers Previews. This makes it possible to use a separate deployment path for testing without treating every branch as production.

Data layer

D1 works with tables and SQL queries accessed through a Worker or API. It may be suitable for repository metadata, user information, agent tasks, and commit summaries.

For example, you could consider the following tables for a commit record:

CREATE TABLE commits (
  id TEXT PRIMARY KEY,
  repo_id TEXT NOT NULL,
  message TEXT NOT NULL,
  author TEXT NOT NULL,
  created_at TEXT NOT NULL
);

D1 uses SQL for queryable records. You should separately verify whether D1 is suitable for operations with a high write frequency.

R2 is better suited to storing large amounts of unstructured data. Build artifacts, log files, large outputs, or files produced by agents can be kept here. R2 is described as standing out from traditional cloud storage because it does not have the expensive egress bandwidth fees commonly seen in those services. Based on the status and storage options, R2 appears more suitable for large, unstructured data.

The shape of the data is not the only factor in this choice. The access method is just as important. D1 provides a better starting point for records that need to be queried with SQL, R2 is better for storing files or outputs, and Durable Objects are better for managing active tasks and concurrent connections between clients. Establishing this separation from the start, instead of using a single service, may reduce the need for a large-scale rewrite later. Keep in mind, however, that the same boundaries do not apply to every operation.

Agent workspaces

An agent workspace can be isolated by creating a fork from a shared baseline repository. You can add an AGENTS.md file to this workspace and write the repository rules, test command, and workspace boundaries in it.

In the AgentSandbox approach, each sandbox runs as its own AgentSandbox Durable Object with its own container. Only one Claude Code task can run at a time per Durable Object. The Sandbox setup documentation specifically calls out this limit. Instead of running multiple tasks one after another in the same object, keeping the boundaries of each workspace separate creates a clearer model.

You can inspect the changes made by the aegnt with the following command:

git add --intent-to-add . && git diff

By reviewing the output and the workspace’s commit history, you can see which files the agent touched. After reviewing the diff and commit history, transfer only the changes that should enter the target branch from the workspace.

In Cloudflare OS, each workspace runs on its own Durable Object. Each Gadget runs in a separate Dynamic Worker Facet. This separation is useful for isolating application components.

On the Gadget server, internet access is disabled unless it is explicitly allowed. Communication with external resources can happen only through the specified Workers Bindings. Therefore, if you expect the agent to connect only to defined resources and not access arbitrary URLs, this creates an acceptable security boundary for the model.

State and security

Durable Objects combine compute and persistent storage in a single building block. They can provide coordination when multiple clients need to work together. They also provide an option for sessions and WebSocket connections. The Durable Objects documentation also explains alarm mechanisms and persistent storage features.

One object should manage only task state, while another object used for connection management should handle client connections. Gatekeepers record Gadget or agent actions. They can narrow access to external services on a resource-by-resource basis and use authorization methods such as OAuth. They can present bulk or individual approval options for operations with side effects.

The result of an action waiting for approval can be simulated locally. This allows the agent to continue working while the real action is executed only after user approval. Simulate the result of an action waiting for appoval locally, then review the output before sending it to the real service.

You can use the quick-start command given in the notes to try Cloudflare OS on a local server:

pnpm run-local

While designing the architecture, the layers appear to be able to evolve independently. Building the repository and branch flow with Artifacts, adding metadata queries to D1, and separating large outputs into R2 can make the system easier to manage. Task coordination and access to external resources can be handled by Durable Objects and Gatekeepers. Keeping these responsibilities separate instead of combining all of these layers in one service is a healthier approach.

Sources

• We want you to build the next Git platform on Cloudflare (Cloudflare Blog)

• cloudflare/cloudflare-os: Agent workspace built on Cloudflare Workers for creating documents, building apps, and running agents with your company’s context and systems. (GitHub)

• Git integration (Cloudflare Docs)

• Cloudflare Artifacts (cloudflare.com)

• GitHub - cloudflare/workers-for-platforms-example: A great place for ... (GitHub)

• Cloudflare OS: your company’s agent workspace, managed for you (cloudflare.com)

• Build a coding agent runner (Cloudflare Docs)

• Cloudflare KV vs D1 vs R2 vs Durable Objects (flaviocopes.com)

• Overview · Cloudflare Durable Objects docs (Cloudflare Docs)