> For the complete documentation index, see [llms.txt](/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Integration setup

Learn how to set up environments and integrations so you can trigger Oz agents from external tools.

This article describes the environment and integration setup that is required before you can trigger agents from external tools, like Slack or Linear. You will learn how to:

-   Create and configure the environment needed to run agents
-   Connect that environment to your team
-   Trigger agents using Slack or Linear

Note

**You only need to complete this setup once per Warp team**. After an integration exists, anyone on the team can use it. For example, the first time a teammate triggers an agent from Slack or Linear, they’ll be prompted to authorize GitHub with their own account in order for the agent to write back to repos.

Note: While cloud agents can be run individually via CLI without a team, integrations (Slack, Linear) require team membership.

Note

For a quickstart guide to Warp integrations, see the [Integrations overview](/agent-platform/cloud-agents/integrations/).

## How integrations and environments work

Warp integrations connect external tools, like Slack or Linear, to agents that run your code in the background.

There are three main components to know:

-   **Triggers** provide the context that tells Warp *what* to run. A trigger could be a Slack message where you tag @Oz, or a Linear issue or comment.
-   [**Integrations**](/agent-platform/cloud-agents/integrations/) are what connect the trigger surface (Slack, Linear) to Warp. An integration links the trigger to your [Warp team](/knowledge-and-collaboration/teams/) and handles posting results to the original tool, for example, replying in Slack.
-   **Environments** define how and where agents run your code. When an agent is triggered, Warp uses the environment to spin up a container, clone repositories, and execute the agent’s workflow.

```
Slack or Linear   (trigger)        →Warp Integration   (connects tools to Warp)        →Environment   (Docker image + repos + setup)        →Agent   (runs workflow, opens PRs, posts results)
```

Setting up an integration consists of three steps.

1.  **Create an environment** for the agent to run your code.
2.  **Authorize GitHub** so Warp can clone repositories, write code, debug issues, open pull requests, and more.
3.  **Configure** the Oz app with an integration.

Tip

If setup fails, use the returned error code to narrow the fix. Common errors include:

-   [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) (environment initialization issues)
-   [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or external-service authorization)
-   [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/) (incomplete integration setup)

* * *

## 1\. Creating an environment

Before you can trigger agents from Slack or Linear, you need an environment. The environment defines how and where Warp runs your code.

At a minimum, an environment includes:

-   A Docker image
-   One or more GitHub repositories
-   Optional setup commands

Typically, you’ll create **one environment per codebase** (or closely related set of repos) and reuse it across integrations.

You can create environments using a guided Agent flow, or directly through the CLI.

#### Before you begin

Make sure you have:

-   A GitHub repository (or repositories) that the agent can work in.
-   A publicly-accessible Docker image that can build and run your code. Official images like `node`, `python`, or `rust` work for many projects.

Note

You only need to create an environment once. It can be reused across Slack, Linear, and terminal triggers.

### Option 1: Guided environment setup (recommended)

The fastest way to get started is to use the guided environment setup. Use the `/create-environment` [slash command](/agent-platform/capabilities/slash-commands/) if you want Warp to analyze your repos and suggest an environment configuration.

You can run the command inside a Git repo directory with no argument, or with one or more repo paths or URLs. For example, from Warp:

```
# File paths/create-environment ./warp-internal ./warp-server
/create-environment warpdotdev/warp-internal warpdotdev/warp-server
# GitHub URLs/create-environment https://github.com/warpdotdev/warp-internal.git
```

The guided flow will:

1.  Detect the repositories you want the agent to work with and identify languages, frameworks, and tools
2.  Look for an existing Dockerfile, recommend an official base image, or help build a custom image (if needed)
3.  Suggest setup commands based on your scripts and package managers
4.  Create the environment through the CLI and return an environment ID

This produces a ready-to-use environment that can immediately be connected to [Slack](/agent-platform/cloud-agents/integrations/slack/) or [Linear](/agent-platform/cloud-agents/integrations/linear/).

### Option 2: Create an environment with the CLI

If you already know how you want to configure your environment, you can create it directly with the CLI.

**Use this approach when:**

-   You already have a custom Docker image
-   You want full control over repos and setup commands
-   You’re scripting or automating environment creation

From Warp:

```
oz environment create \  --name <name> \  --docker-image <image> \  --repo <owner/repo> \  --repo <owner/repo> \  --setup-command "<command1>" \  --setup-command "<command2>" \  --description "Optional description"
```

Key flags:

-   `--name` (`-n`) – human-readable label for the environment.
-   `--docker-image` (`-d`) – image name on Docker Hub. If not specified, you’ll be prompted to select from available images (see `oz environment image list`).
-   `--repo` (`-r`) – can be repeated for each repo.
-   `--setup-command` (`-c`) – can be repeated; commands run in the order provided.
-   `--description` – optional description (max 240 characters).

You can inspect existing environments with `oz environment list`.

To delete an environment, use `oz environment delete <ID>`. Add `--force` to skip confirmation checks for environments used by integrations.

For more details about environment configuration, see the [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/) articles.

#### Example environments

| Project type | Docker image | Repos | Example setup commands |
| --- | --- | --- | --- |
| Web dev project | `node:20-bullseye` | your-org/frontend-react  
  
your-org/backend-api | 
`npm install -g pnpm`

  
`cd frontend-react && pnpm install`

  
`cd backend-api && pnpm install`

 |
| Python project | Custom image based on `python:3.11` | your-org/cool\_python\_project | `cd cool_python_project && pip install -r requirements.txt` |

* * *

## 2\. Authorizing GitHub

Warp needs GitHub access so agents can clone your repositories and, when permitted, write code and open pull requests.

#### How GitHub authorization works

When you create an environment or integration, Warp will prompt you to:

-   Install or update the Warp GitHub app
-   Grant access to the repositories in your environment

This authorization enables agents to clone repositories into the environment, create branches and commits, and open pull requests.

**Public vs private repos**

-   **Public repos:** Agents can read code without authorization, but cannot write or open PRs.
-   **Private repos:** The Warp GitHub App must have access and the triggering user must have write permissions.

#### Ongoing permissions

Depending on how the GitHub app is installed in your organization:

-   You may need to grant access to new repositories over time
-   An organization admin may need to update the app’s permissions

You typically only need to handle this once per team, unless your repo access changes.

#### Team-level GitHub authorization

For automated workflows that use an [agent API key](/reference/cli/api-keys/) (CI/CD pipelines, scheduled agents, SDK-triggered runs), you can configure team GitHub authorization so the agent authenticates with the Oz by Warp GitHub App instead of an individual’s personal token.

This requires a Warp team admin to enable the GitHub organization in the Admin Panel (**Settings** > **Admin Panel** > **Platform**). Once configured, tasks initiated with an agent API key can clone repos and open pull requests using the GitHub App installation token.

For full setup instructions, see [Team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization).

Note

**Using API keys:** Personal API keys authenticate as you, so the agent runs with your GitHub permissions and code changes are attributed to your account. Agent API keys with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) configured use the GitHub App token instead.

