How to Automate Fastio Workspaces with Terraform

Provisioning workspaces by hand works when you have two or three agents. It falls apart at ten. By the time you're managing dedicated environments for content writers, research agents, and code reviewers, the manual approach introduces drift, forgotten permissions, and inconsistent folder structures that break agent workflows.

Infrastructure as code solves this. Adidas cut their infrastructure provisioning time from weeks to minutes after adopting Terraform, and The Home Depot reported a 90% improvement in deployment speed. For AI agent workspaces, the gains are similar: you define the workspace configuration once, version-control it, and deploy identical environments on demand.

Fastio workspaces are more than file storage. When you enable Intelligence Mode, every uploaded file gets automatically indexed for semantic search and citation-backed AI chat. Agents and humans share the same workspace, with humans using the web interface and agents connecting through the Fastio MCP server or REST API. Managing these environments through Terraform means your team reviews workspace changes in pull requests, catches permission mistakes before deployment, and rolls back broken configurations with a single command.

The practical benefit is consistency. Every agent gets the same folder layout, the same permission boundaries, and the same Intelligence Mode settings. No one forgets to enable audit logging on the production workspace because the Terraform module handles it every time.

Fastio doesn't ship a dedicated Terraform provider, but you don't need one. The platform exposes a full REST API for workspace management, and Terraform's ecosystem includes providers that work with any HTTP API. The most practical option is the restapi provider, an open-source Terraform provider maintained by Mastercard that maps CRUD operations to REST endpoints.

Here's how the provider connects to the Fastio API:

terraform {
  required_providers {
    restapi = {
      source  = "Mastercard/restapi"
      version = "~> 1.19"
    }
  }
}

provider "restapi" {
  uri                  = "https://api.fast.io"
  write_returns_object = true

headers = {
    Authorization = "Bearer ${var.fastio_api_token}"
    Content-Type  = "application/json"
  }
}

The fastio_api_token variable should come from your secrets manager or CI/CD environment variables. Fastio supports API key authentication: human users generate keys from their account settings, and agents can authenticate programmatically through the auth endpoints. Never hardcode tokens in your .tf files. Use a variables.tf file with the sensitive flag:

variable "fastio_api_token" {
  type      = string
  sensitive = true
}

After configuring the provider, run terraform init to download the plugin. From here, every Fastio API endpoint becomes available as a restapi_object resource in your Terraform configuration.

With the provider configured, you can define workspaces as Terraform resources. The Fastio API expects an organization ID and a set of workspace parameters. Here's a resource definition that creates a workspace with Intelligence Mode disabled by default (to avoid unnecessary ingestion costs) and sets appropriate join permissions:

resource "restapi_object" "content_workspace" {
  path         = "/v1/orgs/${var.org_id}/workspaces"
  id_attribute = "profile_id"

data = jsonencode({
    name         = "Content Generation"
    folder_name  = "content-generation"
    intelligence = false
    perm_join    = "Admin or above"
  })
}

The id_attribute tells the provider which field in the API response contains the unique identifier. Fastio returns profile IDs as opaque strings, and Terraform stores these in its state file for subsequent updates and deletions.

Once the workspace exists, you can create folder structures that your agents expect. A content pipeline agent might need separate directories for source materials, drafts, and published output:

resource "restapi_object" "sources_folder" {
  path = "/v1/workspaces/${restapi_object.content_workspace.id}/folders"

data = jsonencode({
    name      = "Source Materials"
    parent_id = "root"
  })
}

resource "restapi_object" "drafts_folder" {
  path = "/v1/workspaces/${restapi_object.content_workspace.id}/folders"

data = jsonencode({
    name      = "Drafts"
    parent_id = "root"
  })
}

This guarantees the folder structure exists before the agent starts writing files. Without it, agents waste cycles creating directories at runtime or fail when they try to write to a path that doesn't exist yet.

For workspaces that need built-in RAG capabilities, enable Intelligence Mode at creation time. Remember that Intelligence incurs ingestion costs (10 credits per page), so only enable it on workspaces where agents need semantic search or AI chat. The free agent plan includes 5,000 monthly credits, which covers a reasonable volume of document indexing.

Provision Your First Agent Workspace in Minutes

Fastio gives every agent account 50 GB of free storage and 5,000 monthly credits, with no credit card required. Connect through the MCP server or REST API and start automating workspace provisioning today.

Sign Up Free

Giving every agent full access to every workspace is a common shortcut that creates real problems. An agent processing customer invoices shouldn't be able to read the HR workspace. Terraform lets you define granular permissions as code, so access controls go through the same review process as your application logic.

Fastio supports five workspace roles: owner, admin, member, guest, and view. For agent service accounts, the member role typically provides the right balance. It allows file operations without the ability to modify workspace settings or manage other members.

