KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #cli #react #mcp

cloudsail

★ 160 Open GitHub ↗

Self-hosted instant sandboxes for coding agents on Cloudflare.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Cloudsail

Instant use sandboxes for coding agents on Cloudflare with Cloudsail (_Alpha_). It runs on Cloudflare Workers, Durable Objects, Containers, and Sandboxes, and gives you a local CLI that opens an isolated remote computer for each project, PR, task, or experiment.

Use it when you want to run Codex, tests, package installs, git commands, and dev servers away from your laptop while keeping each workspace separated.

## Features

- **Instant Sandboxes:** Create as many isolated project sandboxes as you need, then destroy them when done.
- **Secure by Default:** GitHub and API credentials live in the Worker instead of being exposed to compromised containers.
- **Controlled Egress:** Access GitHub, OpenAI/ChatGPT, and package registries by default; add docs hosts with `cs allow`.
- **GitHub Integration:** Start with a GitHub Repo or PR URL, inspect diffs, commit, push, and open PRs.

## Requirements

- Node 23+
- A Cloudflare account with Workers, Durable Objects, Containers, and Sandboxes enabled
- Docker Desktop, or another Docker-compatible daemon, for `cs deploy`
- Git

For Codex, either use ChatGPT subscription auth inside the sandbox or configure `OPENAI_API_KEY` as a Worker secret. For GitHub, a fine-grained token works for alpha testing; a GitHub App installation is the better long-term credential.

## Install

```sh
npm install -g cloudsail
```

Log in to Cloudflare if you have Wrangler on your PATH:

```sh
wrangler login
```

If `wrangler` is not already on your PATH, skip that command. The Cloudsail package includes Wrangler, and `cs setup` will open Cloudflare login with the packaged copy if needed.

## Deploy Your Cloudsail

Run setup once:

```sh
cs setup
```

`cs setup` creates `~/.config/cloudsail/config.json`, writes the deploy config to `~/.config/cloudsail/deploy/wrangler.jsonc`, generates a local auth token, and stores that token as the Worker secret `CLOUDSAIL_AUTH_TOKEN`.

Set optional credentials. If the variable already exists in your environment, Cloudsail passes it to Wrangler; otherwise Wrangler prompts securely:

```sh
cs secret set GITHUB_TOKEN
cs secret set OPENAI_API_KEY
```

For GitHub App auth:

```sh
cs secret set GITHUB_APP_ID
cs secret set GITHUB_APP_INSTALLATION_ID
GITHUB_APP_PRIVATE_KEY="$(cat private-key.pem)" cs secret set GITHUB_APP_PRIVATE_KEY
```

Deploy the Worker and container image:

```sh
cs deploy
```

`cs deploy` runs Wrangler against the packaged Worker and Dockerfile. You do not need to clone the Cloudsail repo. After deploy, it saves the deployed Worker URL into `~/.config/cloudsail/config.json`.

Check the setup:

```sh
cs doctor
```

Useful setup commands:

```sh
cs config show
cs config path
cs config deploy-path
cs secret list
cs deploy --dry-run
```

Use a different Worker name:

```sh
cs setup --name my-cloudsail
cs deploy --name my-cloudsail
```

## First Sandbox

Create an empty sandbox:

```sh
cs create my-task --type standard-2
cs shell my-task
```

Seed a sandbox from a GitHub repo:

```sh
cs gh https://github.com/owner/repo my-task
cs shell my-task
```

Seed from a pull request:

```sh
cs gh https://github.com/owner/repo/pull/123 fix-123
cs shell fix-123
```

Inside `cs shell`, commands run in the remote sandbox:

```sh
pnpm install
pnpm test
codex
```

Jump straight into Codex:

```sh
cs codex my-task
```

Run a one-off command:

```sh
cs run my-task -- 'pwd; git status --short; pnpm test'
```

## Testing Web Apps

Start a dev server in the sandbox and expose it:

```sh
cs dev my-task --port 5173 -- pnpm dev --host 0.0.0.0
cs ports my-task
cs open my-task 5173
```

You can also run the dev server manually inside `cs shell`, then expose the port:

```sh
pnpm dev --host 0.0.0.0
cs expose my-task 5173
```

Production preview URLs need a Cloudflare route that can receive the generated preview hostnames. For serious browser testing, configure `CLOUDSAIL_PREVIEW_HOST` in `~/.config/cloudsail/deploy/wrangler.jsonc` or in the Cloudflare dashboard before deploying.

