Cloud Code is a containerized Agent solution that combines Cloudflare's powerful infrastructure with OpenCode's intelligent capabilities.

This is a TypeScript project based on Cloudflare Workers and Cloudflare Containers. It leverages Cloudflare's infrastructure to run and manage containerized workloads.

English | 简体中文

• pnpm (recommended)
• Node.js (v20+ recommended)
• Wrangler CLI (pnpm add -g wrangler)

pnpm install

Start the local development server:

pnpm dev
# or
pnpm start

This command will start wrangler dev, simulating the Cloudflare Workers environment.

If you modify the bindings in wrangler.jsonc, you need to regenerate the type files:

pnpm cf-typegen

Deploy your code to Cloudflare's global network:

pnpm deploy

.
├── src/
│   ├── index.ts        # Workers entry file (ExportedHandler)
│   ├── container.ts    # AgentContainer class definition (extends Container)
│   └── sse.ts          # SSE (Server-Sent Events) stream processing logic
├── worker-configuration.d.ts # Auto-generated environment bindings types
├── wrangler.jsonc      # Wrangler configuration file
├── tsconfig.json       # TypeScript configuration
└── package.json

To protect your Agent from unauthorized access, this project supports standard HTTP Basic Auth authentication.

Set the following variables in wrangler.jsonc or in the Cloudflare Dashboard environment variables:

1. Authentication is only enabled when the SERVER_PASSWORD environment variable is set.
2. Client requests must include an Authorization: Basic <credentials> header.
3. If authentication fails, the server returns a 401 Unauthorized status code.

Cloud Code containers have built-in support for S3-compatible storage (such as Cloudflare R2, AWS S3), using TigrisFS to mount object storage as a local filesystem for persistent data storage.

To enable data persistence, configure the following environment variables in the container runtime:

1. Mount Point: When the container starts, the S3 bucket is mounted at /root/s3.
2. Working Directory: The actual workspace is located at /root/s3/workspace.
3. OpenCode Configuration: OpenCode's configuration files (XDG directory) are also stored in /root/s3/.opencode, ensuring editor state persistence.
4. Initialization:
   • If the S3 bucket (or specified prefix path) is empty, the container will automatically copy the preset workspace directory contents into it.
   • If S3 configuration is missing, the container will fall back to non-persistent local directory mode.

The container comes pre-installed with the cloudflared CLI, which can be used to expose services running inside the container (such as development servers, web applications) to the public internet via Cloudflare Tunnel.

This is useful in the following scenarios:

• Debugging web services running inside the container
• Temporarily sharing development environments
• Configuring SSH access

Usage example (in the container terminal):

# Expose port 8080 inside the container to the public internet
cloudflared tunnel --url http://localhost:8080

• Runtime: Cloudflare Workers
• Language: TypeScript
• Core Libraries:
  • cloudflare:workers: Workers standard library
  • @cloudflare/containers: Container management and interaction
• Tools: Wrangler
• Container Environment:
  • nikolaik/python-nodejs: Python 3.12 + Node.js 22
  • tigrisfs: S3 filesystem mount
  • cloudflared: Cloudflare Tunnel client
  • opencode: Intelligent coding Agent

The official language for this project is English (code, comments, and commit messages are in English). This README is the English version. For detailed development guidelines, code style, and Agent behavior rules, please refer to AGENTS.md.