
| When this happens | What happens | You get |
|---|---|---|
| A new error shows up in Sentry | Opens a GitHub issue with the stack trace and breadcrumbs. You read it and start Codex on it from GitHub Actions | A draft pull request with a fix and a regression test |
| Someone adds the label codex to a Linear task | Starts a Codex run that implements the task | A pull request attached to the Linear task |
| Support tags a Crisp chat with triage | Asks an AI model whether it's a bug, a feature request, a question or spam | A private note in Crisp, and for a bug an issue or a draft fix |
| Monday comes | Pulls last week's numbers from PostHog | A report in Slack |
| You push to production | Codex reads the commits | A pull request with a changelog note |
| Every day | Codex audits your site's SEO and fixes what it can | A pull request with the fixes and a report |
| Started by | When | Workflow |
|---|---|---|
| The server | A Linear task gets the label, or Crisp triage finds a bug in fix mode | linear-implement.yml, codex-issue-fix.yml |
| A repository event | A team member opens an issue or starts a run by hand, or you push to production | codex-issue-fix.yml, codex-changelog.yml |
| A schedule (cron) | Once a day | codex-seo-autopilot.yml |
.github/ or .agents/, so the agent can't rewrite its own workflow.hooks.example.com), one for the admin (admin.example.com).We deploy the server on your VPS, connect GitHub, Sentry, Linear and Crisp, and log Codex in with your ChatGPT plan. You get the admin and the first pull requests.
Loading editor...
curl -fsSL https://raw.githubusercontent.com/paralect/automation-server/main/scripts/deploy-vps.sh | sudo bash
/opt/automation-server.env with mode 600ufw is on, and starts everything behind Traefik with HTTPS.env:Loading editor...
sudo /opt/automation-server/scripts/deploy-vps.sh
IMAGE_TAG=sha- in .env to pin the previous build and run the script again. Set it back to latest to follow main./webhooks/* and /health on the webhook domain. Everything else there answers 404, including the admin's API.

| Permission | Access | Why |
|---|---|---|
| Issues | Read and write | Sentry and Crisp create issues |
| Actions | Read and write | Linear and Crisp start workflows, the admin shows runs |
| Contents | Read and write | The admin installs workflow files |
| Pull requests | Read and write | Installing in pull request mode opens a PR |
| Workflows | Read and write | GitHub requires it for any change in .github/workflows/ |
owner/name and click Test connection.codex login and finish the login in the browser. This writes ~/.codex/auth.json.CODEX_AUTH_JSON and paste the whole file. On a Mac, pbcopy < ~/.codex/auth.json copies it.
GH_PAT_FOR_SECRET_WRITE: a fine-grained token with Secrets: Read and write on this repository. The workflow then saves the new login back after each run.auth.json into an issue, a pull request or a screenshot. The workflow also refuses to open a PR whose text contains a value from it.CODEX_REASONING_EFFORT to high or leave it unset (the default is high). Without an explicit effort, Codex can run with reasoning turned off. CODEX_MODEL picks the model.OPENAI_API_KEY instead, which works in public repositories too. The issue fix and Linear workflows need CODEX_AUTH_JSON.
| Workflow | Starts when | You get |
|---|---|---|
codex-issue-fix.yml | A team member opens an issue or starts it by hand, or Crisp triage finds a bug | A draft PR with a fix and a regression test |
linear-implement.yml | The server sees the trigger label on a Linear task | A PR ready for review, attached to the task |
codex-changelog.yml | A push to your production branch | A PR with a changelog note |
codex-seo-autopilot.yml | Once a day, on GitHub's schedule | A PR with SEO fixes and a report |
.agents/skills/ that tells Codex how to do the job. The same Install button adds it. In pull request mode, merge the PR the admin opened: GitHub only runs a workflow once it's on the branch it starts from.fix-issue came from another project and names that project's check commands (npx tsc --noEmit, npx vitest run, npm run lint). Swap in your own, or Codex will run the wrong checks.The bundled skills come from another project. We rewrite them for your stack, your checks and your conventions, so Codex runs the right tests and writes PRs your team would merge.
sentry appears.error and fatal events become issues. Set SENTRY_ENVIRONMENTS=production to skip staging noise. A repeat alert for the same Sentry issue doesn't open a second GitHub issue.codex.
ENG-42: ...), so Linear attaches it. Running it again for the same task updates the same PR.triage segment. Start in shadow mode, which only writes a private note with the verdict. Switch to issue to open GitHub issues for bugs, or fix to start Codex on them too. A free Crisp plan can't receive private notes over the API, so use issue mode there. Personal data is stripped before the model sees the chat, and the customer never gets a message from the server.| Variable | Example |
|---|---|
SEO_SITE | https://example.com |
SEO_PRODUCT | What you sell, in 1 sentence |
SEO_CONVERSION | The action that counts, like a signup |
SEO_COMPETITORS | Optional. Leave it empty and Codex finds them |
OPENAI_API_KEY secret instead of CODEX_AUTH_JSON. The ChatGPT login only runs in private repositories.seo/ folder in your repo: the site context, a keyword map, a backlog, competitor snapshots and a report per run. From that memory it decides whether today is a light daily pass, a weekly review or a monthly one. The workflow downloads the skill pinned to 1 commit and checks its hash, so a change upstream can't change what Codex runs.seo/ only counts once it's on the default branch, so while a previous SEO PR is open, the daily run skips. Start it from the Actions tab with force to override.robots.txt, the home page and the footer, and we merged it the next day.write-changelog skill ships with the workflow, and the same Install button adds both. On each push to your production branch, Codex reads the commits in that push and writes 1 note for the people who use your product. It leaves out refactors, dependency bumps, CI and tests. If nothing in the push is visible to users, it writes nothing and no pull request opens.title, description and date. The PR body lists the commits it left out and anything you should double-check.| Variable | Default | Set it to |
|---|---|---|
PRODUCTION_BRANCH | production | The branch you deploy from, often main |
CHANGELOG_DIR | changelog | The folder your site reads release notes from |
.agents/skills/write-changelog/ have to be on that branch, not only on the default one.changelog/ as MDX while the site rendered its changelog from a JSON file. Codex flagged it in the PR, but point CHANGELOG_DIR at the right place before the first run.200. So the server records every run (1 automation handling 1 event) and every log line, and the admin shows both. Run 1 real event through each automation and follow it:ENG-42, a Crisp session). You see webhook received and every line of every run it started. Turn on Live while you send a test webhook.
| Status | Means |
|---|---|
running | Working now. If the server restarts mid-run, it becomes failed with interrupted by server restart |
succeeded | Finished without an error. It may have done nothing on purpose, like skipping a staging error. The log says |
failed | Threw an error. The message usually names the fix: a token, a permission, a missing workflow |
duplicate | The event was already handled, so it was skipped. Normal when a sender redelivers |
succeeded only means the workflow started. Whether Codex opened a pull request shows on the GitHub Actions page.LOG_RETENTION_DAYS).docker logs and any log collector see it. Wire 3 checks into the monitoring you already have:GET /health on the webhook domain returns {"status":"ok"}."message":"automation failed" or "message":"job failed".webhook signature rejected means a secret didn't reach the new server.| You see | Fix |
|---|---|
401 or 403 from GitHub | The token lacks a permission from step 3, or it expired |
404 when starting a workflow | The workflow isn't merged into the branch yet, or the token can't see the repo |
| The run fails on gh pr create | Actions aren't allowed to create pull requests yet |
CODEX_AUTH_JSON is not set | The secret is missing or sits in another repository |
| Sentry webhook rejected | The client secret in the admin doesn't match the integration. Copy it again |
packages/sources/src// .packages/automations/src/.apps/server/src/integrations//index.ts , and add the fields the admin should show to packages/settings/src/spec.ts. Once someone fills them in the admin, the webhook goes live at /webhooks// without a restart. The Sentry integration is the smallest complete example to copy.Stripe, Vercel, Intercom, Zendesk or your own app: we build the source and the automation, with signature checks, tests and safe retries, and send it to you as a pull request.
Loading editor...
Read docs/adding-an-integration.md, then the Sentry integration in packages/sources/src/sentry and apps/server/src/integrations/sentry. Add a Stripe integration the same way: - verify the Stripe-Signature header on the raw body - parse invoice.payment_failed events - add an automation that opens a GitHub issue labelled stripe with the customer ID and the amount, and no email addresses - add the webhook secret and target repository to the admin settings Follow the checklist at the end of the doc. Add test fixtures, then run bun run test and bun run check-types until both pass.
main as ghcr.io// , and the deploy script pulls the image of whatever repository it cloned. Point it at your fork:Loading editor...
curl -fsSL https://raw.githubusercontent.com/<you>/automation-server/main/scripts/deploy-vps.sh \ | sudo REPO_URL=https://github.com/<you>/automation-server.git bash
SETTINGS_ENCRYPTION_KEY stable. Change it and every secret saved in the admin becomes unreadable.We deploy the server, connect your repo, Sentry and Linear, and tune the Codex skills to your checks, so the first pull requests are ones you'd merge.
Focus on customers and sales while we handle product delivery. Hire a dedicated AI maker or a whole product team.