Agents and Deployments

A deployment is the workspace-scoped runnable target that AgentClash can attach to a run.

Why a deployment exists at all

AgentClash is stricter than a typical playground because it has to compare like with like. A model name by itself is not enough. The scheduler needs a concrete object that says:

• which build is being run
• which build version is current
• which runtime policy applies
• which provider credentials and provider model are attached

That concrete object is the deployment.

The current creation contract

The current API schema for CreateAgentDeploymentRequest requires:

• name
• agent_build_id
• build_version_id
• runtime_profile_id

It also supports these optional fields:

• provider_account_id
• model
• deployment_config

The OpenAPI description also says only ready build versions can be deployed. A build version is "ready" once its status has moved from draft to ready (the other terminal status is archived); a draft or archived version cannot be attached to a deployment.

Runtime profiles are the execution envelope

A runtime profile defines how aggressive or constrained execution should be. In the current API and web types, a runtime profile carries fields like:

• execution_target
• trace_mode
• max_iterations
• max_tool_calls
• step_timeout_seconds
• run_timeout_seconds
• profile_config

That last field matters. The native executor reads runtime-profile sandbox overrides from profile_config, including things like filesystem roots and allow_shell or allow_network toggles.

The clean mental model is:

• the challenge pack defines what the workload wants
• the runtime profile defines execution ceilings and local overrides
• the deployment binds those choices to a runnable target

Provider accounts are how credentials enter the system

A provider account is a workspace resource with:

• provider_key
• name
• credential_reference
• optional limits_config

The important detail is how credentials are stored.

If you create a provider account with a raw api_key, the infrastructure manager stores that value as a workspace secret and rewrites the credential reference automatically to:

workspace-secret://PROVIDER_<PROVIDER_KEY>_API_KEY

So the product already prefers indirection over plaintext credentials on the resource itself.

Provider model IDs are explicit

Deployments now store the provider's model identifier directly. Use agentclash infra provider-account models <PROVIDER_ACCOUNT_ID> to discover models reachable with an account, then pass the selected ID as model. Deployment snapshots preserve that value for historical runs.

A deployment is where these pieces come together

A good way to think about the chain is:

• agent build version: what logic is being deployed
• runtime profile: how it is allowed to execute
• provider account: which credentials or spend limits back external model calls
• model: which provider model the deployment should use consistently
• deployment: the runnable handle used by runs

This is why the docs should not collapse deployment into “selected model.” The object is richer than that.

What the UI and CLI expose today

The current repo already exposes the resource model across multiple surfaces:

• CLI deployment create and deployment list
• workspace pages for runtime profiles, provider accounts, deployments, secrets, and tools
• run creation UI that asks for challenge pack and deployment selection separately

That separation is deliberate. A run is an execution event. A deployment is reusable infrastructure state.

What is stable versus still moving

The dependency chain and the API surface are stable: the fields documented above are the contract you build against today.

What is still moving is the editing experience and automation around these resources:

• how richly each resource can be edited in the UI
• how much automation exists for creating and wiring them together

Treat the resource model itself as real and rely on it, but expect the UX around editing deployments to keep improving.

See also

• Configure Runtime Resources
• Challenge Packs and Inputs
• Tools, Network, and Secrets
• CLI Reference
• Datasets overview
• Multi-turn packs
• Security evaluation