Deploy from source code
Upload a JavaScript, Go or Python project as it is, with no Dockerfile. Agent Lab detects the framework, builds it, and makes it a web page or a web service.
What happens#
Zip the project with its dependency manifest at the top and upload it. The platform reads the project, makes a build plan and builds it:
- A project that only produces files for the browser becomes a web page, served from the CDN. A single-page app's routes, such as
/orders/42, all answer withindex.html. - A project that runs a server becomes a web service, built into an image that runs as a non-root user on port 8080.
You don't write a Dockerfile. If the project has one at the top, it is used instead of detection; see build settings to turn that off.
Leave these out of the zip
node_modules, .git, dist and .env. The platform installs dependencies itself and skips them if they are included anyway.
Supported frameworks#
| Becomes a web page | Becomes a web service |
|---|---|
| Vite (React, Vue, Svelte), Create React App, Vue CLI | Next.js (also output: "export" becomes a web page) |
| Angular, static Astro, plain HTML with a build script | Nuxt, SvelteKit, Remix, React Router 7, Astro with SSR |
| Express, Fastify, Koa, Hono, NestJS, any Node server |
npm, pnpm, Yarn and Bun are detected from the lockfile or the packageManager field. Node.js comes from engines.node, .nvmrc or .node-version; otherwise the latest LTS (24) is used. 18, 20, 22 and 24 are available.
Build environment#
For Node.js, the build runs on the full node:<version> image, which includes git, python3, make and g++; the service itself runs on the smaller node:<version>-slim. git works in the install and build steps, so a script that runs git rev-parse HEAD gets an answer:
- A build from GitHub has the pushed commit, fetched at depth 1, on a branch with the pushed branch's name.
- An upload gets a repository with one commit holding the uploaded files. A
.gitfolder in the upload is ignored.
Three variables describe the commit during the build: AGENTLAB_GIT_COMMIT_SHA, AGENTLAB_GIT_COMMIT_REF (the branch) and AGENTLAB_GIT_REPO (owner/name). They are set for GitHub builds and empty for uploads, and a variable you set with one of these names is ignored. They are not passed to the running service. A project with its own Dockerfile receives them if it declares them with ARG, and has git only if its own image has it.
Environment variables#
The plan lists the variables the code reads (from .env.example, process.env.* and import.meta.env.*) and marks the ones that look like secrets or are needed at build time (such as VITE_* and NEXT_PUBLIC_*).
For Nuxt 3 and later it also reads the keys written under runtimeConfig in nuxt.config: runtimeConfig.apiSecret is NUXT_API_SECRET, and runtimeConfig.public.apiBase is NUXT_PUBLIC_API_BASE. With nuxt-auth-utils it lists NUXT_SESSION_PASSWORD. Keys added by a spread (...shared), from a layer or by another module are not found: list those in .env.example.
Each secret also says who supplies its value (source):
generate: the value only has to be random and nobody needs to know it, such asNUXT_SESSION_PASSWORD,SESSION_SECRET,AUTH_SECRETorSECRET_KEY_BASE. It can be generated in the console, at the length the framework requires, or by an assistant throughsites_secrets_generate, which stores it without the assistant seeing it.person: every other secret, such as an API key, a webhook's signing secret or a database password. Only you have the value. A name from a service such asSTRIPE_orLINE_is alwaysperson, and so is any name the platform does not recognize.
- Enter them before deploying: a web service's in Settings › Runtime settings (secrets under Secrets), a web page's in Settings › Build variables. A version built from source lists the names the code reads that nothing sets yet.
- Variables are passed to the build too: a build-time name is baked into the web page, so never put a secret in a
VITE_orNEXT_PUBLIC_variable. - Secrets are available to the install and build steps as mounted values, for example a private registry token. They are never written into the image.
Build settings#
When detection guesses wrong, override it in Settings › Build settings. An empty field is detected.
| Setting | Example | Variable |
|---|---|---|
| Node.js version | 22 | ALPACK_NODE_VERSION |
| Install command | npm ci | ALPACK_INSTALL_CMD |
| Build command | npm run build:prod | ALPACK_BUILD_CMD |
| Start command | node dist/server.js | ALPACK_START_CMD |
| Output directory | dist/browser | ALPACK_OUTPUT_DIR |
| Ignore the repo's Dockerfile | on | ALPACK_IGNORE_DOCKERFILE |
| Root Directory | apps/web | — |
A variable with that name, set in the environment's runtime settings, wins over the setting. ALPACK_* variables steer the build only and are never passed to the running service.
Setting a start command on a project detected as a web page makes it a web service.
Monorepos#
For a repository with several projects, upload the whole repository and set Root Directory in the build settings to the project's folder, such as apps/web. The platform plans and builds from that folder, so its own package.json and lockfile decide the build. Packages from elsewhere in the repository, such as workspace:* dependencies, are not available to it yet.
A new project is not published when its first upload or push has nothing deployable at the top but has a project one or two folders down, as in a repository split into frontend/ and backend/. Nothing deployable means no Dockerfile, no package.json, go.mod, pyproject.toml, requirements.txt or setup.py, and no index.html. The version asks you to choose the folder, listing up to five, and the project stays undecided. Choosing one sets the Root Directory and deploys again: the newest commit from GitHub, or the same files in the console. Files with index.html at the top are still a web page, even with sources in a folder beside them.
When the build fails#
| What you see | Fix |
|---|---|
| Can't tell how to build this source | Put package.json at the top of the zip, or set a start command. |
| The build produced nothing | Set the output directory to where the build writes its files. |
| A web service's upload is only a web page | A web service can't go back to being a web page. Create a new project for it, or set a start command. |
| A native module fails to compile | Commit the lockfile; the build image already has the compilers (python3, make, g++). |
The build log on the version page shows each step. With an AI tool, ask for the build plan first; see MCP tools.
Go and Python#
Upload go.mod, pyproject.toml, requirements.txt or setup.py at the project root. A Dockerfile in the upload takes priority. Without one, Go builds a main package at the root or a single cmd/*/main.go; for several services, set the build and start commands yourself. Python works with pip, Poetry and uv, and sets the server command for Django (WSGI), Flask and FastAPI on its own. Any other entry point needs a web: line in a Procfile, or a start command setting.
Go uses the version in go.mod. Python uses .python-version, then the manifest's Python constraint (supported minor versions 3.10–3.14), and 3.12 when neither gives one. ALPACK_GO_VERSION and ALPACK_PYTHON_VERSION pick a version explicitly. ALPACK_PORT sets the generated image's port (1024–65535, 8080 by default).
When native dependencies need system libraries, set ALPACK_BUILD_PACKAGES and ALPACK_RUNTIME_PACKAGES to Debian package names separated by spaces. Build packages stay in the build stage. The install, build and start command overrides work for both languages too. Generated images run as a non-root user and keep the project's assets; Python caches and virtual environments are left out.
Each source file can be up to 128 MiB, with at most 512 MiB in total after extraction and 20,000 files. Set up databases, Redis and service credentials separately before starting the service: building the image doesn't check those connections.