Building Deployment Bundles

Use agentuity build to turn a framework app into the .agentuity deployment bundle that agentuity deploy uploads.

Basic Build

Build the current project:

agentuity build

agentuity bundle is an alias for the same command.

Write the bundle somewhere else:

agentuity build --outdir ./dist-agentuity

Skip the post-build type check:

agentuity build --skip-type-check

The command detects the framework from package.json, runs the matching adapter, writes launch metadata, enumerates static assets, and type checks the project unless you skip that step.

For an existing app, start with a no-write validation pass before building:

agentuity project import --validate-only
agentuity build

Read the Build Output

The first few lines tell you what the detector found and which adapter packaged the app:

Detecting framework...
Detected nextjs (node)
Building with nextjs adapter to .agentuity
✓ Dependencies installed in 510ms
✓ Next.js build completed in 3400ms
✓ Standalone output packaged
Build complete (nextjs, 4012ms)

Detection checks known framework packages and config files first, then falls back to a generic package.json shape. BUILD010 usually means the CLI did not find a known framework or a generic build/start entry it can package.

For frameworks that produce static assets or standalone servers, the adapter logs the important packaging step. For example, Next.js should report Standalone output packaged; static-oriented builds may report that a static file server was injected or assets were copied into the bundle.

PATH="$PWD/node_modules/.bin:$PATH" agentuity build

Build Options

CI Build Options

Git Metadata Options

Deployment Bundle Contents

The build output is a self-contained deployment bundle. It includes framework output plus Agentuity metadata:

agentuity deploy uses this bundle, the launch metadata, and the static asset list when it creates a deployment.

Example:

{
  "processes": [
    {
      "type": "web",
      "command": "node .output/server/index.mjs",
      "default": true
    }
  ],
  "framework": {
    "name": "tanstack-start"
  },
  "runtime": {
    "name": "node"
  }
}

For a workspace app, a monorepo-aware build stages from the workspace root and adds workingDirectory:

{
  "processes": [
    {
      "type": "web",
      "command": "node server.js",
      "default": true,
      "workingDirectory": "apps/web"
    }
  ],
  "framework": {
    "name": "nextjs"
  },
  "runtime": {
    "name": "node",
    "port": 3000
  }
}

Custom Launchers

If your app is not a JavaScript framework app, add a root launch.json. The build can package a directory without package.json when the launcher tells Agentuity what to run:

{
  "processes": [
    {
      "type": "web",
      "command": "python3 -m http.server 8000",
      "default": true
    }
  ],
  "framework": {
    "name": "python"
  },
  "runtime": {
    "name": "python",
    "port": 8000
  }
}

agentuity build copies the directory, skips dependency installation when no package.json exists, and writes the final .agentuity/launch.json. The command must bind the same port as runtime.port.

Framework Notes

Next.js generated projects can build with the framework command:

npm run build

If agentuity build cannot resolve next or another local framework binary, use the PATH form shown above.

Generated Hono projects include build and start scripts so the generic detector has a process to package. If agentuity build reports BUILD010, check that package.json still has both scripts and that start points at the built server entry.

Vite Projects

For Vite-based apps, use vite.config.ts the same way you would in a normal Vite project.

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
 
export default defineConfig({
  plugins: [react(), tailwindcss()],
  envPrefix: ['VITE_', 'AGENTUITY_PUBLIC_', 'PUBLIC_'],
});

Use framework-native config files for non-Vite frameworks such as Next.js, Nuxt, SvelteKit, Astro, and React Router.

Next Steps

• Local Development: Run the framework dev server with Agentuity environment wiring
• Deployment: Upload and provision the deployment bundle
• App Configuration: Configure regions, resources, and environment files