Preview URLs are authenticated. Open them with `cs open`, `cs dev`, or `cs expose`; the CLI mints a short-lived browser ticket and the Worker stores it as an HTTP-only cookie. Raw exposed URLs return `401` unless the request includes `CLOUDSAIL_AUTH_TOKEN` bearer auth.

## Credentials

Cloudsail keeps Worker-owned credentials outside the remote computer. The sandbox receives a harmless placeholder `OPENAI_API_KEY` so API-key CLIs can detect that auth exists. When an approved HTTP or HTTPS request leaves the sandbox, the Worker injects the real credential at the edge.

- `api.openai.com`: Worker injects `OPENAI_API_KEY`.
- `chatgpt.com`: Codex ChatGPT subscription traffic is allowed; Cloudsail does not inject subscription credentials.
- `github.com` and `api.github.com`: Worker injects GitHub auth only for the project's repo.
- The container cannot read the real token from env, files, process args, or shell history.
- Terminal WebSockets use short-lived one-time tickets.
- Public internet is blocked by default except for the configured HTTP/S allowlist.

Inside `cs shell`, `echo "$OPENAI_API_KEY"` prints the placeholder, not your real key. `git fetch`, `git push`, and OpenAI API calls still work through Worker-side injection.

## Egress

Sandboxes start with the hosts needed for normal development: GitHub, OpenAI, ChatGPT, npm registries, and common GitHub asset hosts.

Add docs or research hosts per project:

```sh
cs egress my-task
cs allow my-task viteplus.dev
cs allow my-task docs.astro.build
cs disallow my-task viteplus.dev
```

Project-added hosts are read-only. `GET`, `HEAD`, and `OPTIONS` are allowed; mutating requests are blocked.

## Git Workflow

Use normal git inside the sandbox:

```sh
git status
git add -A
git commit -m "Build feature"
git push origin HEAD:cloudsail/my-feature
```

Cloudsail also includes optional helpers:

```sh
cs diff my-task
cs changes my-task
cs commit my-task "Build feature"
cs push my-task cloudsail/my-feature
cs pr my-task "Build feature"
```

`cs changes --json` exposes commit and file before/after data for tools such as codiff.

## Lifecycle and Cost

Cloudsail defaults to `CLOUDSAIL_SANDBOX_SLEEP_AFTER=3h`. A sandbox can stay warm during active work, then Cloudflare can shut it down after roughly three idle hours.

Live terminals and dev servers stop when the sandbox sleeps. Durable state should be in Git commits, pushed branches, or checkpoints. Cloudsail is not a durable VM unless you checkpoint or push your work.

Change keepalive per sandbox:

```sh
cs keepalive my-task 3h
cs keepalive my-task 24h
cs keepalive my-task 7d
cs keepalive my-task forever
cs keepalive my-task off
```

`forever` keeps the sandbox alive until you destroy it:

```sh
cs destroy my-task
```

Approximate idle live cost for the default `standard-2` container:

- `3h`: about `$0.17` per sandbox
- `24h`: about `$1.37` per sandbox
- `7d`: about `$9.58` per sandbox

CPU usage, Workers, Durable Objects, logs, egress, and included monthly usage can change the final bill.

## Project Config

Cloudsail stores user config at:

```sh
~/.config/cloudsail/config.json
```

Repo-local defaults can live in `.cloudsail.json`:

```sh
cs init
```

Environment variables override stored config for one command:

```sh
CLOUDSAIL_URL=https://your-worker.workers.dev CLOUDSAIL_AUTH_TOKEN=... cs doctor
```

## Contributing

Clone the repo only if you want to work on Cloudsail itself:

```sh
git clone https://github.com/nkzw-tech/cloudsail.git
cd cloudsail
pnpm install
pnpm check
pnpm test
pnpm pack:check
```

Run the local Worker during development:

```sh
cp .dev.vars.example .dev.vars
pnpm dev
```

Run a production smoke test after deploying:

```sh
pnpm smoke:prod
```

## Docs

- [Security policy](SECURITY.md)
- [Architecture proposal](docs/remote-sandbox-proposal.md)
- [Repo setup notes](docs/repo-setup.md)
- [Next steps](docs/next-steps.md)

cloudsail

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README