# Alchemist: Clone Your App's Code and Develop Locally

Clone your Alchemist-built repository, make changes in Claude Code or Cursor, push to deploy, and debug your live app with the built-in MCP tools.

---

Every app you build on the Alchemist platform lives in a real git repository. You own that code, and you can clone it down and work on it directly: fix a sticky issue by hand, explore the codebase in your editor, or run the whole app locally with Claude Code, Cursor, or any tooling you like. Pushing your changes deploys them through the same pipeline the Alchemist agents use.

You do not need a GitHub account for any of this. Access goes through a project-scoped credential that you mint and revoke yourself.

> **Note:** This guide is about the Alchemist autonomous development platform at build.chipp.ai. If you are looking for the Alchemist copilot inside the Chipp app builder, see the [Alchemist guide](/docs/guides/alchemist).

## 1. Mint a git credential

Only the tenant owner can mint credentials.

1. Open your project at build.chipp.ai.
2. Go to **Settings** → **Git access**.
3. Click **New credential**.
4. Copy the token (it starts with `alchg_`) immediately. It is shown exactly once; store it in a password manager or your git credential helper.

You can list active credentials (with creation and last-used dates) and revoke any of them from the same panel. Revocation takes effect on the very next request.

## 2. Clone your repository

The clone URL is shown on the Git access panel. It looks like:

```
https://build.chipp.ai/alchemist-api/git/<projectId>.git
```

The credential goes in the HTTP password field; the username can be anything. The quickest form (note the token lands in your shell history):

```bash
git clone https://x:alchg_...@build.chipp.ai/alchemist-api/git/<projectId>.git my-app
```

The cleaner way is to store the credential once and keep it out of URLs. With `~/.netrc` (file mode 600):

```
machine build.chipp.ai
  login x
  password alchg_...
```

Or with your git credential helper (for example the macOS Keychain):

```bash
git credential approve <<< "
url=https://build.chipp.ai/alchemist-api/git/<projectId>.git
username=x
password=alchg_...
"
```

Then clone without inline credentials:

```bash
git clone https://build.chipp.ai/alchemist-api/git/<projectId>.git my-app
```

> **Warning:** Working on more than one Alchemist project on the same machine? macOS Keychain (and most git credential helpers) store credentials by **host only**, not by path. Cloning a second project overwrites the first project's saved password for `build.chipp.ai`, and pushes to the first repo start failing with a 404 (a mismatched credential looks identical to "wrong project" by design, so the proxy never reveals which). Store each project's credential explicitly scoped to its full clone URL (`git credential approve` with the exact `url=` shown above, once per project) rather than relying on the helper to disambiguate by host.

## 3. Run the app locally

Your repository is a complete, runnable project. From the clone:

```bash
./scripts/setup.sh                       # first time: toolchain check, deps, local Postgres + Redis, migrations
./scripts/dev.sh --api-port 8000 --port 5173
```

The repo's `CLAUDE.md` documents the project's conventions, dev login flow, and test commands, so Claude Code and Cursor pick up the house rules automatically.

## 4. Push to deploy

Commit and push to the `staging` branch:

```bash
git add .
git commit -m "Fix the thing by hand"
git push origin staging
```

A push to `staging` deploys through the normal Alchemist pipeline, exactly like an agent merge, and shows up in the project's **Deployments** view. Pushes are coordinated with in-flight agent work: if the platform is mid-merge on your project, your push gets a clear "retry in a moment" message instead of racing it.

Two guardrails to know about:

- Changes under `.github/workflows/` are rejected at push time (the platform's repo credential deliberately cannot modify CI workflows).
- Force-pushing is refused. If your push is rejected because the remote has commits you do not have, run `git fetch origin staging && git merge origin/staging` and push again.

## 5. Debug the deployed app from your editor

Every repository ships with a `.mcp.json` that connects Claude Code (or any MCP client) to the Alchemist platform. Export your tenant API key before launching:

```bash
export ALCHEMIST_API_KEY=alch_...   # from your Alchemist dashboard; never commit it
```

Your agent then has these tools against your deployed app:

| Tool | What it does |
| --- | --- |
| `get_project_errors` | Error-level logs from your deployed app (5 minutes to 7 days back, with pattern filtering) |
| `get_project_logs` | Full log search: error, warn, and info levels |
| `query_database` | Read-only SQL against your app's production database (SELECT only, row-capped, time-limited) |
| `get_env_status` | Which required environment variables are configured on the deployment |
| `dispatch_ticket`, `list_tickets`, `get_ticket_reports` | Hand work back to the autonomous pipeline |

There are no production database credentials to configure, and you should never need any: `query_database` is the only path to production data, and it is read-only by construction.

A practical rhythm for hand-fixing an issue: reproduce it with `get_project_errors` or `get_project_logs`, inspect the data with `query_database`, fix and verify locally, then `git push origin staging` to ship it. Anything you would rather not do by hand, send back to the agents with `dispatch_ticket`.

## FAQ

**Do I need a GitHub account or seat?** No. The credential is issued by the platform and scoped to your project's repository only.

**Can my whole team use one credential?** Credentials are per-project, not per-person, so sharing works, but minting one credential per person means you can revoke one person's access without rotating everyone.

**What happens if I leak a token?** Revoke it in **Settings** → **Git access**. It stops working on the next request. Then mint a fresh one.

**Can I push branches other than `staging`?** Yes. Feature branches push fine and do not deploy; only pushes to the base branch trigger a deployment.

**Does pushing interfere with Alchemist tickets?** No. Your pushes and agent merges go through the same serialization and are deduplicated by commit, so the same change never deploys twice.