> ## Documentation Index
> Fetch the complete documentation index at: https://help.plannotator.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Clone a Workspace with Git

> Clone and fetch a Workspaces repository with an API key, and understand the read-only Git limits.

Workspaces Git is read-only. You can clone, fetch, and pull a workspace with an
account and API key. Workspaces rejects `git push`.

The Git URL uses the instance's public API origin. Hosted Workspaces and the
default container setup use the app origin. A Cloudflare self-hosted deployment
uses its separate public API origin, not the Access-protected app origin.

## Before you clone

You need:

* Git installed on your computer.
* A [Workspaces API key](/workspaces/agents/api-keys).
* An API key whose owner can view the workspace.
* Your Workspaces public API origin and workspace ID.

A share link cannot authenticate Git. Every clone requires an account and API
key. Any valid key can clone a public or open workspace by ID. A private
workspace requires the owner's key. An organization-gated workspace requires
an owner or member key.

Git clone and fetch do not extend an anonymous workspace's 30-day expiry. Use
the share in the app or through an authenticated API or MCP request to record
activity. You can also claim the workspace before the date shown to remove the
expiry.

## Clone the workspace

The repository URL uses this form:

```text theme={null}
https://your-workspaces-host.example/git/<workspace-id>.git
```

Run:

```bash theme={null}
git clone https://your-workspaces-host.example/git/<workspace-id>.git
```

When Git asks for credentials:

* Enter any username, such as `workspaces`.
* Enter the Workspaces API key as the password.

After cloning, Git saves the repository URL. Your credential helper may also
save the API key. Check its settings before you use a shared computer.

## Fetch or pull changes

Run these read-only commands inside the clone:

```bash theme={null}
git fetch
git pull --ff-only
```

The clone uses the same file paths as Workspaces. Each Workspaces save point
appears in the Git history.

## Read-only limits

Workspaces provides the read-only `main` history and rejects `git push`. Make
changes in the browser or through the API or MCP, then fetch the new history.
Workspaces does not allow remote branch changes or other Git writes.

## Fix clone and fetch errors

| Result                                                     | Cause                                                                                          | Recovery                                                                                                         |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Authentication prompt repeats or returns `401`             | The password is not an active Workspaces API key.                                              | Create a new key and use it as the Git password.                                                                 |
| `No such workspace Git repository`                         | The workspace ID is wrong or the key owner cannot view it.                                     | Copy the correct workspace ID and confirm the account can open it.                                               |
| `No checkpointed Git repository exists for this workspace` | Workspaces has no saved Git repository for this workspace.                                     | Save a document change and retry. Ask the instance admin to check the Git store if the error continues.          |
| `500` with a backend failure                               | The container's Git process failed.                                                            | Retry once. If it fails again, ask the instance admin to check the Git service and logs.                         |
| `502` with a backend failure                               | The Cloudflare Git service could not find, authenticate with, or reach its repository backend. | Retry once. If it fails again, ask the instance admin to check the repository settings and Artifacts connection. |
| `503` with a busy or not-configured message                | The container reached its Git process limit, or the Cloudflare Git backend is not configured.  | Wait and retry a busy request. Ask the instance admin to check the Git configuration if the error continues.     |
| Push returns `405`                                         | Workspaces Git is read-only.                                                                   | Make the change through the browser, API, or MCP.                                                                |

*Reviewed July 22, 2026. Maintained by the Plannotator documentation team.*