# Implementation
Source: https://docs.automa.app/bot-development/implementation

Learn how to implement a bot for Automa

You can write a bot in any language. All that's required is an HTTP server that can handle incoming webhook events from Automa.

## Starter kits

We provide starter kits to help you get started with building bots quickly:

| Language   | Template                                                   |
| ---------- | ---------------------------------------------------------- |
| TypeScript | [bot-typescript](https://github.com/automa/bot-typescript) |
| Python     | [bot-python](https://github.com/automa/bot-python)         |

These starter kits use our [Bot SDKs](/sdks/bot) and include basic implementations of the webhook and task-handling logic, allowing you to focus on your bot's specific functionality. They also include tests to ensure your bot works correctly with Automa.

## Receiving events

Your bot needs to expose an HTTP endpoint (for example, `/webhook`) to receive events from Automa. For security, you should also verify the webhook signature to ensure that the request is coming from Automa. You can read more about the available webhook events and how they are structured in the [Webhooks](/webhooks) reference guide.

The starter kits already handle this, and the endpoint they provide is `/automa`. They also require the `AUTOMA_WEBHOOK_SECRET` environment variable to verify the webhook signature.

## Handling tasks

When a task is created, your bot will receive a `task.created` event. You can then download the code from Automa and begin making changes. Once you are done, you can submit the changes back to Automa, which will create a pull request in the repository.

The starter kits contain the logic to do this using the `code.download` and `code.propose` methods from the [Bot SDKs](/sdks/bot).

### Changing code

After downloading the code, you can make changes to it based on the task requirements.

The starter kits include an empty `update` function that you can implement to modify the code. This function is called from the webhook handler with the downloaded code's location and the task data.

## Testing

The starter kits include a test suite for the webhook handler that you can run to ensure your bot works correctly with Automa. You can also write your own tests to cover specific functionality for the `update` function or other parts of your bot.

If you want to test your bot with real tasks, follow these steps:

<Steps>
  <Step title="Run the bot locally">
    Start the bot locally. This will start the HTTP server that listens for
    incoming requests.
  </Step>

  <Step title="Expose the bot with a tunneling service">
    Use a tunneling service like [ngrok](https://ngrok.com/) to expose your
    local bot to the internet. This will provide you with a public URL that
    Automa can use to send webhook events.
  </Step>

  <Step title="Update the webhook URL">
    Update the webhook URL for your bot in Automa to point to the public URL
    provided by the tunneling service.
  </Step>

  <Step title="Create tasks">
    Use either the Automa UI or connected integrations to create a task for the
    bot. Automa will send webhook events to your bot's endpoint, allowing you to
    test its functionality.
  </Step>
</Steps>


# Overview
Source: https://docs.automa.app/bot-development/index

Learn how to create and integrate custom bots with Automa

<Steps>
  <Step title="Register your bot">
    Register your bot with Automa by providing a name, description, and webhook
    URL. This step connects your bot to Automa, making it available for users to
    install.
  </Step>

  <Step title="Develop functionality">
    Implement the core logic of your bot to handle webhook events. This involves
    receiving tasks from Automa, processing them, and sending back the results.
  </Step>

  <Step title="Test locally">
    Thoroughly test your bot locally to ensure it functions correctly. For
    integration testing, expose your local development server to the internet
    using a tunneling service like [ngrok](https://ngrok.com/). This allows
    Automa to send webhook events to your bot for real-time testing.
  </Step>

  <Step title="Deploy to production">
    Deploy your bot to a cloud platform and update its webhook URL in Automa if
    needed.
  </Step>
</Steps>


# Registration
Source: https://docs.automa.app/bot-development/registration

Learn how to register a bot in Automa and configure it

You can register a new bot in Automa by going to [Settings > Bots > Create Bot](https://console.automa.app/\$/settings/bots/new).

<Steps>
  <Step title="Choose a name and description">
    Provide a unique name for your bot within your organization and a short
    description to help users understand its purpose.
  </Step>

  <Step title="Select a trigger type">
    Choose between [manual](/bots/types#manual) and
    [scheduled](/bots/types#scheduled) bot types. Manual bots run on demand,
    while scheduled bots run at specified intervals.
  </Step>

  <Step title="Enter the webhook URL">
    Provide the URL where Automa will send webhook events.
  </Step>

  <Step title="Create the bot">
    Click "Create" to complete the registration. Your bot will then be available
    for installation within your organization.
  </Step>

  <Step title="Save the webhook secret">
    After creation, copy the webhook secret. Your bot will use this secret to
    verify that incoming events are from Automa.
  </Step>
</Steps>

<video autoPlay muted loop playsInline className="mx-auto w-3/4 rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/bot-register.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=2bd4142d44d507db97e6e68c98800d70" data-path="videos/bot-register.mp4" />


# Overview
Source: https://docs.automa.app/bots/index

A bot in Automa is a remote coding tool that can work on coding tasks

A bot in Automa is a remote coding assistant designed to handle various coding tasks. Think of it as a specialized tool in your development workflow, running in the cloud and always available. Bots connect to Automa as external services via webhooks, meaning anyone can build and integrate their own custom bots.

## Bot vs Agent

While all agents are a type of bot, not all bots are agents. Here's the key difference:

* **Bots** are designed to follow a specific, predefined set of rules to perform a task.
* **Agents** possess a greater degree of autonomy. They can analyze code, understand context, and make decisions on how to best approach a task. This makes agents ideal for complex scenarios that require a deeper understanding of your codebase.

## Use cases

Bots can be used for a variety of tasks, including:

* *Writing boilerplate code* for new features or components.
* *Fixing minor bugs* that follow predictable patterns.
* *Updating dependencies* to the latest versions.
* *Changing page copy* to improve user experience.
* *Configuring tools* across multiple projects.
* *Renaming variables* to improve code readability.
* *Improving accessibility* to meet standards.
* *Adding observability* to monitor performance.
* *Tracking analytics* to understand user behavior.
* *Localizing content* for different languages.
* *Covering edge cases* by extending existing tests.
* *Migrating code* to new APIs or frameworks.


# Task lifecycle
Source: https://docs.automa.app/bots/task-lifecycle

The lifecycle of a bot task in Automa

In Automa, every bot task follows a structured lifecycle, from creation to completion. Understanding these stages is key to building reliable bots that integrate smoothly with your development workflow.

<br />

```mermaid  theme={null}
sequenceDiagram
  participant Automa
  participant Bot
  participant Code as Source code
  Note over Automa: Task created
  Automa->>Bot: Send "task.created" event
  activate Bot
  Bot->>Automa: Request access to code
  Automa->>Bot: Grant temporary code access
  Bot<<->>Code: Download code from repository
  Note over Bot: Implements task on code
  Bot->>Automa: Propose code changes with diff
  deactivate Bot
  Automa->>Code: Create pull request with diff
  Note over Code: Pull request merged
  Code->>Automa: Send pull request merged event
  Note over Automa: Mark task completed
  Automa->>Bot: Send "proposal.accepted" event
```

### Task created

When a task is assigned to a bot, Automa initiates the process by sending a webhook notification.

<Steps>
  <Step title="Send task created event">
    Automa sends a [`task.created`](/webhooks/task-created) event to the bot's webhook URL.
  </Step>

  <Step title="Request access to code">
    Since the access to source code is managed by Automa, the bot must request temporary access to download and view the code necessary to implement the task.
  </Step>

  <Step title="Send code access details">
    Automa verifies the bot's authorization and provides a short-lived, permission-scoped URL. This allows the bot to securely download the code required for the task.
  </Step>

  <Step title="Download code">
    The bot uses the provided URL to download the code and prepare for implementation.

    For the above 3 steps, you can use the `code.download` method from the [Bot SDK](/sdks/bot).
  </Step>
</Steps>

### Task implemented

Once the bot has the code, it can begin its work. After completing the task, it proposes the changes back to Automa.

<Steps>
  <Step title="Propose code changes">
    The bot sends the completed work back to Automa as a **diff**, along with a title and description for the pull request.

    You can use the `code.propose` method from the [Bot SDK](/sdks/bot) for this step.
  </Step>

  <Step title="Create pull request">
    Automa creates a pull request in the source code repository, making the changes available for review.
  </Step>
</Steps>

### Pull request merged

Once the pull request is merged, the task is considered complete.

<Steps>
  <Step title="Pull request merged event">
    The source code host sends a pull request merged event to Automa.
  </Step>

  <Step title="Mark task completed">
    Automa updates the task's status to "completed" in its system.
  </Step>

  <Step title="Send proposal accepted event">
    Automa sends a [`proposal.accepted`](/webhooks/proposal-accepted) event to
    the bot's webhook URL, confirming that the proposed changes have been
    successfully merged.
  </Step>
</Steps>


# Types
Source: https://docs.automa.app/bots/types

Learn about the different types of bots in Automa.

Bots in Automa are categorized along two dimensions: how they are triggered and how they execute tasks. Understanding these helps you choose or build the right bot for your needs.

## Trigger

This dimension defines how a task is initiated and assigned to a bot.

### Manual

Manual bots are triggered by direct user action, either through the Automa UI or via integrations. They are perfect for on-demand tasks where you need full control over when the bot runs.

### Scheduled

Scheduled bots operate on a fixed, recurring schedule. Automa automatically creates and assigns tasks to them at set intervals, making them ideal for routine maintenance and other recurring automations.

<Warning>
  Right now, scheduled bots run once a week on Monday at 00:00 UTC. We're
  working to add more scheduling options soon!
</Warning>

## Logic

This dimension defines how a bot processes tasks and makes decisions.

### Deterministic

Deterministic bots operate based on a predefined set of rules. They deliver consistent, predictable outcomes, making them ideal for repeatable tasks like scaffolding, code generation, or simple refactoring.

### AI

AI bots use machine learning models (like LLMs) to analyze context and generate solutions dynamically. They excel at open-ended tasks like implementing features, writing unit tests, or drafting documentation.


# Ideal workflow
Source: https://docs.automa.app/ideal-workflow

Currently recommended workflow for developers leveraging AI tools.

The software development process has been in a constant state of flux with the rise of LLMs and AI tools. Please find below the current ideal workflow which we will try our best to keep up to date.

<img className="block dark:hidden" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_light.png?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=6f57067090fe8b18fcb944981b82428d" alt="Ideal workflow" noZoom data-og-width="2360" width="2360" data-og-height="2812" height="2812" data-path="images/workflow_light.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_light.png?w=280&fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=c08d1b489dc0e29d85d1ca043636c473 280w, https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_light.png?w=560&fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=b3bf346f62263454a7107293024aa0a2 560w, https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_light.png?w=840&fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=e8a7738b0659abd457577b6e18e92ad5 840w, https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_light.png?w=1100&fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=88ddea0bb96b512885aacd3f88e4951b 1100w, https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_light.png?w=1650&fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=37f04e482b919a25bf14d862a348cb04 1650w, https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_light.png?w=2500&fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=fe34b4441029452ede0bb646c198a7a6 2500w" />

<img className="hidden dark:block" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_dark.png?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=63da73d183d1edb72bdd16161ce4609a" alt="Ideal workflow" noZoom data-og-width="2356" width="2356" data-og-height="2808" height="2808" data-path="images/workflow_dark.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_dark.png?w=280&fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=2d2aa67a7dc0dd8e531aa258f6c898d9 280w, https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_dark.png?w=560&fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=7743b4e32eeea7b9284ebffa9e29b7dd 560w, https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_dark.png?w=840&fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=55de7dae179adb6bf23fe8809324971f 840w, https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_dark.png?w=1100&fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=eb0d0e8933251aaaf420d997867d549e 1100w, https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_dark.png?w=1650&fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=468019b8b59a0d62c834204a5b98106b 1650w, https://mintcdn.com/automa/eeL4keyWWsKr0LQB/images/workflow_dark.png?w=2500&fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=9139937403619c2549330b860867e1e4 2500w" />


# Overview
Source: https://docs.automa.app/index

Automa is a platform where people can run cloud coding agents from the tools they already use

<Columns cols={2}>
  <Card arrow title="Bots" icon="bot" href="/bots">
    Learn about bots in Automa and how they are used to automate coding tasks
  </Card>

  <Card arrow title="Bot Development" icon="code" href="/bot-development">
    Learn how to create custom coding bots & agents for Automa
  </Card>

  <Card arrow title="Self Hosting" icon="server" href="/self-hosting">
    Discover how to self-host Automa on your own infrastructure
  </Card>

  <Card arrow title="Platform" icon="app-window-mac" href="/platform">
    Explore the Automa platform and its features
  </Card>
</Columns>


# Overview
Source: https://docs.automa.app/platform/index



## Integrations

We support the following integrations in our platform with more coming soon:

<Columns cols={2}>
  <Card arrow title="GitHub" href="/platform/integrations/github">
    Connect your GitHub account to provide access to your code repositories and
    create tasks from issues and pull requests.
  </Card>

  <Card arrow title="Linear" href="/platform/integrations/linear">
    Connect your Linear account to create tasks from issues.
  </Card>

  <Card arrow title="Jira" href="/platform/integrations/jira">
    Connect your Jira account to create tasks from issues.
  </Card>
</Columns>


# GitHub
Source: https://docs.automa.app/platform/integrations/github



<video autoPlay muted loop playsInline className="mx-auto w-3/4 rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/platform/connect-github.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=abd6f31224fa588a728f7dc6e22894c9" data-path="videos/platform/connect-github.mp4" />


# Jira
Source: https://docs.automa.app/platform/integrations/jira



<video autoPlay muted loop playsInline className="mx-auto w-3/4 rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/platform/connect-jira.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=f053075954a357765b81ae1fe31a2b0d" data-path="videos/platform/connect-jira.mp4" />


# Linear
Source: https://docs.automa.app/platform/integrations/linear



<video autoPlay muted loop playsInline className="mx-auto w-3/4 rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/platform/connect-linear.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=7e07815a3c6f52ece407cfb4240cec25" data-path="videos/platform/connect-linear.mp4" />


# Bot
Source: https://docs.automa.app/sdks/bot

A list of SDKs for building bots with Automa

Automa provides SDKs to [implement a bot](/bot-development/implementation) that can interact with the platform. Please refer to the documentation for each SDK to learn how to use them effectively.

| Language   | Registry |    Package    | Documentation                                                               |
| ---------- | :------: | :-----------: | --------------------------------------------------------------------------- |
| TypeScript |    NPM   | `@automa/bot` | [GitHub](https://github.com/automa/sdk-typescript/tree/master/packages/bot) |
| Python     |   PyPI   |  `automa-bot` | [GitHub](https://github.com/automa/sdk-python/tree/master/packages/bot)     |


# Claude Code
Source: https://docs.automa.app/self-hosting/agents/claude-code

A step-by-step guide to setup Claude Code agent for Automa

export const title_0 = "Claude Code"

Claude Code agent for Automa is based on [Anthropic's Claude Code](https://anthropic.com/claude-code) CLI tool. It's source code is available on [GitHub](https://github.com/automa/claude-code).

It contains the following components:

* **Cache**: A key-value store for jobs & caching.
* **Agent**: The agent that responds to Automa and implements tasks.

## Automa bot

You would need to [register a bot](/bot-development/registration) of [manual](/bots/types#manual) type in Automa (Cloud or Self-hosted) and configure it's webhook URL to point to the **Agent** service. The webhook URL will be `http://<your-server>/hooks/automa` if you are running it on a server with either a public IP address or domain name. Make sure to copy the **Webhook Secret** from Automa.

<Note>
  If you are running the agent on your local machine, you'll need to expose your
  local **Agent** service to the public internet so that Automa's webhooks can
  reach it. A tool like [ngrok](https://ngrok.com/) can create a secure tunnel
  to your `localhost`. You would then set the public URL provided by the tool as
  the webhook URL for the agent in Automa.
</Note>

## Docker

Automa publishes official [Docker](https://www.docker.com) images for the {title_0} agent which can be run on any system with Docker installed. This section will help you set it up using Docker.

### Setting up

You can set all this up locally on your machine or on a server.

There are 2 steps in the setup process:

* Start the needed services.
* Check if the services are working.

You will need:

* **Docker**: to run the cache, and Claude Code agent container.
* **Docker network**: containers must share a user-defined network (e.g. `automa-claude-code`).
* **Anthropic API Key**: to use Anthropic's models.

#### Cache

We use [Redis](https://redis.io/) for the key-value store. The Redis container will store its data in a Docker volume named `automa-claude-code-redis-data`. It listens on port 6379. Make sure to replace `<cache-password>` with a secure password of your choice.

```bash icon="terminal" theme={null}
docker run -d --name automa-claude-code-redis \
  --network automa-claude-code \
  -e REDIS_PASSWORD=<cache-password> \
  -v automa-claude-code-redis-data:/data \
  -p 6379:6379 \
  redis:7-alpine
```

<Tip>
  If you are self-hosting Automa, you can use the **Cache** service from it
  instead of setting up a separate cache. Just make sure the Claude Code agent
  is on the same network as your Automa services.
</Tip>

#### Agent

We use the latest [Automa Claude Code agent image](https://ghcr.io/automa/claude-code). The Agent will connect to the Redis container. It listens on port 8000. Make sure to replace `<anthropic-api-key>` with your Anthropic API key, `<webhook-secret>` with the webhook secret you copied from Automa earlier and `<cache-password>` with the password you set earlier.

```bash icon="terminal" theme={null}
docker run -d --name automa-claude-code \
  --network automa-claude-code \
  -e ANTHROPIC_API_KEY=<anthropic-api-key> \
  -e AUTOMA_WEBHOOK_SECRET=<webhook-secret> \
  -e REDIS_URL=redis://:<cache-password>@localhost:6379 \
  -p 8000:8000 \
  ghcr.io/automa/claude-code
```

#### Check the setup

You can check if the containers are running with the following command:

```bash icon="terminal" theme={null}
docker ps
```

### Updating

We recommend updating periodically to ensure you have the latest features and security updates. To update your services:

```bash icon="terminal" theme={null}
docker pull ghcr.io/automa/claude-code
docker restart automa-claude-code
```

## Railway

Automa publishes official [Railway](https://railway.com) templates for the Claude Code agent. This section will help you set it up using Railway.

### Setting up

There are 2 steps in the setup process:

* Start the needed services.
* Check if the services are working.

#### Start services

You will need an account on [Railway](https://railway.com) to get started. Once you have an account, go to the [Automa Claude Code agent template](https://railway.com/deploy/UQSi48?referralCode=Ri3kTG) and deploy it by clicking on the "**Deploy Now**" button.

You would need to provide the following environment variables for the **Agent** service:

* `ANTHROPIC_API_KEY`: Your Anthropic API key.
* `AUTOMA_WEBHOOK_SECRET`: The webhook secret you copied from Automa earlier.

<video autoPlay muted loop playsInline className="mx-auto rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/railway-agent-deploy.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=a8ed8dc101ccdf5a0dbf0079bd4f4862" data-path="videos/self-hosting/railway-agent-deploy.mp4" />

#### Check the setup

If you have successfully deployed the template, you should see 2 healthy services in your Railway project: **Agent** and **Redis**.

The **Agent** service in the Railway project should have been automatically assigned a domain name by Railway in the form of `<random>.up.railway.app`. You can find this by clicking on the service. Make sure to update the webhook URL of the agent in Automa to match this domain.

<video autoPlay muted loop playsInline className="mx-auto w-3/4 rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/railway-agent-domain.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=567c528aa19e929bfe293b36e9ee47b3" data-path="videos/self-hosting/railway-agent-domain.mp4" />

### Updating

We recommend updating periodically to ensure you have the latest features and security updates. To update your **Agent** service, go to the service in your Railway project, click on the "**Deployments**" tab, click on **three dots** on active deployment, and then choose the "**Redeploy**" option. This will pull the latest changes and redeploy your service.

<video autoPlay muted loop playsInline className="mx-auto rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/railway-agent-redeploy.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=54b4c8259a11ec0077856f06670ada96" data-path="videos/self-hosting/railway-agent-redeploy.mp4" />


# Codex
Source: https://docs.automa.app/self-hosting/agents/codex

A step-by-step guide to setup Codex agent for Automa

export const title_0 = "Codex"

Codex agent for Automa is based on [OpenAI's Codex](https://github.com/openai/codex) CLI tool. It's source code is available on [GitHub](https://github.com/automa/codex).

It contains the following components:

* **Cache**: A key-value store for jobs & caching.
* **Agent**: The agent that responds to Automa and implements tasks.

## Automa bot

You would need to [register a bot](/bot-development/registration) of [manual](/bots/types#manual) type in Automa (Cloud or Self-hosted) and configure it's webhook URL to point to the **Agent** service. The webhook URL will be `http://<your-server>/hooks/automa` if you are running it on a server with either a public IP address or domain name. Make sure to copy the **Webhook Secret** from Automa.

<Note>
  If you are running the agent on your local machine, you'll need to expose your
  local **Agent** service to the public internet so that Automa's webhooks can
  reach it. A tool like [ngrok](https://ngrok.com/) can create a secure tunnel
  to your `localhost`. You would then set the public URL provided by the tool as
  the webhook URL for the agent in Automa.
</Note>

## Docker

Automa publishes official [Docker](https://www.docker.com) images for the {title_0} agent which can be run on any system with Docker installed. This section will help you set it up using Docker.

### Setting up

You can set all this up locally on your machine or on a server.

There are 2 steps in the setup process:

* Start the needed services.
* Check if the services are working.

You will need:

* **Docker**: to run the cache, and Codex agent container.
* **Docker network**: containers must share a user-defined network (e.g. `automa-codex`).
* **OpenAI API Key**: to use OpenAI's models.

#### Cache

We use [Redis](https://redis.io/) for the key-value store. The Redis container will store its data in a Docker volume named `automa-codex-redis-data`. It listens on port 6379. Make sure to replace `<cache-password>` with a secure password of your choice.

```bash icon="terminal" theme={null}
docker run -d --name automa-codex-redis \
  --network automa-codex \
  -e REDIS_PASSWORD=<cache-password> \
  -v automa-codex-redis-data:/data \
  -p 6379:6379 \
  redis:7-alpine
```

<Tip>
  If you are self-hosting Automa, you can use the **Cache** service from it
  instead of setting up a separate cache. Just make sure the Codex agent is on
  the same network as your Automa services.
</Tip>

#### Agent

We use the latest [Automa Codex agent image](https://ghcr.io/automa/codex). The Agent will connect to the Redis container. It listens on port 8000. Make sure to replace `<openai-api-key>` with your OpenAI API key, `<webhook-secret>` with the webhook secret you copied from Automa earlier and `<cache-password>` with the password you set earlier.

```bash icon="terminal" theme={null}
docker run -d --name automa-codex \
  --network automa-codex \
  -e OPENAI_API_KEY=<openai-api-key> \
  -e AUTOMA_WEBHOOK_SECRET=<webhook-secret> \
  -e REDIS_URL=redis://:<cache-password>@localhost:6379 \
  -p 8000:8000 \
  ghcr.io/automa/codex
```

#### Check the setup

You can check if the containers are running with the following command:

```bash icon="terminal" theme={null}
docker ps
```

### Updating

We recommend updating periodically to ensure you have the latest features and security updates. To update your services:

```bash icon="terminal" theme={null}
docker pull ghcr.io/automa/codex
docker restart automa-codex
```

## Railway

Automa publishes official [Railway](https://railway.com) templates for the Codex agent. This section will help you set it up using Railway.

### Setting up

There are 2 steps in the setup process:

* Start the needed services.
* Check if the services are working.

#### Start services

You will need an account on [Railway](https://railway.com) to get started. Once you have an account, go to the [Automa Codex agent template](https://railway.com/deploy/htbpnU?referralCode=Ri3kTG) and deploy it by clicking on the "**Deploy Now**" button.

You would need to provide the following environment variables for the **Agent** service:

* `OPENAI_API_KEY`: Your OpenAI API key.
* `AUTOMA_WEBHOOK_SECRET`: The webhook secret you copied from Automa earlier.

<video autoPlay muted loop playsInline className="mx-auto rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/railway-agent-deploy.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=a8ed8dc101ccdf5a0dbf0079bd4f4862" data-path="videos/self-hosting/railway-agent-deploy.mp4" />

#### Check the setup

If you have successfully deployed the template, you should see 2 healthy services in your Railway project: **Agent** and **Redis**.

The **Agent** service in the Railway project should have been automatically assigned a domain name by Railway in the form of `<random>.up.railway.app`. You can find this by clicking on the service. Make sure to update the webhook URL of the agent in Automa to match this domain.

<video autoPlay muted loop playsInline className="mx-auto w-3/4 rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/railway-agent-domain.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=567c528aa19e929bfe293b36e9ee47b3" data-path="videos/self-hosting/railway-agent-domain.mp4" />

### Updating

We recommend updating periodically to ensure you have the latest features and security updates. To update your **Agent** service, go to the service in your Railway project, click on the "**Deployments**" tab, click on **three dots** on active deployment, and then choose the "**Redeploy**" option. This will pull the latest changes and redeploy your service.

<video autoPlay muted loop playsInline className="mx-auto rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/railway-agent-redeploy.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=54b4c8259a11ec0077856f06670ada96" data-path="videos/self-hosting/railway-agent-redeploy.mp4" />


# Gemini
Source: https://docs.automa.app/self-hosting/agents/gemini

A step-by-step guide to setup Gemini agent for Automa

export const title_0 = "Gemini"

Gemini agent for Automa is based on [Google's Gemini](https://github.com/google-gemini/gemini-cli) CLI tool. It's source code is available on [GitHub](https://github.com/automa/gemini).

It contains the following components:

* **Cache**: A key-value store for jobs & caching.
* **Agent**: The agent that responds to Automa and implements tasks.

## Automa bot

You would need to [register a bot](/bot-development/registration) of [manual](/bots/types#manual) type in Automa (Cloud or Self-hosted) and configure it's webhook URL to point to the **Agent** service. The webhook URL will be `http://<your-server>/hooks/automa` if you are running it on a server with either a public IP address or domain name. Make sure to copy the **Webhook Secret** from Automa.

<Note>
  If you are running the agent on your local machine, you'll need to expose your
  local **Agent** service to the public internet so that Automa's webhooks can
  reach it. A tool like [ngrok](https://ngrok.com/) can create a secure tunnel
  to your `localhost`. You would then set the public URL provided by the tool as
  the webhook URL for the agent in Automa.
</Note>

## Docker

Automa publishes official [Docker](https://www.docker.com) images for the {title_0} agent which can be run on any system with Docker installed. This section will help you set it up using Docker.

### Setting up

You can set all this up locally on your machine or on a server.

There are 2 steps in the setup process:

* Start the needed services.
* Check if the services are working.

You will need:

* **Docker**: to run the cache, and Gemini agent container.
* **Docker network**: containers must share a user-defined network (e.g. `automa-gemini`).
* **Gemini API Key**: to use Google's Gemini models.

#### Cache

We use [Redis](https://redis.io/) for the key-value store. The Redis container will store its data in a Docker volume named `automa-gemini-redis-data`. It listens on port 6379. Make sure to replace `<cache-password>` with a secure password of your choice.

```bash icon="terminal" theme={null}
docker run -d --name automa-gemini-redis \
  --network automa-gemini \
  -e REDIS_PASSWORD=<cache-password> \
  -v automa-gemini-redis-data:/data \
  -p 6379:6379 \
  redis:7-alpine
```

<Tip>
  If you are self-hosting Automa, you can use the **Cache** service from it
  instead of setting up a separate cache. Just make sure the Gemini agent is on
  the same network as your Automa services.
</Tip>

#### Agent

We use the latest [Automa Gemini agent image](https://ghcr.io/automa/gemini). The Agent will connect to the Redis container. It listens on port 8000. Make sure to replace `<gemini-api-key>` with your Gemini API key, `<webhook-secret>` with the webhook secret you copied from Automa earlier and `<cache-password>` with the password you set earlier.

```bash icon="terminal" theme={null}
docker run -d --name automa-gemini \
  --network automa-gemini \
  -e GEMINI_API_KEY=<gemini-api-key> \
  -e AUTOMA_WEBHOOK_SECRET=<webhook-secret> \
  -e REDIS_URL=redis://:<cache-password>@localhost:6379 \
  -p 8000:8000 \
  ghcr.io/automa/gemini
```

#### Check the setup

You can check if the containers are running with the following command:

```bash icon="terminal" theme={null}
docker ps
```

### Updating

We recommend updating periodically to ensure you have the latest features and security updates. To update your services:

```bash icon="terminal" theme={null}
docker pull ghcr.io/automa/gemini
docker restart automa-gemini
```

## Railway

Automa publishes official [Railway](https://railway.com) templates for the Gemini agent. This section will help you set it up using Railway.

### Setting up

There are 2 steps in the setup process:

* Start the needed services.
* Check if the services are working.

#### Start services

You will need an account on [Railway](https://railway.com) to get started. Once you have an account, go to the [Automa Gemini agent template](https://railway.com/deploy/kQnZs_?referralCode=Ri3kTG) and deploy it by clicking on the "**Deploy Now**" button.

You would need to provide the following environment variables for the **Agent** service:

* `GEMINI_API_KEY`: Your Gemini API key.
* `AUTOMA_WEBHOOK_SECRET`: The webhook secret you copied from Automa earlier.

<video autoPlay muted loop playsInline className="mx-auto rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/railway-agent-deploy.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=a8ed8dc101ccdf5a0dbf0079bd4f4862" data-path="videos/self-hosting/railway-agent-deploy.mp4" />

#### Check the setup

If you have successfully deployed the template, you should see 2 healthy services in your Railway project: **Agent** and **Redis**.

The **Agent** service in the Railway project should have been automatically assigned a domain name by Railway in the form of `<random>.up.railway.app`. You can find this by clicking on the service. Make sure to update the webhook URL of the agent in Automa to match this domain.

<video autoPlay muted loop playsInline className="mx-auto w-3/4 rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/railway-agent-domain.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=567c528aa19e929bfe293b36e9ee47b3" data-path="videos/self-hosting/railway-agent-domain.mp4" />

### Updating

We recommend updating periodically to ensure you have the latest features and security updates. To update your **Agent** service, go to the service in your Railway project, click on the "**Deployments**" tab, click on **three dots** on active deployment, and then choose the "**Redeploy**" option. This will pull the latest changes and redeploy your service.

<video autoPlay muted loop playsInline className="mx-auto rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/railway-agent-redeploy.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=54b4c8259a11ec0077856f06670ada96" data-path="videos/self-hosting/railway-agent-redeploy.mp4" />


# Overview
Source: https://docs.automa.app/self-hosting/index

Discover how to self-host Automa & agents on your own infrastructure

## Automa

Automa is a source-available platform for code automation that you can run on your own servers. Its source code is available on [GitHub](https://github.com/automa/monorepo).

It contains the following components:

* **Database**: A database for storing data.
* **Cache**: A key-value store for jobs, caching, and session management.
* **API**: The backend server that handles requests and integrates with external tools.
* **Console**: The web UI for interacting with the API to manage agents, tasks, and settings.

You can set up Automa in various ways, depending on your infrastructure and preferences. Below are the recommended methods:

<Columns cols={2}>
  <Card arrow title="Docker" icon="docker" href="/self-hosting/setup/docker">
    Set up Automa using Docker containers
  </Card>

  <Card arrow title="Railway" icon="train-track" href="/self-hosting/setup/railway">
    Set up Automa using Railway templates
  </Card>
</Columns>

## Agents

Automa also provides open-source agents that you can run on your own servers. Their source code is available in our GitHub [organization](https://github.com/automa).

Below are some of the agents that you can self-host:

<Columns cols={2}>
  <Card arrow title="Codex" href="/self-hosting/agents/codex">
    Set up Codex agent for Automa
  </Card>

  <Card arrow title="Claude Code" href="/self-hosting/agents/claude-code">
    Set up Claude Code agent for Automa
  </Card>

  <Card arrow title="Gemini" href="/self-hosting/agents/gemini">
    Set up Gemini agent for Automa
  </Card>
</Columns>


# GitHub
Source: https://docs.automa.app/self-hosting/integrations/github

A step-by-step guide to configure GitHub integration for Automa

Automa supports [GitHub](https://github.com) integration for:

* **Source Code Management:** Allows users to let the bots read the code. And allows bots to create pull requests to propose code changes after working on a task.

## Creating app

Assuming you have already [set up Automa](/self-hosting#automa), when you open **Automa Console** for the first time, if Automa doesn't detect a GitHub integration configuration, it will prompt you to create a [Github App](https://docs.github.com/en/apps/using-github-apps/about-using-github-apps). And once you complete it, we retrieve the necessary secrets which would need to be set as environment variables.

<video autoPlay muted loop playsInline className="mx-auto rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/integrations-github.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=fcd77299d3b2e809546da2dabf95b6ae" data-path="videos/self-hosting/integrations-github.mp4" />

<Tip>
  It only prompts you if you have not configured any **source code management**
  integration. If you haven't been prompted and still want to create a GitHub
  app and configure it, you can do so by visiting `/admin/setup/code`.
</Tip>

## Adding environment variables

To configure the GitHub integration, you need to set the following environment variables:

* `GITHUB_APP_SLUG`: The slug of your GitHub App.
* `GITHUB_APP_CLIENT_ID`: The client ID of your GitHub App.
* `GITHUB_APP_CLIENT_SECRET`: The client secret of your GitHub App.
* `GITHUB_APP_PEM`: The PEM file of your GitHub App, which contains the private key.
* `GITHUB_APP_WEBHOOK_SECRET`: The webhook secret for the webhook in your GitHub App.

Depending on your self-hosting setup, you can configure environment variables in different ways. You can find the relevant instructions for your setup below:

<Columns cols={2}>
  <Card arrow title="Docker" icon="docker" href="/self-hosting/setup/docker#adding-environment-variables">
    Configure environment variables in Docker
  </Card>

  <Card arrow title="Railway" icon="train-track" href="/self-hosting/setup/railway#adding-environment-variables">
    Configure environment variables in Railway
  </Card>
</Columns>


# Jira
Source: https://docs.automa.app/self-hosting/integrations/jira

A step-by-step guide to configure Jira integration for Automa

Automa supports [Jira](https://www.atlassian.com/software/jira) integration for:

* **Project Management:** Allows users to create tasks from Jira issues and update issues based on bot actions.

## Creating app

You can create a [Jira App](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/) by going to [Create > OAuth 2.0 integration](https://developer.atlassian.com/console/myapps/create-3lo-app) in Atlassian Developer Console.

<Steps>
  <Step title="Get server URL">
    Retrieve the URL for the **API** service after you [set up Automa](/self-hosting#automa).
  </Step>

  <Step title="Add scopes">
    Go to the **Permissions** tab and add the following scopes in **Jira API** category:

    * `read:jira-work`
    * `read:jira-user`
    * `write:jira-work`
    * `manage:jira-webhook`
  </Step>

  <Step title="Callback URL">
    Go to the **Authorization** tab and set the callback URL to `https://<your-api-server>/callbacks/jira`.
  </Step>

  <Step title="Copy the secrets">
    Go to the **Settings** tab and copy the required secrets:

    * Client ID
    * Client Secret
  </Step>
</Steps>

<video autoPlay muted loop playsInline className="mx-auto rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/integrations-jira.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=867ae722565fe947c99f61cbd46c756f" data-path="videos/self-hosting/integrations-jira.mp4" />

## Adding environment variables

To configure the Jira integration, you need to set the following environment variables:

* `JIRA_API_CLIENT_ID`: The client ID of your Jira App.
* `JIRA_APP_CLIENT_SECRET`: The client secret of your Jira App.

Depending on your self-hosting setup, you can configure environment variables in different ways. You can find the relevant instructions for your setup below:

<Columns cols={2}>
  <Card arrow title="Docker" icon="docker" href="/self-hosting/setup/docker#adding-environment-variables">
    Configure environment variables in Docker
  </Card>

  <Card arrow title="Railway" icon="train-track" href="/self-hosting/setup/railway#adding-environment-variables">
    Configure environment variables in Railway
  </Card>
</Columns>


# Linear
Source: https://docs.automa.app/self-hosting/integrations/linear

A step-by-step guide to configure Linear integration for Automa

Automa supports [Linear](https://linear.app) integration for:

* **Project Management:** Allows users to create tasks from Linear issues and update issues based on bot actions.

## Creating app

You can create a [Linear App](https://linear.app/developers) by going to [Settings > API > +](https://linear.app/settings/api/applications/new) in Linear.

<Steps>
  <Step title="Get server URL">
    Retrieve the URL for the **API** service after you [set up Automa](/self-hosting#automa).
  </Step>

  <Step title="Callback URL">
    Set the callback URL to `https://<your-api-server>/callbacks/linear`.
  </Step>

  <Step title="Turn on webhooks">
    Switch on the toggle for "Webhooks" to enable webhook support.
  </Step>

  <Step title="Webhook URL">
    Set the webhook URL to `https://<your-api-server>/hooks/linear`.
  </Step>

  <Step title="Select events">
    Choose the events you want to receive webhooks for:

    * Comments
    * Agent session events
    * Inbox notifications
    * Permission changes
  </Step>

  <Step title="Copy the secrets">
    Copy the required secrets:

    * Client ID
    * Client Secret
    * Webhook Signing Secret
  </Step>
</Steps>

<video autoPlay muted loop playsInline className="mx-auto rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/integrations-linear.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=081a569a9975d3e545a90e188e5c43e4" data-path="videos/self-hosting/integrations-linear.mp4" />

## Adding environment variables

To configure the Linear integration, you need to set the following environment variables:

* `LINEAR_API_CLIENT_ID`: The client ID of your Linear App.
* `LINEAR_APP_CLIENT_SECRET`: The client secret of your Linear App.
* `LINEAR_APP_WEBHOOK_SECRET`: The webhook secret for the webhook in your Linear App.

Depending on your self-hosting setup, you can configure environment variables in different ways. You can find the relevant instructions for your setup below:

<Columns cols={2}>
  <Card arrow title="Docker" icon="docker" href="/self-hosting/setup/docker#adding-environment-variables">
    Configure environment variables in Docker
  </Card>

  <Card arrow title="Railway" icon="train-track" href="/self-hosting/setup/railway#adding-environment-variables">
    Configure environment variables in Railway
  </Card>
</Columns>


# Licensing
Source: https://docs.automa.app/self-hosting/licensing

Licensing information & FAQ for Automa

Automa is licensed under the Business Source License 1.1 (BUSL-1.1) as source-available software. You can find the full text of the license [here](https://github.com/automa/monorepo/blob/master/LICENSE).

You can get a commercial license for Automa from our [pricing page](https://automa.app/pricing) if you want to use it in production for a use case that does not fall under the "Additional Use Grant" of our BUSL-1.1 license.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Is Automa open source?">
    <p>
      From the perspective of the [OSI](https://opensource.org/) and the broader
      software community, Automa is not considered open source software.
      However, its source code is available for anyone to view, modify, and use
      under the terms of the BUSL. Therefore, it is considered
      "source-available" software.
    </p>
  </Accordion>

  <Accordion title="Is internal use considered production use under BUSL?">
    <p>
      Yes, if you are using Automa internally to develop software applications
      and services, it is considered production use under the BUSL. Therefore,
      you must comply with the terms of the license.
    </p>
  </Accordion>

  <Accordion title="Can I self-host Automa for personal use?">
    <p>Yes, you can self-host Automa for personal use on personal projects.</p>
  </Accordion>

  <Accordion title="Can I self-host Automa and sell it as a service?">
    <p>No, you cannot self-host Automa and sell it as a service.</p>
  </Accordion>

  <Accordion title="Can I self-host Automa and offer it as a free service?">
    <p>No, you cannot self-host Automa and offer it as a free service.</p>
  </Accordion>

  <Accordion title="As an individual, can I self-host Automa for commercial purposes?">
    <p>
      Yes, if you are acting as an individual and not as part of an
      organization, you can self-host Automa for commercial purposes.
    </p>
  </Accordion>

  <Accordion title="As an organization, can we self-host Automa for commercial purposes?">
    <p>
      Yes, you can self-host Automa for commercial purposes as an organization,
      provided that the number of Product Development Personnel (**PDP**) in
      your organization does not exceed ten (10).
    </p>
  </Accordion>

  <Accordion title="What is the definition of Product Development Personnel (PDP)?">
    <p>
      **Product Development Personnel** are defined as any individuals who
      contribute to the design, development, testing, deployment, or maintenance
      of your organization's software applications or services.
    </p>
  </Accordion>

  <Accordion title="Are SREs & DevOps engineers considered PDP?">
    <p>
      Yes, SREs and DevOps engineers are considered PDP since they contribute to
      the deployment and maintenance of software applications or services.
    </p>
  </Accordion>

  <Accordion title="Is a Product Manager considered PDP?">
    <p>
      Yes, a Product Manager is considered PDP since they contribute to the
      design, development & testing of software applications or services.
    </p>
  </Accordion>

  <Accordion title="Is a Product Designer considered PDP?">
    <p>
      Yes, a Product Designer is considered PDP since they contribute to the
      design of software applications or services.
    </p>
  </Accordion>

  <Accordion title="Is everyone in my organization considered PDP?">
    <p>
      No, not everyone in your organization is considered PDP. People like
      Sales, Marketing, and Support, etc.. are typically not considered PDP.
    </p>
  </Accordion>
</AccordionGroup>


# Docker
Source: https://docs.automa.app/self-hosting/setup/docker

A step-by-step guide to setting up Automa using Docker containers

Automa publishes official [Docker](https://docker.com) images for the **API** and **Console** services which can be run on any system with Docker installed. This section will help you set it up using Docker containers.

## Setting up

You can set all this up locally on your machine or on a server. The setup is the same in both cases, but you may need to adjust the URLs and ports based on your environment.

There are 4 steps in the setup process:

* Start the needed services.
* Initialize the database schema.
* Check if the services are working.
* Configure third-party integrations.

### Start services

You will need:

* **Docker**: to run the database, cache, and Automa containers.
* **Docker network**: containers must share a user-defined network (e.g. `automa`).

#### Database

We use [PostgreSQL](https://www.postgresql.org/) for the database. The PostgreSQL container will store its data in a Docker volume named `automa-postgres-data`. It listens on port 5432. Make sure to replace `<db-password>` with a secure password of your choice.

```bash icon="terminal" theme={null}
docker run -d --name automa-postgres \
  --network automa \
  -e POSTGRES_USER=automa \
  -e POSTGRES_PASSWORD=<db-password> \
  -v automa-postgres-data:/var/lib/postgresql/data \
  -p 5432:5432 \
  postgres:15-alpine
```

#### Cache

We use [Redis](https://redis.io/) for the key-value store. The Redis container will store its data in a Docker volume named `automa-redis-data`. It listens on port 6379. Make sure to replace `<cache-password>` with a secure password of your choice.

```bash icon="terminal" theme={null}
docker run -d --name automa-redis \
  --network automa \
  -e REDIS_PASSWORD=<cache-password> \
  -v automa-redis-data:/data \
  -p 6379:6379 \
  redis:7-alpine
```

#### API

We use the latest [Automa API image](https://ghcr.io/automa/api). The API will connect to the PostgreSQL and Redis containers. It listens on port 8080. Make sure to replace `<your-cookie-secret>` with a secure secret for session management, and `<db-password>` and `<cache-password>` with the passwords you set earlier.

We also set the `BASE_URI` and `CLIENT_URI` environment variables to point to the URLs where the **API** and **Console** services will be accessible, respectively. We recommend using the server's public IP address or domain name for these variables. If you are running this on your local machine, you can use `localhost` in place of `<your-server>`.

<Note>
  The **Console** service while not yet available, will be served on port 80.
</Note>

```bash icon="terminal" theme={null}
docker run -d --name automa-api \
  --network automa \
  -e BASE_URI=http://<your-server>:8080 \
  -e CLIENT_URI=http://<your-server> \
  -e COOKIE_SECRET=<your-cookie-secret> \
  -e DATABASE_URL=postgresql://automa:<db-password>@localhost:5432/automa \
  -e REDIS_URL=redis://:<cache-password>@localhost:6379 \
  -p 8080:8080 \
  ghcr.io/automa/api
```

<Note>
  If you are running this on your local machine, you'll need to expose your
  local API service to the public internet so that any integrations that use
  webhooks can reach it. A tool like [ngrok](https://ngrok.com/) can create a
  secure tunnel to your `localhost`. You would then set the public URL provided
  by the tool as the `WEBHOOK_URI` environment variable for the `automa-api`
  container.
</Note>

#### Console

We use the latest [Automa Console image](https://ghcr.io/automa/console). The Console will connect to the API container. It listens on port 80. Make sure to set the `API_URI` environment variable to the URL of the **API** service. We recommend using the server's public IP address or domain name for this variable. If you are running this on your local machine, you can use `localhost` in place of `<your-server>`.

```bash icon="terminal" theme={null}
docker run -d --name automa-console \
  --network automa \
  -e API_URI=http://<your-server>:8080 \
  -p 80:80 \
  ghcr.io/automa/console
```

### Initialize database

To set up the database schema, you need to run the following command in the **API** container. This will create the necessary tables and indexes in your PostgreSQL database.

```bash icon="terminal" theme={null}
docker exec -it automa-api sh -c "npm run db-migrate"
```

### Check the setup

You can check if the containers are running with the following command:

```bash icon="terminal" theme={null}
docker ps
```

And if you visit `http://<your-server>` in your browser, you should see the **Automa Console** interface. If you are running this on your local machine, you can use `http://localhost` instead.

### Configuring integrations

Automa supports various third-party integrations like [GitHub](https://github.com), [Linear](https://linear.app), and [Jira](https://jira.com). Most of these integrations require you to set up OAuth applications on the respective platforms and provide the necessary credentials to the **Automa API** service.

You can find detailed instructions for each integration in the respective documentation pages:

<Columns cols={2}>
  <Card arrow title="GitHub" href="/self-hosting/integrations/github">
    Configure GitHub to allow users to provide access to their repositories, and
    creating tasks from issues and pull requests.
  </Card>

  <Card arrow title="Linear" href="/self-hosting/integrations/linear">
    Configure Linear to allow users to create tasks from issues.
  </Card>

  <Card arrow title="Jira" href="/self-hosting/integrations/jira">
    Configure Jira to allow users to create tasks from issues.
  </Card>
</Columns>

#### Adding environment variables

When you are configuring third-party integrations, you will need to add environment variables to the **API** service. These variables typically include client IDs, secrets, and other configuration details required for the integration to work.

For example, to add a Jira integration, first, stop and remove the container:

```bash icon="terminal" theme={null}
docker rm -f automa-api
```

Then, create the service again while adding your new environment variables.

```bash icon="terminal" theme={null}
docker run -d --name automa-api \
  --network automa \
  -e BASE_URI=http://<your-server>:8080 \
  -e CLIENT_URI=http://<your-server> \
  -e COOKIE_SECRET=<your-cookie-secret> \
  -e DATABASE_URL=postgresql://automa:<db-password>@localhost:5432/automa \
  -e REDIS_URL=redis://:<cache-password>@localhost:6379 \
  -e JIRA_APP_CLIENT_ID=<your-jira-client-id> \
  -e JIRA_APP_CLIENT_SECRET=<your-jira-client-secret> \
  -p 8080:8080 \
  ghcr.io/automa/api
```

## Updating

We recommend updating periodically to ensure you have the latest features and security updates. To update your services:

```bash icon="terminal" theme={null}
docker pull ghcr.io/automa/api ghcr.io/automa/console
docker restart automa-api automa-console
```

### Migrate database

Run the following command to apply any pending changes to database schema. It is safe to run this command even if there are no schema changes.

```bash icon="terminal" theme={null}
docker exec -it automa-api sh -c "npm run db-migrate"
```


# Railway
Source: https://docs.automa.app/self-hosting/setup/railway

A step-by-step guide to setting up Automa using Railway templates

Automa publishes official [Railway](https://railway.com) templates for the whole application. This section will help you set it up using Railway.

## Setting up

There are 3 steps in the setup process:

* Start the needed services.
* Check if the services are working.
* Configure third-party integrations.

### Start services

You will need an account on [Railway](https://railway.com) to get started. Once you have an account, go to the [Automa template](https://railway.com/deploy/PKfjlB?referralCode=Ri3kTG) and deploy it by clicking on the "**Deploy Now**" button.

<video autoPlay muted loop playsInline className="mx-auto rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/railway-deploy.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=cb9b4ed11a3ba902e499a22d44f00635" data-path="videos/self-hosting/railway-deploy.mp4" />

### Check the setup

If you have successfully deployed the template, you should see 4 healthy services in your Railway project: **API**, **Console**, **Postgres**, and **Redis**.

The **Console** service in the Railway project should have been automatically assigned a domain name by Railway in the form of `<random>.up.railway.app`. You can find this by clicking on the service, and if you visit this domain in your browser, you should see the **Automa Console** interface.

<video autoPlay muted loop playsInline className="mx-auto w-3/4 rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/railway-domain.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=ce65babf04e5c913471a38d6c85b842c" data-path="videos/self-hosting/railway-domain.mp4" />

### Configuring integrations

Automa supports various third-party integrations like [GitHub](https://github.com), [Linear](https://linear.app), and [Jira](https://jira.com). Most of these integrations require you to set up OAuth applications on the respective platforms and provide the necessary credentials to the **Automa API** service.

You can find detailed instructions for each integration in the respective documentation pages:

<Columns cols={2}>
  <Card arrow title="GitHub" href="/self-hosting/integrations/github">
    Configure GitHub to allow users to provide access to their repositories, and
    creating tasks from issues and pull requests.
  </Card>

  <Card arrow title="Linear" href="/self-hosting/integrations/linear">
    Configure Linear to allow users to create tasks from issues.
  </Card>

  <Card arrow title="Jira" href="/self-hosting/integrations/jira">
    Configure Jira to allow users to create tasks from issues.
  </Card>
</Columns>

#### Adding environment variables

When you are configuring third-party integrations, you will need to add environment variables to the **API** service in the Railway project.

For example, to add a Jira integration, go to the **API** service in your Railway project, click on the "**Variables**" tab, and add the new environment variables.

<video autoPlay muted loop playsInline className="mx-auto rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/railway-env-var.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=f02440811d3d5559f7908c91b473f4b3" data-path="videos/self-hosting/railway-env-var.mp4" />

## Updating

We recommend updating periodically to ensure you have the latest features and security updates. To update your **API** and **Console** services, go to each service in your Railway project, click on the "**Deployments**" tab, click on **three dots** on active deployment, and then choose the "**Redeploy**" option. This will pull the latest changes and redeploy your service.

<video autoPlay muted loop playsInline className="mx-auto rounded-xl" src="https://mintcdn.com/automa/eeL4keyWWsKr0LQB/videos/self-hosting/railway-redeploy.mp4?fit=max&auto=format&n=eeL4keyWWsKr0LQB&q=85&s=28b410a04aaa543185c129b618f51f0f" data-path="videos/self-hosting/railway-redeploy.mp4" />


# Overview
Source: https://docs.automa.app/webhooks/index

Learn about the webhooks sent by Automa

In Automa, webhooks are used to notify your bot about various events, such as task creation, proposal updates, and more. This allows your bot to respond to changes in real-time.

Automa's webhooks follow the [Standard Webhooks](https://www.standardwebhooks.com/) specification, which means they are designed to be secure and reliable. Therefore, all the events use the following payload structure:

* `id`: Unique identifier for the webhook event.
* `type`: The type of event (e.g., `task.created`, `proposal.accepted`).
* `timestamp`: The time when the event occurred, in ISO 8601 format.
* `data`: The event-specific data, which varies based on the event type.

```json  theme={null}
{
  "id": "whmsg_task_created_1234",
  "type": "task.created",
  "timestamp": "2025-07-28T04:58:00.000Z",
  "data": {
    /* task, repo, org, items */
  }
}
```

The events are also accompanied by the following headers:

* `webhook-id`: the same as payload `id`
* `webhook-timestamp`: UNIX timestamp of when the event occurred (seconds since epoch)
* `webhook-signature`: the signature(s) of the webhook used to verify the payload
* `x-automa-server-host`: the URL of the Automa server that sent the webhook

### Verifying signatures

To ensure the integrity and origin of webhooks, Automa signs each one using HMAC-SHA256. The signature is passed in the `webhook-signature` header, which includes a version identifier and the signature in base64 format, separated by a comma (e.g., `v1,d82n...`).

The signature is generated using your bot's webhook secret (excluding the `atma_whsec_` prefix). The content that is signed is a string made by concatenating the webhook ID, the timestamp in unix format, and the raw request body, joined by periods.

```
{id}.{timestamp}.{body}
```

We strongly recommend using our [Bot SDKs](/sdks/bot), which provide a helper function to verify the signature for you.

## Retries

When a webhook event is sent, Automa ensures that it is delivered successfully. If a delivery fails due to a non-2xx response or a network issue, Automa will retry.

The retry policy uses an **exponential backoff** strategy, with an initial delay of **10 minutes** and a maximum of **5 attempts**. The delay doubles with each subsequent retry.

To prevent side effects from repeated deliveries:

* Use the webhook id to detect and discard duplicate requests.
* Ensure your webhook handler is idempotent (safe to run multiple times).
* Use locking to protect shared resources from race conditions.


# proposal.accepted
Source: https://docs.automa.app/webhooks/proposal-accepted



<ResponseField name="proposal" type="Proposal">
  The proposal that was accepted.

  <Expandable title="properties">
    <ResponseField name="id" type="number">
      The unique identifier of the proposal.
    </ResponseField>

    <ResponseField name="data" type="object">
      The data associated with the proposal from the provider.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="task" type="Task">
  The task for which the proposal was originally created.

  <Expandable title="properties">
    <ResponseField name="id" type="number">
      The unique identifier for the task.
    </ResponseField>

    <ResponseField name="title" type="string">
      The title of the task.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="org" type="Organization">
  The organization containing the proposal.

  <Expandable title="properties">
    <ResponseField name="id" type="number">
      The unique identifier for the organization
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the organization.
    </ResponseField>

    <ResponseField name="provider_type" type="enum">
      The provider behind the organization.

      <Expandable title="values">
        <ResponseField name="github" type="string">GitHub</ResponseField>
        <ResponseField name="gitlab" type="string">GitLab</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Event theme={null}
  {
    "type": "proposal.accepted",
    "data": {
      "proposal": {
        "id": 123,
        "data": {
          "prId": 2593079484,
          "prBase": "master",
          "prHead": "automa:automa/openai/codex/2",
          "prState": "closed",
          "prTitle": "Auto-select only first enabled repository",
          "prMerged": true,
          "prNumber": 205
        }
      },
      "task": {
        "id": 2,
        "title": "Ignore disabled repos when trying to auto-select the first repo option in task creation"
      },
      "org": {
        "id": 1,
        "name": "automa",
        "provider_type": "github"
      }
    }
  }
  ```
</ResponseExample>


# proposal.rejected
Source: https://docs.automa.app/webhooks/proposal-rejected



<ResponseField name="proposal" type="Proposal">
  The proposal that was rejected.

  <Expandable title="properties">
    <ResponseField name="id" type="number">
      The unique identifier of the proposal.
    </ResponseField>

    <ResponseField name="data" type="object">
      The data associated with the proposal from the provider.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="task" type="Task">
  The task for which the proposal was originally created.

  <Expandable title="properties">
    <ResponseField name="id" type="number">
      The unique identifier for the task.
    </ResponseField>

    <ResponseField name="title" type="string">
      The title of the task.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="org" type="Organization">
  The organization containing the proposal.

  <Expandable title="properties">
    <ResponseField name="id" type="number">
      The unique identifier for the organization
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the organization.
    </ResponseField>

    <ResponseField name="provider_type" type="enum">
      The provider behind the organization.

      <Expandable title="values">
        <ResponseField name="github" type="string">GitHub</ResponseField>
        <ResponseField name="gitlab" type="string">GitLab</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Event theme={null}
  {
    "type": "proposal.rejected",
    "data": {
      "proposal": {
        "id": 123,
        "data": {
          "prId": 2593079484,
          "prBase": "master",
          "prHead": "automa:automa/openai/codex/2",
          "prState": "closed",
          "prTitle": "Auto-select only first enabled repository",
          "prMerged": false,
          "prNumber": 205
        }
      },
      "task": {
        "id": 2,
        "title": "Ignore disabled repos when trying to auto-select the first repo option in task creation"
      },
      "org": {
        "id": 1,
        "name": "automa",
        "provider_type": "github"
      }
    }
  }
  ```
</ResponseExample>


# task.created
Source: https://docs.automa.app/webhooks/task-created



<ResponseField name="task" type="Task">
  The task object containing details about the task that was created.

  <Expandable title="properties">
    <ResponseField name="id" type="number">
      The unique identifier for the task.
    </ResponseField>

    <ResponseField name="token" type="string">
      A unique token for the task, used to request access to the code base.
    </ResponseField>

    <ResponseField name="title" type="string">
      The title of the task.
    </ResponseField>

    <ResponseField name="items" type="object[]">
      Detailed items related to the task.

      <Expandable title="items">
        <ResponseField name="type" type="enum">
          The type of the item.

          <Expandable title="values">
            <ResponseField name="origin" type="string">Origin of the task</ResponseField>
            <ResponseField name="message" type="string">Comment on the task</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="data" type="object">
          The content of the item.

          * `origin`: It contains the data associated with the integration from where the task originated.
          * `message`: It contains the content of the message on the task.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="repo" type="Repository">
  The repository on which the tasks is to be implemented.

  <Expandable title="properties">
    <ResponseField name="id" type="number">
      The unique identifier for the repository.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the repository.
    </ResponseField>

    <ResponseField name="is_private" type="boolean">
      Indicates whether the repository is private.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="org" type="Organization">
  The organization where the task was created.

  <Expandable title="properties">
    <ResponseField name="id" type="number">
      The unique identifier for the organization.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the organization.
    </ResponseField>

    <ResponseField name="provider_type" type="enum">
      The provider behind the organization.

      <Expandable title="values">
        <ResponseField name="github" type="string">GitHub</ResponseField>
        <ResponseField name="gitlab" type="string">GitLab</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Event theme={null}
  {
    "type": "task.created",
    "data": {
      "task": {
        "id": 2,
        "token": "abc123xyz",
        "title": "Ignore disabled repos when trying to auto-select the first repo option in task creation",
        "items": [
          {
            "type": "origin",
            "data": {
              "orgId": 1
            }
          },
          {
            "type": "message",
            "data": {
              "content": "In the file named `TaskCreate.tsx`, when we are trying to use `setValue` on the first repository option, we should ignore disabled repository options."
            }
          }
        ]
      },
      "repo": {
        "id": 1,
        "name": "monorepo",
        "is_private": true
      },
      "org": {
        "id": 1,
        "name": "automa",
        "provider_type": "github"
      }
    }
  }
  ```
</ResponseExample>