# Software Factory: Clone Your App's Code and Develop Locally Clone your software factory 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 in the software factory 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 software factory 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 software factory 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 the **Deployment** tab → **Git access**. 3. Click **+ Mint 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/.git ``` The credential goes in the HTTP password field; the username can be anything. The dashboard's copy-paste command (the project's Developer tools page -> "Work locally") now does the safe thing by default: it stores the token via `git credential approve` scoped to the full clone URL, then clones with a clean URL so the token never lands in `.git/config` or `git remote -v`: ```bash printf 'protocol=https\nhost=build.chipp.ai\npath=alchemist-api/git/.git\nusername=x\npassword=alchg_...\n' | git credential approve \ && git clone -c credential.useHttpPath=true https://x@build.chipp.ai/alchemist-api/git/.git my-app ``` An alternative is `~/.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/.git username=x password=alchg_... " ``` Then clone without inline credentials: ```bash git clone https://build.chipp.ai/alchemist-api/git/.git my-app ``` > **Warning:** Working on more than one software factory 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 software factory pipeline, exactly like an agent merge, and shows up in the project's **Deployment** tab. 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. Three 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. - Pushes are capped at 100MB. This comfortably covers ordinary application-code changes; if you hit it, check for an accidentally-committed binary, dataset, or dependency directory rather than something that belongs in the repo. ## 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 software factory MCP server at `https://build.chipp.ai/alchemist-api/api/mcp`, authenticated with an `alch_` key read from the `ALCHEMIST_API_KEY` environment variable. A tenant owner or admin creates that key on the **API Keys** page in the software factory sidebar (see [API keys](/docs/guides/alchemist-api-keys)); export it with `export ALCHEMIST_API_KEY=alch_...` before you start your client. The `alchg_` git credential from step 1 is a different credential and does not work here. To use your personal Chipp login instead of a key, point the file at Chipp's unified MCP endpoint: ```json { "mcpServers": { "chipp": { "type": "http", "url": "https://build.chipp.ai/mcp" } } } ``` With the unified endpoint there is no key to export. The first tool call opens a browser window for a one-time OAuth approval, then your client holds the session. This works as long as your org is entitled (STUDIO_PRO, ENTERPRISE, or Chipp Executive) and has connected the software factory under **Settings → Alchemist Cloud**; see the [Software Factory Tickets MCP](/docs/guides/alchemist-mcp-server) guide if you would rather use a dedicated tenant-wide key instead of your personal login. Your agent then has these tools against your deployed app, alongside the rest of the software factory tool catalog: | 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 **Deployment** → **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 software factory tickets?** No. Your pushes and agent merges go through the same serialization and are deduplicated by commit, so the same change never deploys twice. **Can I fetch a ticket's own branch, not just `staging`?** Yes, the proxy reaches every branch. See [Rescuing a Stuck Ticket](/docs/guides/alchemist-stuck-ticket-recovery) for the full recovery workflow.