* * *

## 3\. Setting up an integration

Once you have set up at least one environment, you can create integrations that connect it to Slack or Linear.

Note

For easier setup, use the [Oz web app](https://oz.warp.dev) to configure integrations with a guided flow.

Alternatively, use the CLI where `<ENV_ID>` is your environment ID:

```
oz integration create slack --environment <ENV_ID># oroz integration create linear --environment <ENV_ID>
```

Note

If you omit `--environment`, the CLI will show a list of environments and prompt you to choose one.

The CLI then:

1.  Links the integration to your Warp team and environment.
2.  Opens a browser flow to install the Oz app into your Slack workspace or Linear workspace.
3.  Generates an **integration ID** you can later list or delete.

**Additional `integration create` flags:**

-   `--prompt` — custom instructions applied to all runs for this integration.
-   `--mcp <SPEC>` — attach MCP servers (inline JSON, file path, or UUID). Can be repeated.
-   `--model <MODEL_ID>` — override the default model.
-   `--host <WORKER_ID>` — run on a specific self-hosted worker.
-   `--file <PATH>` (`-f`) — load configuration from a YAML or JSON file.

**Example with a custom prompt:**

```
oz integration create slack \  --environment <ENV_ID> \  --prompt "Always prefix PR titles with [WARP-AGENT] and add detailed test steps."
```

### Updating an integration

You can modify an existing integration using `oz integration update`:

```
oz integration update slack \  --environment <ENV_ID> \  --prompt "Updated instructions for the integration."
```

**Update-specific flags:**

-   `--environment <ID>` — change the environment.
-   `--remove-environment` — remove the environment from the integration.
-   `--prompt` — update the custom instructions.
-   `--mcp <SPEC>` — add MCP servers to the integration.
-   `--remove-mcp <SERVER_NAME>` — remove an MCP server by name.
-   `--model <MODEL_ID>` — update the default model.
-   `--host <WORKER_ID>` — update the execution host.

Note

For more details, see the dedicated pages for [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/) integrations.

## How are environments used at runtime?

When you trigger an agent from Slack or Linear, Warp follows a consistent, repeatable execution process using your environment.

At a high level, each run works like this:

1.  **Warp receives the trigger**  
    Warp captures the message content (for example, a Slack thread or Linear issue), along with any linked context.
2.  **Warp creates an execution container**  
    Warp spins up a fresh container from the Docker image defined in your environment.
3.  **Repositories are cloned**  
    The GitHub repositories associated with the environment are cloned into the container.
4.  **Setup commands are run**  
    Any setup commands you configured, like installing dependencies, are executed.
5.  **The agent workflow runs**  
    The agent executes the task using the provided context, tools, and permissions.
6.  **Results are posted back**  
    Progress updates, summaries, and results are posted back to Slack or Linear.
7.  **The container is destroyed**  
    After the run completes, the container is torn down. Each run starts from a clean, isolated environment.

## Next steps

You now have everything needed to trigger agents from your team’s tools. From here, you can:

-   Add or adjust setup commands
-   Switch to a custom Docker image
-   Include additional repositories
-   Add custom prompts for consistent agent behavior
-   Create separate environments for different workflows or teams

**Additional reading**

-   [Cloud Agents Overview](/agent-platform/cloud-agents/overview/)
-   [Oz Platform](/agent-platform/cloud-agents/platform/)
-   [Slack](/agent-platform/cloud-agents/integrations/slack/), [Linear](/agent-platform/cloud-agents/integrations/linear/), and [GitHub Actions](/agent-platform/cloud-agents/integrations/github-actions/) integrations
-   [Troubleshooting](/reference/cli/troubleshooting/)