appeeky spec
← Learn

Teams and CI · 7 min read

Run it on your own VM

One container on a machine you own does what GitHub Actions does: daily pulls, pushes after a merge and the weekly co-founder review.

Everything GitHub Actions does for the spec also runs in one container on a machine you own. Fill in an .env file, start it, and it works on a schedule: it pulls the data every day, pushes what you merge, and commits every result back to your repo.

When a VM is the better fit

  • No GitHub Actions

    Your code lives on GitLab, Bitbucket or your own git server, or Actions minutes are tight.

  • Several apps

    One small machine runs the routines for every app, each with its own env file.

  • The weekly review on your Claude plan

    Run the co-founder review with your Pro or Max subscription instead of an API key.

  • Your own keys stay on your machine

    The store, Claude, fal, model and Search Console keys live in one .env file on a server you control.

Both can live side by side: the pull request check stays in Actions if you have it, and the VM does the scheduled work. Pick one place for push, so a merge is pushed once.

Pick a machine

Any Linux machine with Docker works. The routines clone the repo, run for a minute and exit, so the smallest plan of most providers is enough. The weekly review runs a coding agent, so give that one a little more memory.

  • Hetzner
  • DigitalOcean
  • AWS
  • Google Cloud
  • Railway
  • Fly.io
  • Render
  • Any Docker host

Nothing listens on a port. The container only calls GitHub, Appeeky, the stores and, if you set them, Claude and fal.

A token for one repo

On GitHub, create a fine-grained personal access token with Only select repositories → the app's repo, and Contents: Read and write. For the weekly review add Pull requests: Read and write. With any other git host, use a token that can push to that one repo.

.env
# The app's repo, and a fine-grained token for it (Contents: read and write;
# Pull requests: read and write too for the weekly review)
REPO_URL=https://github.com/you/sleep-sounds.git
GITHUB_TOKEN=github_pat_…
APPEEKY_API_KEY=apk_…
# Optional
DAILY_AT=0 6 * * * # UTC
PUSH_EVERY=*/15 * * * * # "off" to push by hand
WEEKLY_AT=0 7 * * 1 # the co-founder review, with the agent image
CLAUDE_CODE_OAUTH_TOKEN=… # claude setup-token: runs on your Claude plan
FAL_KEY=… # UGC clips on your own fal account
GSC_CREDENTIALS=/keys/gsc.json # Google Search Console: a service account key
ASA_CLIENT_ID=SEARCHADS.… # Apple Search Ads API user (also ASA_TEAM_ID, ASA_KEY_ID,
ASA_PRIVATE_KEY=/keys/asa.pem # ASA_PRIVATE_KEY): spend, installs and search terms
VISIBILITY_EVERY=7 # ask the AI assistants every 7 days, on these keys:
OPENAI_API_KEY=… # ChatGPT (also GEMINI_API_KEY, PERPLEXITY_API_KEY)
HEALTHCHECK_URL=https://hc-ping.com/…
PUSH_DRY_RUN=1 # the first week: show what a push would do

Start it

docker-compose.yml
services:
appeeky-spec:
image: ghcr.io/appeeky/appeeky-spec:latest # or :latest-agent
command: schedule
env_file: .env
restart: unless-stopped
your-vm
$ ssh root@your-vm
$ curl -fsSL https://get.docker.com | sh
$ mkdir appeeky-spec && cd appeeky-spec
$ # put docker-compose.yml and .env here
$ docker compose up -d
$ docker compose logs -f

The first lines of the log show the schedule and where push starts following main:

your-vm
$ docker compose logs -f
Running on this schedule (UTC):
0 6 * * * daily
*/15 * * * * push
0 7 * * 1 weekly
[push] Started at 3f2a91c. Merged listing changes are pushed from now on.

The schedule mode keeps running and restarts with the machine. To run one routine by hand: docker compose run --rm appeeky-spec daily.

What runs, and when

  • daily06:00 UTC

    Category rank, AI visibility, Google search, reviews, competitors, social posts and UGC clips. Releases measured on day 7 and 14, verdicts written to the playbook. All committed to the repo.

  • pushevery 15 minutes

    When main has a merged listing change, pushes it to the stores and records the release. Approved social drafts are sent and UGC briefs are made. A change the store cannot take yet waits for the next run.

  • weeklyMonday, optional

    The co-founder review: six specialists read the repo, one change is proposed for a store that is free, with a brief, as a pull request. Needs the agent image and a Claude token.

Every routine starts from a fresh clone and ends with a commit, so the container keeps nothing between runs. Where push left off is a tag in the repo, appeeky-spec/pushed: replace the machine and it carries on from there.

A safe first week

  • Nothing old goes out

    The first run starts from what is on main today and never pushes it. Only merges after that are pushed.

  • Dry run first

    With PUSH_DRY_RUN=1, push prints what it would change and the posts and clips it would send, and changes nothing.

  • Know when it fails

    HEALTHCHECK_URL is pinged after every daily run and gets /fail when it fails, so healthchecks.io or a similar service emails you.

  • Logs stay small

    docker-compose.yml rotates them at 10 MB.

Container platforms and other schedulers

On Railway, Fly.io or Render, deploy the same image as a worker with no public port, set the variables from the .env file, and use schedule as the command. It behaves exactly like the VM.

Already have a scheduler, like cron, a Kubernetes CronJob or a CI you use elsewhere? Run one routine per job with MODE=daily, MODE=push or MODE=weekly. Each run does its work, commits and exits.

cron
$ docker run --rm --env-file .env -e MODE=daily ghcr.io/appeeky/appeeky-spec:latest