Skip to main content
Agents can be managed as code with the Runlayer Terraform provider. The 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 on terraform 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:
After 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 schedules or 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.
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.

Importing an existing agent

The agent id is the UUID in the app URL (/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.

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