CodeCloud agents have always required a GitHub repository. Clone the repo, read the code, make changes, open a PR. That's the core loop.

But not every task involves code. Sometimes you want an agent to query an API, transform some data, generate a report, or orchestrate a workflow across services. No repo needed.

You can now set blank_workspace: true to run an agent in an empty sandbox with only your custom tools available.

How it works

Add blank_workspace: true to your API request. The agent starts in a clean environment—no repository is cloned, no GitHub installation is required. The repo, branch, and auto_create_pr fields are ignored.

curl -X POST https://codecloud.dev/api/v1/agents \
  -H "Authorization: Bearer cc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "blank_workspace": true,
    "prompt": "Get all P0 incidents from the last 24 hours and write a summary",
    "tools": [
      {
        "name": "get_incidents",
        "description": "Fetch incidents from PagerDuty. Returns title, severity, status, and created_at.",
        "parameters": {
          "type": "object",
          "properties": {
            "severity": {
              "type": "string",
              "enum": ["P0", "P1", "P2", "P3"],
              "description": "Filter by severity"
            },
            "since": {
              "type": "string",
              "description": "ISO date string, return incidents after this date"
            }
          }
        },
        "endpoint": {
          "url": "https://internal.yourcompany.com/api/incidents",
          "method": "GET",
          "headers": {
            "Authorization": "Bearer your-pagerduty-token"
          }
        }
      }
    ]
  }'

The agent receives your prompt and tools, does its work, and returns the result via the API or webhook. No PR is created because there's no repo to push to.

When to use it

Blank workspace mode is designed for workflows where code isn't the output. A few examples:

Incident summaries – Pull incidents from PagerDuty or Opsgenie, correlate with deployment logs, and generate a summary for the team
Data transformations – Fetch data from one API, transform it, and push the result to another
Report generation – Query your analytics API, CRM, or database and produce a formatted report
Multi-service orchestration – Coordinate actions across Slack, Linear, your deployment pipeline, and other internal services
Q&A over internal data – Give the agent tools to search your docs, wiki, or knowledge base and answer questions

The common thread: the agent uses tools to interact with external services instead of reading and writing files in a repo.

No GitHub required

One practical benefit: you don't need a GitHub App installation to use blank workspace mode. If you're building an internal tool or automation that doesn't touch code, you can get started with just an API key and your custom tools.

This also means teams that use GitLab, Bitbucket, or no version control at all can still use CodeCloud for tool-based workflows.

Combining with follow-ups

Blank workspace runs support follow-up messages just like regular runs. You can have a multi-turn conversation with the agent, passing different tools at each step.

# Step 1: Gather data
curl -X POST https://codecloud.dev/api/v1/agents \
  -H "Authorization: Bearer cc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "blank_workspace": true,
    "prompt": "Pull all customer support tickets from the last week tagged billing",
    "tools": [{ "name": "search_tickets", ... }]
  }'

# Step 2: Act on the results
curl -X POST https://codecloud.dev/api/v1/agents/run/{id}/resume \
  -H "Authorization: Bearer cc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Post a summary of those tickets to the #billing-ops Slack channel",
    "tools": [{ "name": "post_slack_message", ... }]
  }'

Each follow-up can include a fresh set of tools. The agent retains context from previous turns, so it can reference earlier results without you needing to pass them back in.

What gets ignored

When blank_workspace is true, the following fields are ignored:

repo – No repository is cloned
branch – No branch is checked out
auto_create_pr – Forced to false, no PR is created

Everything else works the same: providers, models, webhooks, follow-up messages, and the full run lifecycle.

Getting the output

Since there's no PR, you'll typically get results through one of two paths:

Polling the API – Check the run status and read the agent's messages from GET /api/v1/agents/run/{id}
Webhooks – Set a webhook_url and receive the result when the run completes

The agent's output lives in its messages, just like any other run. The only difference is there are no file changes or PRs to look at.

Blank workspace mode turns CodeCloud from a code-focused agent into a general-purpose one. If you're already using custom tools with a repo, try running the same tools without one. You might find that half your workflows don't need a codebase at all.

For full API details, see the documentation. Questions or feedback? Reach out at support@codecloud.dev.