runlayer_agent resource owns the agent’s configuration; the runlayer_agent data source reads back what Runlayer computed (model, generated description, counts).
What you need
- The provider set up as described in Terraform Provider, with a user API key. Organization API keys cannot create agents.
- A provider release that includes
runlayer_agent(check the provider changelog onterraform init). - Agents enabled for your workspace.
Example
A support-triage agent with a least-privilege connector, a prompt kept in a file, tags, an environment variable, and starter prompts. It starts disabled so nothing can trigger it before you have reviewed it in the app.prompts/support-triage.md:
apply, the agent appears in the app under Agents, owned by the user whose API key Terraform used. Open it there to run it, share it, add triggers, and watch sessions. Those runtime settings are not managed by Terraform.
What Terraform manages
Read-only in Terraform, managed in the app:
description (generated by Runlayer from the prompt), harness, and the usage limits run_limits_by_model, daily_cost_limit_usd, weekly_cost_limit_usd. The data source also exposes server_count, tool_count, skill_count, env_keys, skills, created_by, share_scope, and timestamps.
Provider 1.8.1 and later also return two read-only usage fields for the user whose API key Terraform uses: my_last_used_at, your latest run of the agent (null if you never ran it), and my_run_count, the runs you started in the last 30 days. They need backend 1.28.1543 or later.
servers, skill_ids, and env are request-only: Terraform sends them on create and update but does not read them back, because the API returns connectors in a different shape and never returns environment values. Edits made to those three in the app are not detected as drift. Use server_count, tool_count, skill_count, and env_keys from the data source for read-side checks.Catching changes made in the app
An agent you reviewed and applied from Terraform can still be edited in the app by anyone with edit access. Two checks catch those edits, including the connector, tool and skill changesterraform plan can’t see.
Pin the reviewed version. Every saved change to what the agent is and does creates a new version: prompt, model, network access policy, memory scopes, code mode, delegation, connectors with their tool lists, skills and environment variable names. Visibility switches (is_public, listed_in_workspace, is_disabled) and usage limits don’t. The data source returns the latest version as current_version. Record the version you reviewed and flag the plan when it moves (check blocks need Terraform 1.5 or later):
check reports a warning and doesn’t stop the apply; to block, make the same assertion a precondition on a resource that depends on the agent.
Alert on edits as they happen. Each edit writes an agent_updated audit log entry with the changed fields, their old values and the version it created. Stream these to your SIEM, or add an Audit event trigger for agent_updated to a reviewer agent. These entries also cover the visibility switches that don’t create versions. Fields worth watching: model, egress_policy, memory_scopes, enable_codemode, can_delegate, connectors and is_public.
These checks detect a change after it’s saved. They don’t block it. Runlayer doesn’t yet enforce an organization-wide baseline for agent configuration. What admins can restrict today: which roles may use each model (Settings → AI Providers, see LLM providers), which memory scopes agents may use (Settings → Memory), and what an agent’s connectors may do at run time, through policies. None of these are Terraform resources yet.
Importing an existing agent
/agents/<agent-id>). The first plan after an import shows a one-time in-place update that re-sends servers, skill_ids, and env from your configuration, for the reason above.
Deleting
terraform destroy deletes the agent and its linked agent account. Sessions, artifacts, and audit history follow the same retention as a deletion from the app.
Related docs
Terraform Provider
Provider setup, credentials, and the other resources
Agents
Everything an agent can do once it exists
Policies
Control what agents and users can do
Agent Accounts
Programmatic auth + delegated access model