resource "restapi_object" "agent_membership" {
  path = "/v1/workspaces/${restapi_object.content_workspace.id}/members"

data = jsonencode({
    email_or_user_id = var.agent_user_id
    role             = "member"
  })
}

resource "restapi_object" "reviewer_membership" {
  path = "/v1/workspaces/${restapi_object.content_workspace.id}/members"

data = jsonencode({
    email_or_user_id = "reviewer@company.com"
    role             = "view"
  })
}

This separation keeps agent operations contained. The content agent writes files to the workspace while human reviewers can inspect output without accidentally modifying it.

For multi-agent systems, you can use Terraform modules to provision workspace-and-permission pairs. Define a module that takes an agent identity and a permission level, then call it once per agent:

module "research_agent_env" {
  source    = "./modules/agent-workspace"
  org_id    = var.org_id
  name      = "Research Pipeline"
  agent_id  = var.research_agent_id
  role      = "member"
  intel     = true
}

module "writer_agent_env" {
  source    = "./modules/agent-workspace"
  org_id    = var.org_id
  name      = "Content Writer"
  agent_id  = var.writer_agent_id
  role      = "member"
  intel     = false
}

Each module call produces an isolated workspace with the exact permissions that agent needs. Adding a new agent to your system means adding one module block and running terraform apply.

Fastio also supports ownership transfer, which pairs well with Terraform-managed workspaces. An agent can build a client deliverable workspace, populate it with files, and transfer ownership to a human stakeholder. The agent retains admin access for ongoing management while the client receives a fully configured environment. You can model this handoff as a separate Terraform step that updates the ownership configuration once the agent marks work as complete.

Running terraform apply from a developer's laptop works for prototyping. Production deployments should run through a CI/CD pipeline with remote state storage, plan reviews, and approval gates.

Store your Terraform state in a remote backend. This prevents two engineers (or two pipelines) from modifying the same workspace simultaneously. Most teams use an S3-compatible backend with state locking:

terraform {
  backend "s3" {
    bucket         = "company-terraform-state"
    key            = "fastio/workspaces.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-locks"
  }
}

With remote state in place, your CI/CD pipeline follows a standard flow: terraform plan generates a preview of changes, a team member reviews the plan, and terraform apply executes the approved changes. This review step catches mistakes like accidentally removing a workspace member or disabling Intelligence Mode on a production workspace.

A practical pipeline for GitHub Actions looks like this:

name: Deploy Fastio Workspaces
on:
  push:
    branches: [main]
    paths: ["terraform/fastio/**"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init
        working-directory: terraform/fastio
      - run: terraform plan -out=plan.tfplan
        working-directory: terraform/fastio
        env:
          TF_VAR_fastio_api_token: ${{ secrets.FASTIO_API_TOKEN }}
      - run: terraform apply plan.tfplan
        working-directory: terraform/fastio

The pipeline only triggers when files under terraform/fastio/ change, avoiding unnecessary runs. The API token lives in GitHub Secrets, never in the repository.

For teams managing many workspaces, consider structuring your Terraform code by environment. Keep a modules/ directory with reusable workspace definitions and separate environments/ directories for staging and production. This prevents a staging experiment from accidentally touching production agent workspaces.

Terraform is one option for automating Fastio workspaces, but it isn't the only one. Choosing the right tool depends on how your team already works and what level of control you need.

Direct API scripting. If you only need to provision a handful of workspaces, a Python or TypeScript script calling the Fastio API directly might be simpler than setting up Terraform state management. The Fastio MCP server exposes workspace, storage, and member operations that agents can call natively. For teams already building on the MCP protocol, scripting through MCP tools avoids the overhead of maintaining a separate IaC layer.

Pulumi. Teams that prefer writing infrastructure in TypeScript, Python, or Go can use Pulumi's dynamic providers to wrap the Fastio API. Pulumi manages state similarly to Terraform but lets you use general-purpose programming languages instead of HCL. This appeals to teams that want conditionals, loops, and type checking without HCL's declarative constraints.

Agent-driven provisioning. Fastio's API supports agent accounts that can create organizations, workspaces, and shares programmatically. An agent can sign up for a free account (50 GB storage, 5,000 monthly credits, no credit card required), create an organization, provision workspaces, and transfer ownership to a human when the work is done. This approach skips IaC tooling entirely and lets the agent manage its own infrastructure. It works well for project-based workflows where each client engagement gets a fresh workspace that the agent builds and hands off. See Fastio for agents for details on the free tier.

When Terraform wins. Terraform shines when you need repeatable, auditable deployments across many workspaces. If your team manages ten or more agent environments, runs workspace changes through code review, or needs to enforce consistent permission policies, Terraform's declarative model and state tracking pay for themselves quickly. The combination of version-controlled configurations and Fastio's built-in audit trails gives you visibility from both the infrastructure and application layers.