Docs/Guides/Alchemist Platform

    Alchemist Local Development

    Last updated · MAR 2026·Read as Markdown

    Alchemist: Clone Your App's Code and Develop Locally

    Clone your Alchemist-built repository, work 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. 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 covers the Alchemist autonomous development platform at build.avcodex.com. For the Alchemist copilot inside the AVCodex agent builder, see The Alchemist Copilot.

    Only the tenant owner can mint credentials.

    1. Open your project at build.avcodex.com.
    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.

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

    code
    https://build.avcodex.com/alchemist-api/git/<projectId>.git

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

    bash
    git clone https://x:alchg_...@build.avcodex.com/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):

    code
    machine build.avcodex.com
  login x
  password alchg_...

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

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

    Then clone without inline credentials:

    bash
    git clone https://build.avcodex.com/alchemist-api/git/<projectId>.git my-app

    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.

    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.

    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.

    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. 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.

    *AVCodex · Your AV expertise. Amplified by AI.*

    Was this helpful?
    Edit this page →