Skip to main content

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.
If no handler is detected, the pipeline completes after file sync and skips the code deploy step. You can still run prompts via Connect in this case — run npx agentmark dev --remote from your project to forward local execution through AgentMark Cloud.
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.

​
Build caching

When you push a commit whose import graph hasn’t changed since your last successful deployment, AgentMark Cloud skips the builder and marks the new deployment as deployed using the artifact already running. No setup needed — caching is automatic.

​
How it works

Each successful build emits a build manifest — the list of files that actually participated in the bundle. For TypeScript that’s the import graph from your handler (resolved by esbuild), plus the lockfile, package.json, tsconfig.json, and agentmark.json. For Python it’s the transitively-imported modules from your handler (resolved by Python’s modulefinder), plus requirements.txt / pyproject.toml / Pipfile.lock / etc. Each manifest entry records the file’s git blob SHA at the time of that build. On the next push, AgentMark Cloud fetches the recursive git tree at the new commit and compares each manifest entry’s recorded blob SHA to the file’s blob SHA at the new commit. If they all match, the cache hits — your code’s actual inputs haven’t changed, so the prior bundle is still correct. When the cache hits, the deployment record gets cache_hit = true and completes in under a second. The running production machine continues to serve.

​
When you’ll see cache hits

  • Prompt-, dataset-, or component-only pushes — the most common case. PMs editing .prompt.mdx / .mdx / .md / .jsonl files don’t appear in the import graph, so the manifest doesn’t include them, and changes don’t affect the cache.
  • Edits to source files your handler doesn’t import — e.g., one-off scripts, examples, internal tools, or dead code. If the file isn’t reachable from your entry point, it’s not in the manifest.
  • Retries of the same commit (a previous push errored mid-pipeline; you retry the same commit).
  • Re-deploys after rolling forward and back to the most recently deployed code state (older matching deployments don’t count — only the latest successful one).

​
When the cache misses

  • Any change to a file that’s part of your handler’s import graph (the entry point itself, anything it imports transitively).
  • Any change to your lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, Pipfile.lock, poetry.lock).
  • Any change to your package manifest (package.json, pyproject.toml, requirements.txt, etc.).
  • Any change to build configs (tsconfig.*, setup.py/setup.cfg).
  • Any change to agentmark.json / puzzlet.json.
  • A new lockfile or manifest appearing where there wasn’t one before.
  • A builder image upgrade (system-wide cache invalidation when AgentMark Cloud upgrades the build environment).
  • The first deploy of an app, or the first deploy after this feature shipped (no prior manifest to compare against).

​
Manual deploys always bypass the cache

The dashboard’s Full deploy and Rebuild buttons always run the builder, regardless of whether the manifest matches. A manual click is an explicit signal that you want a fresh build — typically to pick up new environment variables, recover from a transient failure, or rebuild against an updated builder image. The cache only applies to automatic deploys triggered by git push.

​
Commit-message overrides

You can override the cache decision by including a directive in your commit message:
DirectiveEffect
[force build]Always run the builder, even when the hash matches. Use to force a fresh build (e.g., to pick up a new base image).
[skip build]Skip the builder and reuse the most recent successful artifact. Use for documentation-only or other no-op pushes when you want a deployment record without a rebuild.
Both directives are case-insensitive and may appear anywhere in the commit message. If both appear, [force build] wins. 
# Forces a rebuild even if the hash matches the prior successful deploy.
git commit -m "fix: bump base image [force build]"

# Skips the build entirely and reuses the prior artifact.
git commit -m "docs: typo in README [skip build]"
[skip build] reuses the most recent successful artifact regardless of whether your code changed. That means any code differences in the current push will not run in production until your next normal deploy. Use it for genuine no-ops only — not as a way to ship code without testing the build.
If you push [skip build] to an app with no prior successful deployment, the deployment fails with a clear reason ([skip build] requested but no prior successful build to reuse) — there’s no artifact to fall back to. Push without the directive to trigger a normal first build.

​
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.
A small set of names are reserved and cannot be overridden: AGENTMARK_API_KEY, AGENTMARK_APP_ID, AGENTMARK_BASE_URL, AGENTMARK_DISPATCH_SECRET, and PORT. Any other name — including ones starting with AGENTMARK_ — can be used freely.
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.

​
Have Questions?

We’re here to help! Choose the best way to reach us: