Ephemeral Build

• An ephemeral build is a temporary agent version Guild creates automatically when you run guild agent test or guild agent chat from a local agent directory.
• Ephemeral builds never appear in your version history. They exist to make local iteration fast without polluting the version log with every save-and-test cycle.
• Guild caches ephemeral builds. If nothing changed since the last one, the same cached build is reused, so repeated tests are near-instant.
• Ephemeral builds include only files tracked by Git. Committed and staged files upload; untracked files are ignored until you git add them.

An ephemeral build is the mechanism Guild uses to let developers iterate on an agent locally without cluttering version history. When you run guild agent test or guild agent chat inside an agent directory, Guild packages your current working files, uploads them as a temporary agent version, and runs the session against that version. The build is not persisted in your version log; it exists only for the duration of the test session and gets recycled once it is no longer needed.

This is a deliberate contrast with guild agent save, which creates a versioned, persisted build every time. Save is for milestones. Ephemeral is for iteration. Keeping them separate is what lets developers experiment freely without turning their version log into a firehose.

Triggered by guild agent test and guild agent chat

Both commands, when run from a local agent directory, create an ephemeral build automatically. There is no separate flag to enable it. It is the default developer path for testing changes.

Cached by file content

Guild caches ephemeral builds by the exact set of files they contain. If you run guild agent test twice in a row without changing anything, the second run reuses the cached build from the first — no re-upload, no re-validate. The moment you edit a tracked file, the next run creates a fresh ephemeral build.

Only Git-tracked files upload

Ephemeral builds include only files Git knows about. Files that are committed or staged with git add are uploaded. New untracked files are ignored until you stage them. Modified tracked files still upload their working-tree contents, so you can test uncommitted changes to existing files without committing them first.

Do not appear in version history

Nothing an ephemeral build produces enters the agent's version list. guild agent versions shows only the versions you created explicitly with guild agent save. This is the whole point: the log is for milestones, not for every test.

Fast iteration requires cheap iteration

A version history that logs every save-and-test cycle stops being useful. Ephemeral builds separate the tight inner loop of "tweak, test, tweak, test" from the outer loop of "save this as a real version because it's a real change." That separation is what makes iteration fast.

Caching is what makes the pattern practical

If every test uploaded from scratch, iteration would be slower than saving. Because Guild caches ephemeral builds by content, repeated tests with no changes are essentially free, and small changes only pay for the delta. The developer feels a local dev loop while getting the guarantees of running against Guild's real runtime.

Git-tracked-only upload is a safety feature

If ephemeral builds uploaded every file in your working directory, they would ship .env files, editor swap files, and every accidental artifact. By respecting Git's tracked set, ephemeral builds inherit the same "what belongs in this repo" contract you have already declared through .gitignore and git add.

Test a local agent

guild agent test

Creates an ephemeral build from your working files and starts an interactive session against it. Ephemeral versions do not appear in guild agent versions.

Chat with an agent you're developing

guild agent chat

Same behavior as test: creates an ephemeral build from the current files, starts a chat session, does not persist a version. Repeat runs reuse the cached build if nothing changed.

Add a new file so it uploads

git add new-file.mdguild agent test

Staging with git add is what makes an untracked new file part of the next ephemeral build. Existing tracked files upload their working-tree contents whether or not they are committed.

When you're ready to persist a version

guild agent save --message "Add error handling"

That is the transition from ephemeral iteration to a real version. Save creates a versioned artifact that shows up in guild agent versions and is eligible to be published.

Ephemeral builds are not for CI

guild agent test is a developer command. For automation that needs a reproducible artifact, use guild agent save with a descriptive message so the version is persisted and can be referenced later.

The Git-tracked contract matters

If your agent depends on a file, that file must be tracked (or staged) or the ephemeral build will not include it. New helper files, generated artifacts you rely on, credentials you accidentally added — all of these behave according to Git's rules, not the filesystem's.

Cache invalidation is content-based

Guild's cache lookup is by the exact set of files and their contents. Rebooting your machine or moving to a different directory does not invalidate a cached ephemeral build if the same file set produces the same content hash.

Ephemeral builds respect the runtime, not the sandbox

Ephemeral builds run against Guild's real runtime. If your agent uses a service that requires credentials, and the credentials are not configured in the workspace, the ephemeral test will fail the same way a saved version would.

Guild is a control plane for AI agents, a place to build, deploy, and govern the agents your teams run in production. Ephemeral builds are what make the local development loop feel fast without giving up the guarantees of running against Guild's real runtime.

• The versions guide covers the full lifecycle from ephemeral test to published version.
• Agent version states covers the Saved / Validated / Published lifecycle ephemeral builds precede.
• Sign in at app.guild.ai to start iterating on your first agent.