> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/cli/iai_stacks_sync.md).

# iai stacks sync

Sync services, agents, databases, mcps, and jobs from a stack config file

## Synopsis

Sync services, agents, databases, mcps, and jobs in a project from a stack configuration file.

Services, agents, databases, mcps, and jobs are created and updated to match the config file. Resources the config file no longer mentions are NOT deleted by default: a config that omits a resource looks identical to a stale one, so the sync refuses each deletion, reports it on stderr, and continues with the creates and updates. Pass --allow-delete with the resource types you intend to decommission (services, agents, databases, mcps, jobs, or all) to delete them; within each resource type, deletes run after that type's creates and updates.

Resource types sync in order: services, databases, mcps, then agents once the self-hosted mcps are ready, and finally jobs. Remote mcps are registered on the platform.

Updates replace the whole live spec of each resource. For every service, agent, mcp, or job that changes, the live revision being replaced is printed to stderr so a sync from a stale config file is visible. Changing or deleting a job requires all its runs to finish.

Script jobs reference their files with scriptFile and pyprojectFile, resolved relative to the config file.

Use --dry-run to preview changes without applying anything.

The organization and project are read from the config file, flags, or resolved via 'iai organizations select' / 'iai projects select'.

```
iai stacks sync [flags]
```

## Examples

```
  iai stacks sync --file stack.yaml
  iai stacks sync --file stack.yaml --project my-project --organization my-org
  iai stacks sync --file stack.yaml --dry-run
  iai stacks sync --file stack.yaml --wait-timeout 10m
  iai stacks sync --file stack.yaml --allow-delete services,agents
```

## Example config file

```yaml
organization: my-org
project: my-project
stack-id: my-stack-v1

services:
  my-service:
    servicePort: 8080
    image:
      type: external
      repository: kennethreitz
      name: httpbin
      tag: latest
    resources:
      memory: "512M"
      cpu: "1"
    env:
      - name: DATABASE_URL
        value: "postgres://db:5432/mydb"
      - name: LOG_LEVEL
        value: "info"
    secretRefs:
      - secretName: my-secret
    endpoint: true
    replicas: 2
    healthcheck:
      path: /health
      initialDelaySeconds: 10
    schedule:
      uptime: "Mon-Fri 07:30-20:30"
      timezone: "Europe/Berlin"
```

> **Note:** `image.type` is `internal` (the project's registry) or `external` (`repository` required) for services and jobs; self-hosted mcps also accept `platform`, a self-hosted image from `iai mcps catalog` with no `repository`.

> **Note:** `replicas` and `autoscaling` are mutually exclusive for services. To use autoscaling instead:

```yaml
    autoscaling:
      minReplicas: 2
      maxReplicas: 10
      cpuPercentage: 80
      memoryPercentage: 85
```

> **Note:** a remote mcp takes exactly one of `catalogId` or `endpointUrl`, an `auth.type` of none, bearer, api\_key or custom, and none of the self-hosted keys; a catalog entry supplies its own endpoint and auth headers. Create oauth and client\_credentials mcps with `iai mcps create`; a stack never manages them.

```yaml
mcps:
  tools:
    type: self-hosted
    port: 8080
    image:
      type: internal
      name: my-mcp
      tag: v1
    resources:
      memory: "128M"
      cpu: "250m"
    auth:
      type: none
  docs:
    type: remote
    catalogId: awsknowledge
    auth:
      type: none
```

## Options

```
      --allow-delete strings    Resource types the sync may delete when the config omits them (services, agents, databases, mcps, jobs, or all); deletions are refused otherwise
      --dry-run                 Preview creates, updates, deletes, and refused deletions without applying; agent validation and update decisions are deferred when referenced mcps are changing
  -f, --file string             Path to stack configuration file
  -h, --help                    help for sync
      --no-wait                 Skip checking every self-hosted mcp is ready; this check also runs for unchanged mcps and stacks without agents
  -o, --organization string     Organization name that owns the project
  -p, --project string          Project name to sync resources in
      --wait-timeout duration   How long to wait for every self-hosted mcp in the config to be ready (tools verified), even without agents; a timeout stops the remaining sync phases (default 5m0s)
```

## Options inherited from parent commands

```
      --api-key string               API key for authentication
      --cfg-file string              Path to YAML config file with organization, project, and optional service definitions
      --deployment-hostname string   Hostname for the deployment API (default "https://deployment.interactive.ai")
      --hostname string              Hostname for the API (default "https://app.interactive.ai")
```

## SEE ALSO

* [iai stacks](https://docs.interactive.ai/cli/iai_stacks.md) - Declarative resource sync from config files


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.interactive.ai/cli/iai_stacks_sync.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
