GitOps deployment engine for AI CoreKit. One autobuilder container manages many auto-built repositories, each described by a folder under deployments/.
The autobuilder polls the deployments folder and reconciles app containers directly via the Docker socket. Every POLL_INTERVAL seconds (default 60s) it fetches each deployment's branch, rebuilds the image when the deployment hash changes, and (re)creates the app container on the project's default network.
Each app container is labeled with CoreKit's generic managed-child labels (corekit.child=true, corekit.parent.service, corekit.project, and corekit.service). corekit ps includes any container using that generic contract, and corekit down autobuilder removes AutoBuilder's children through this service's cleanup hook. If the autobuilder profile is disabled, corekit up pruning also stops the disabled parent service so its cleanup hook can remove labeled children.
The deployment hash covers the fetched repo commit, service.json, .env, and any deployment-folder Dockerfile override. AutoBuilder stores that hash as Docker labels on the image and app container, so changes to runtime env, build args, ports, commands, volumes, or deployment Dockerfile content are reconciled even when the git commit is unchanged.
Each deployment is a folder containing a spec file, an env file, and optionally a Dockerfile override:
deployments/main-site/
├── service.json # git repo, branch, token, port, build args, command (structured)
├── .env # app environment variables (passed via --env-file)
└── Dockerfile # (optional) custom Dockerfile if the repo doesn't have one
All deployments/*/ folders are gitignored — tokens and app secrets stay off disk history. The _example/ template is tracked as a starting point.
dockerfile_path takes precedence over dockerfile. Specify at most one.
Pure, unprefixed environment variables for the running app container. They're passed via --env-file — no stripping, no filtering.
# deployments/main-site/.env
GEMINI_API_KEY=sk_live_...
SERVICE_ALLOWED_HOSTS=tcoretech.com,localhost,main-site
VITE_ALLOWED_HOSTS=tcoretech.com,localhost,main-site| When | What gets through | Controlled by |
|---|---|---|
docker build |
Vars from the deployment's own .env whose keys match build.args globs — passed as --build-arg; use "*" only when you intentionally want every key from that one deployment .env |
service.json → build.args |
| Container runtime | Every var in .env — passed via --env-file |
.env alone |
Frontend frameworks that inline env vars at compile time (Vite, Next.js, Create React App) need build-time args. Everything else lives happily in the runtime env. Prefer narrow patterns like NEXT_PUBLIC_*, VITE_*, or PUBLIC_*. Passing "*" is convenient, but Docker build args are not a secret mechanism and may be exposed through Dockerfile usage, image metadata/provenance, or build cache. For in-repo Dockerfiles, the Dockerfile still needs matching ARG declarations before Docker will make those values available during build.
AutoBuilder exposes a CLI via corekit's standard run command:
corekit run autobuilder help # show all commands
corekit run autobuilder list # list deployments + container status
corekit run autobuilder add my-app # scaffold deployments/my-app/ from the template
corekit run autobuilder edit my-app # edit service.json in $EDITOR
corekit run autobuilder show my-app # print spec (token redacted) + .env
corekit run autobuilder rebuild my-app # force an immediate rebuild
corekit run autobuilder migrate my-app # run the deployment's post_build_run target on demand
corekit run autobuilder logs -f # tail autobuilder logs
corekit run autobuilder logs my-app -f # tail an app container's logs
corekit run autobuilder app-logs my-app -f # tail the app container's logs
corekit run autobuilder reload # restart autobuilder to reconcile immediately
corekit run autobuilder remove my-app # stop, delete image, delete folder# 1. Scaffold a new deployment
corekit run autobuilder add landing-page
# 2. Configure it
$EDITOR services/custom-services/autobuilder/deployments/landing-page/service.json
$EDITOR services/custom-services/autobuilder/deployments/landing-page/.env
# 3. Start autobuilder (first time) or reload (already running)
corekit up autobuilder
# or: corekit run autobuilder reload
# 4. Watch the first build
corekit run autobuilder logs -fFor each deployment, autobuilder uses the first of these it finds:
- In-repo Dockerfile by path — set
build.dockerfile_pathinservice.jsonto a path inside the cloned repo (e.g."deploy/docker/Dockerfile.web"). Passed via-f; the build context stays at the repo root. Combines naturally withbuild.targetfor multi-stage Dockerfiles. - Custom Dockerfile from the deployment folder — set
build.dockerfileto a path inside the deployment folder. Copied into the repo at build time. - The repo's own
Dockerfile— used as-is. - Auto-detected template — if the repo has
package.json, a bundled Node.js Dockerfile template is used.
corekit up autobuilder
├─ secrets.sh (no-op)
├─ prepare.sh → validates deployments/*/service.json, ensures data/repos/<name>/ dirs
├─ build.sh → docker build ./updater -t autobuilder:latest
├─ docker compose up -d (static compose: one service, `autobuilder`)
└─ healthcheck.sh → confirms the autobuilder container is running
Inside the autobuilder container, every POLL_INTERVAL seconds:
for each deployments/<name>/:
├─ read service.json (spec) and .env
├─ clone or fetch into /app/repos/<name>
├─ compute desired deployment hash from commit + spec + env + Dockerfile override
├─ if hash changed / missing image / missing, failed, or unhealthy container:
│ ├─ build <name>:latest with the spec's build.args as --build-arg
│ ├─ run automatic post_build_run, if configured
│ └─ docker run -d --name <name> --network <project>_default --label corekit.child=true --env-file .env <name>:latest
└─ continue
All app containers live on the <project>_default network (e.g. localai_default), so Caddy and any other core-stack service can reach them by container name. Removing a deployment folder also removes the previously managed container during the next reconcile loop.
Add bind mounts in service.json under volumes. Each entry is a string of the form <src>:<dst>[:flags]:
- Relative
<src>(e.g../data/api) resolves to<deployments-host-path>/<deployment-name>/<src>on the host. The autobuilder learns its host path from theDEPLOYMENTS_HOST_PATHenv var (set byprepare.sh). - Absolute
<src>passes through unchanged. <src>may reference environment variables via${VAR}or${VAR:-default}syntax. Variables resolve against the deployment's own.env, which is sourced into a subshell at volume-resolution time (so deployments don't leak vars to each other). After expansion the result is classified as absolute or relative using the rules above.
"volumes": [
"./data/api:/data", // relative — resolves under <deployments-host-path>/<name>/data/api
"./config/settings.env:/config/settings.env:ro",
"${ASSETS_DIR}/sample-data:/srv/sample:ro", // env var must be defined in this deployment's .env
"${OPTIONAL_PATH:-/srv/empty}:/srv/optional:ro" // falls back to /srv/empty if OPTIONAL_PATH unset
]Use env-var-driven absolute paths when your deployment needs to mount data that lives outside its deployment folder — datasets curated elsewhere on the host, large files you don't want under the deployment directory, or developer-machine-specific paths.
Some deployments need a side-effect container after each rebuild — database migrations being the classic case. Configure post_build_run in service.json:
"post_build_run": {
"dockerfile_path": "deploy/docker/Dockerfile.web",
"target": "migrator",
"command": null,
"auto": true // default true — fire every rebuild. Set false for manual-only.
}When auto is true, the autobuilder builds the named target into <name>-post:latest after each successful main-image build, runs it once with --rm --env-file .env --network <project>_default, then proceeds to (re)create the long-running app container. If the automatic post-build run fails, deployment stops and the existing app container is left in place.
When auto is false, the spec stays dormant and you trigger it manually:
corekit run autobuilder migrate <name>The CLI invokes docker exec autobuilder /app/start.sh run-post <name>, which performs the same build + run flow on demand regardless of the auto flag.
cd services/custom-services/autobuilder
# 1. Create a deployment folder
mkdir -p deployments/my-app
cp deployments/_example/service.json deployments/my-app/service.json
cp deployments/_example/.env.example deployments/my-app/.env
$EDITOR deployments/my-app/service.json
$EDITOR deployments/my-app/.env
# 2. Build the updater image and start
bash prepare.sh
bash build.sh
docker compose -p localai up -dIf you have an old service directory that was cloned from autobuilder:
corekit run autobuilder add main-site
# Copy values from services/custom-services/main-site/.env into:
# deployments/main-site/service.json (git, container, build.args)
# deployments/main-site/.env (app env vars only — GEMINI_API_KEY, VITE_*, etc.)
corekit disable main-site # drop the old service from profiles
corekit down main-site # stop the old container
corekit up autobuilder # autobuilder brings up main-site; name unchangedThe new container's name is the same (main-site), so any Caddy routes or cross-service references keep working.
{ "name": "main-site", // must match folder name; becomes container name and image tag "git": { "repo": "https://github.com/org/repo", "branch": "main", "token": "ghp_…" // optional; only needed for private repos }, "container": { "port": 3000, // port the app listens on inside the container "host_port": 3000, // optional; publish on host. Omit or null to keep internal "command": "npm run preview -- --host" // optional; overrides Dockerfile CMD }, "build": { "dockerfile": null, // path inside the deployment folder; copied into the repo as `Dockerfile` "dockerfile_path": null, // path inside the cloned repo; passed via -f (context stays at repo root) "target": null, // multi-stage build target (e.g. "runtime") "args": ["VITE_*", "NEXT_PUBLIC_*"], // glob patterns — matched against .env for --build-arg injection "args_map": {} // explicit { KEY: "value" } build args, merged with the glob list }, "volumes": [ // optional bind mounts. <src> may be: "./data:/data", // - a relative path resolved under <deployments-host-path>/<name>/<src>, "./config/settings.env:/config/settings.env:ro", "${ASSETS_DIR}/sample-data:/srv/sample:ro", // - or an env-var reference; ${VAR} and ${VAR:-default} "${OPTIONAL_PATH:-/srv/empty}:/srv/optional:ro" // are expanded against the deployment's own .env. ], "post_build_run": { // optional one-shot run after each rebuild (e.g. db migrations) "dockerfile_path": "deploy/Dockerfile", // built with the same build_args as the main image "target": "migrator", "command": null // optional override of the image's CMD } }