coreweave/cws-agent

coreweave/cws-agent

Language: Python

License: Apache-2.0

Stars: 0

Forks: 0

Open issues: 0

Created: 2026-09-15T23:00:44Z

Pushed: 2026-09-15T23:04:22Z

Default branch: main

Fork: no

Archived: no

README:

cws-agent

Run Claude Code, Codex, Devin CLI, OpenCode, or Cursor CLI in a CoreWeave sandbox. Also run [OpenAI Agents API tools on CoreWeave](docs/openai-agents.md), with OpenAI managing the agent and conversation.

Install once

Already have cws-agent --help working? Skip to [Launch](#launch).

Requires Git, uv, and macOS, Linux, or WSL.

git clone https://github.com/coreweave/cws-agent.git
cd cws-agent
mkdir -p "$HOME/.local/bin"
ln -s "$PWD/cws-agent" "$HOME/.local/bin/cws-agent"
export PATH="$HOME/.local/bin:$PATH"
cws-agent --help

Add the export PATH=... line above to ~/.zshrc (or ~/.bashrc) for future terminals. Keep the checkout: the installed command links to it. If the link already exists, inspect command -v cws-agent before changing it; these instructions do not overwrite an existing installation.

All examples use `cws-agent`, which works from any project directory. A ./ prefix looks for a file in your current directory instead.

Launch

Set your CoreWeave credential, then change to the project you want to upload:

export CWSANDBOX_API_KEY='YOUR_COREWEAVE_KEY'

Choose one agent:

cws-agent launch --name claude1 --local-dir . # Claude Code (default)
cws-agent launch --name cdx1 --agent codex --local-dir . # Codex
cws-agent launch --name dvn1 --agent devin --local-dir . # Devin CLI
cws-agent launch --name open1 --agent opencode --local-dir . # OpenCode
cws-agent launch --name cursor1 --agent cursor --local-dir . # Cursor CLI

Launch opens the remote agent. Follow its sign-in flow; if needed, exit the agent to return to your local shell and run:

cws-agent login claude1

For Claude, type /login inside the agent. For the others, use their sandbox name. Already have an agent token or API key? See [authentication](docs/usage.md#authentication). Setup and differences: [OpenCode](docs/opencode.md) · [Cursor CLI](docs/cursor.md).

OpenCode with an open-weight coding model on W&B Serverless Inference:

export WANDB_API_KEY='YOUR_WANDB_KEY'
cws-agent launch --name open-wandb --agent opencode --wandb --local-dir .

Keep your sandbox credential set. Get the W&B key from User Settings → Create new API key; inference access and credits are required. The preset selects DeepSeek V4 Pro 0813, with no fallback to GPT or another provider. [Key setup, model choice, and alternatives](docs/opencode.md#wb-serverless-inference).

Your project lands at /workspace/project. Local sync shows packaging/upload sizes and progress (. means the entire current directory). Launch automatically sizes the disk to fit local files with headroom; --disk overrides it. Project uploads are resumable: on failure, run the printed cws-agent sync NAME --resume-upload ID command. Completed chunks are reused without repackaging. The sandbox stays billable until stopped or expired. See [upload recovery](docs/usage.md#resume-an-upload). With --telegram, skills/MCP setup and sign-in come first; workspace upload runs in the background while you chat. Completion automatically saves a snapshot. Later: cws-agent restore telegram2 --telegram --dangerously-skip-permissions restores the saved workspace and reconnects the bot without another upload. Edits are accepted by default where supported; Cursor retains its native permissions. Other actions can still need approval. Review the skills/MCP import prompt, or press Enter to skip. Exiting the agent does not stop the sandbox.

Daily commands

cws-agent list
cws-agent connect claude1 # open the agent in a running sandbox
cws-agent sync claude1 . # upload local changes
cws-agent run claude1 "summarize this repo" # one-shot prompt
cws-agent snapshot claude1 # save workspace without stopping
cws-agent down claude1 # snapshot and stop compute
cws-agent restore claude1 --connect # restore and open the agent

Re-export environment-only credentials before restore. Snapshots retain files and saved logins, not running processes. To continue a specific conversation, use session resume below.

Snapshot preparation temporarily changes live permissions and link representations; read the [snapshot caveat](docs/usage.md#snapshots) before storing sensitive data.

Continue a conversation

cws-agent session history claude1
cws-agent session resume claude1 SESSION_ID

History listing supports Claude/Codex and OpenCode workspace projects; Cursor uses its native picker (session history NAME --agent cursor). For upload/download and multiple agents in one sandbox, see [sessions](docs/sessions.md).

Claude Managed Agents: a separate mode

Use --agent claude for the Claude Code terminal. Use --claude-env to run Managed Agents tool workers:

export ANTHROPIC_ENVIRONMENT_KEY='YOUR_ENVIRONMENT_KEY'
cws-agent launch --name claudebox --claude-env env_REPLACE_ME

This starts workers and returns to your shell. It does not create a conversation. Managed Agents supports interactive conversations through its API, but cws-agent has no Managed Agents chat command. Neither login nor attaching to worker logs opens a chat.

See [self-hosted setup](docs/self-hosted.md) for connecting an agent/session, checking worker connectivity, and Devin Outposts. Environment keys are not Claude Code login tokens.

More features

Create a Claude sandbox and connect Telegram in one command:

cws-agent launch --name telegram2 --local-dir . --telegram --dangerously-skip-permissions

Follow sign-in and QR pairing; leave the command running. The permission flag bypasses tool approvals. [Configure a management bot once](docs/messaging.md#create-bots-without-copying-their-tokens) to create bots without copying each token; otherwise setup asks for a BotFather token.

| Task | How | | --- | --- | | Parallel agents, restart, history transfer | [Sessions guide](docs/sessions.md) | | Bypass permissions explicitly | cws-agent connect claude1 --yolo — [permissions](docs/permissions.md) | | Review skills and MCP imports | cws-agent config sync claude1 — [configuration](docs/config-import.md) | | Paste a local image into remote Claude | Ctrl+V — [terminal...