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

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 are what connect the trigger surface (Slack, Linear) to Warp. An integration links the trigger to your Warp team 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.

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

Step 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.

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 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:

Detect the repositories you want the agent to work with and identify languages, frameworks, and tools
Look for an existing Dockerfile, recommend an official base image, or help build a custom image (if needed)
Suggest setup commands based on your scripts and package managers
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 or 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 and Linear articles.

Example environments

Project type Docker image Repos Example setup commands

Web dev project

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`

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

Step 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 a team API key (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 a team API key can clone repos and open pull requests using the GitHub App installation token.

For full setup instructions, see Team GitHub authorization.

Step 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.

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

oz integration create slack --environment <ENV_ID>
# or
oz integration create linear --environment <ENV_ID>

The CLI then:

Links the integration to your Warp team and environment.
Opens a browser flow to install the Oz app into your Slack workspace or Linear workspace.
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.

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:

Warp receives the trigger
Warp captures the message content (for example, a Slack thread or Linear issue), along with any linked context.
Warp creates an execution container
Warp spins up a fresh container from the Docker image defined in your environment.
Repositories are cloned
The GitHub repositories associated with the environment are cloned into the container.
Setup commands are run
Any setup commands you configured, like installing dependencies, are executed.
The agent workflow runs
The agent executes the task using the provided context, tools, and permissions.
Results are posted back
Progress updates, summaries, and results are posted back to Slack or Linear.
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
Oz Platform
Slack, Linear, and GitHub Actions integrations
Troubleshooting