Deployment

Documentation Index

Fetch the complete documentation index at: https://docs.agentmark.co/llms.txt

Use this file to discover all available pages before exploring further.

Deploy your AgentMark project by connecting a Git repository. On every push, AgentMark Cloud runs a deployment pipeline that syncs your files and deploys your handler code.

​

Deployment pipeline

Connect a Git repository to your app in the AgentMark Dashboard. When you push, the pipeline runs two steps: file sync and code deploy.

​

Setup

1. Push your project to a Git repository (GitHub or GitLab).
2. From your org’s Apps page, create an app (name-only — the Create App modal doesn’t connect a repo). Then open the app’s settings menu → Link repository to connect your Git repository.
3. Pick a branch to deploy from.

​

How the pipeline works

Every push to your connected branch triggers a two-step deployment:

1. File sync — AgentMark Cloud syncs your prompt templates (.prompt.mdx), components (.mdx, .md), and datasets (.jsonl) between your repository and the app.
2. Code deploy — If a handler file is detected, AgentMark Cloud bundles your code and deploys it to a managed machine. Your handler executes prompts when triggered from the Dashboard, API, or experiments.

A handler is the entry point for prompt execution in AgentMark Cloud. It receives prompt requests and runs them using your adapter and models. Projects scaffolded with npm create agentmark@latest include a handler file automatically. Each push creates its own deployment record; rapid consecutive pushes each run through the pipeline.

​

Handler detection

AgentMark Cloud resolves your handler file in this order:

1. handler key in agentmark.json — If your config includes a handler field, that path is used.
   agentmark.json

   {
     "version": "2.0.0",
     "agentmarkPath": ".",
     "handler": "src/handler.ts"
   }
   
   Use "src/handler.py" if your project is Python.
2. Fallback — If no handler key is set, AgentMark Cloud looks for handler.py first, then handler.ts at the repository root.

Both TypeScript and Python handlers are fully supported. Projects scaffolded with npm create agentmark@latest for cloud deployment drop the right entry point into the right language automatically (handler.ts for TypeScript projects, handler.py for Python). Local-only scaffolds skip the handler — add one before you deploy. If neither file is found, the code deploy step is skipped and the deployment completes after file sync only.

​

Re-triggering deployments

After your first successful deployment, you can re-trigger individual steps from the deployment card in the Dashboard:

• Re-sync — pull the latest files from your repository without rebuilding code. Use this when you only changed prompt templates or datasets.
• Rebuild — re-bundle and redeploy your handler code without re-syncing files. Use this when you need to pick up new environment variables.
• Full deploy — run both file sync and code deploy.

​

Environment variables

Configure environment variables for your deployed handler in the Dashboard under Settings → Environment variables. These variables are injected during the build step and available to your handler at runtime. Add your AI provider keys (such as OPENAI_API_KEY or ANTHROPIC_API_KEY) and any other secrets your handler needs. Changes to environment variables take effect on the next deployment — trigger a Rebuild to apply them immediately.

​

Connect: local execution via AgentMark Cloud

Connect lets you run prompts triggered from the Dashboard against your local process — useful when you want live iteration against in-development handler code, or when your handler depends on services/files that aren’t committed to the repo. Run npx agentmark dev --remote from your linked project. The CLI opens a WebSocket to AgentMark Cloud and forwards prompt-run requests to your local handler. Close the terminal and Connect goes offline; no bundled code runs in AgentMark Cloud.