Docs — Aibotq.dev

1 · Connect a source

Open /new. You can start four ways:

Import a repository. Sign in with GitHub (scopes read:user and repo), search your repositories — private and organization repos included — and press Import. GitLab and Bitbucket work the same way when the operator has configured them; otherwise their buttons say so.
Public repository URL. Paste an https:// URL on github.com, gitlab.com or bitbucket.org. Aibotq checks the repository exists before continuing.
Upload. Drop a folder or a .zip. Limits: 50 MB and 1000 files; node_modules, .git and .env* are skipped. Uploads require an R2 bucket bound to the Worker — if there isn't one, the UI tells you.
Template. Agent App, AI Chatbot and Commerce Agent are GitHub template repositories. Aibotq copies one into your account as a new repository (private by default) and carries on.

2 · Configure

Field	Notes
Project name	2–40 characters: lowercase letters, numbers, hyphens.
Framework	nextjs, nuxt, astro, sveltekit, remix, vite, cra, node, static, other. Auto-detected from `package.json` (and re-detected when you change the root directory).
Build command	Single line, e.g. `npm run build`. Empty means no build step.
Output directory	Relative path such as `dist` or `.next`. No `..`.
Root directory	For monorepos: the sub-folder that holds the project.
Environment variables	See below.

3 · Deploy

Press Deploy to edge. Aibotq creates a deployment record and sends a signed request to the build pipeline. The page then polls the deployment and shows its real state — Queued → Building → Live — together with the log the pipeline reports. When the pipeline reports success you get the live URL.

Nothing is simulated. If the pipeline is not configured or cannot be reached you see Deploy failed: <reason>, and a deployment that never reports back is marked failed after 20 minutes. Deploys are rate-limited to 10 per 10 minutes per account. Redeploy any time from the dashboard.

Git push = deploy

For GitHub repositories, creating the project registers a webhook on the repository:

a push to the default branch starts a production deployment;
a pull request opened, synchronized or reopened from the same repository starts a preview deployment;
pull requests from forks are ignored so untrusted code never runs next to your environment variables.

Registering a webhook needs admin access to the repository and a server-side GITHUB_WEBHOOK_SECRET. If either is missing, the project page shows the actual reason instead of claiming auto-deploy is on. GitLab, Bitbucket and uploads are redeployed manually.

Environment variables

Up to 64 variables per project, names matching [A-Za-z_][A-Za-z0-9_]*, values up to 4096 characters. They are encrypted at rest (AES-GCM) and are write-only: the API returns only their names. They are sent to the build pipeline when a deployment starts — treat the pipeline as part of your trust boundary.

Build pipeline contract

Aibotq does not build code itself; it hands the job to a build pipeline you operate (DEPLOY_WEBHOOK_URL) and tracks the result.

Request: Aibotq → pipeline

POST DEPLOY_WEBHOOK_URL, JSON body, with headers x-aibotq-event: build, x-aibotq-timestamp (unix seconds) and x-aibotq-signature: sha256=<hex> where the signature is HMAC-SHA256(DEPLOY_WEBHOOK_SECRET, "<timestamp>.<raw body>"). Verify it and reject old timestamps.

build request body

{
  "deployment_id": "…",
  "environment": "production" | "preview",
  "project": { "id", "name", "framework", "build_command", "output_dir", "root_dir" },
  "source": {
    "type": "git", "provider", "repo", "clone_url", "branch", "commit_sha", "private",
    "token": "…"            // only for private repos
    // or: "type": "upload", "manifest_url": "…"   (short-lived signed URL)
  },
  "env": { "KEY": "value" },
  "callback_url": "https://aibotq.dev/api/deployments/<id>/callback"
}

Any non-2xx answer (or no answer within 15 seconds) fails the deployment with that reason.

Callback: pipeline → Aibotq

POST callback_url with the same signing scheme and a JSON body. Call it as often as you like while building, then once with a final status.

callback body

{
  "status": "building" | "ready" | "failed",
  "step": "optional short label",
  "log": "optional text appended to the deployment log",
  "url": "https://…",          // required when status is "ready", https only
  "commit_sha": "optional"
}

JSON API

Cookie-authenticated, same-origin. Responses are {"ok":true,"data":…} or {"ok":false,"error":"…"}. Every POST must carry a same-origin Origin header.

Route	Purpose
`GET /api/config`	Which providers, uploads and deploy pipeline are configured.
`GET /api/me`	Current user or `null`.
`GET /api/auth/github?mode=login\|signup`	Start OAuth (also gitlab, bitbucket).
`POST /api/auth/logout`	End the session.
`GET /api/repos?provider&q&page`	Your repositories, searchable and paginated.
`POST /api/repos/resolve`	Validate a public repository URL.
`GET /api/repos/detect`	Detect framework and build settings.
`POST /api/upload`	Multipart upload (`files`) to R2.
`GET /api/templates` · `POST /api/templates/:id/create`	List templates; create a repo from one.
`GET /api/projects` · `POST /api/projects`	List or create projects.
`GET /api/projects/:id` · `GET /api/projects/:id/deployments`	Project details; deployment history with logs.
`POST /api/projects/:id/deploy`	Start a production deployment.
`GET /api/deployments/:id`	Status and log of one deployment.

Self-hosting

Aibotq.dev is a Cloudflare Worker with static assets and a D1 database. To run your own:

setup

npm install
npx wrangler d1 create aibotq          # paste the id into wrangler.jsonc
npx wrangler d1 migrations apply aibotq --remote
npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put SESSION_SECRET
npx wrangler secret put GITHUB_WEBHOOK_SECRET
npx wrangler secret put DEPLOY_WEBHOOK_SECRET
npx wrangler deploy

Register a GitHub OAuth App with the callback URL https://aibotq.dev/api/auth/github/callback (use your own domain). Optionally create an R2 bucket (npx wrangler r2 bucket create aibotq-uploads) and bind it as UPLOADS to enable uploads. For local work put the same names in an untracked .dev.vars file and run npx wrangler dev. Never commit secrets.