Skip to main content
Codex agent for Automa is based on OpenAI’s Codex CLI tool. It’s source code is available on GitHub. 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 of 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.
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 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.

​
Docker

Automa publishes official Docker images for the 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 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. 
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
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.

​
Agent

We use the latest Automa Codex agent image. 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. 
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: 
docker ps

​
Updating

We recommend updating periodically to ensure you have the latest features and security updates. To update your services: 
docker pull ghcr.io/automa/codex
docker restart automa-codex

​
Railway

Automa publishes official Railway 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 to get started. Once you have an account, go to the Automa Codex agent template 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.

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

​
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.
⌘I