# Build an agent's source into an image

Source: https://docs.vlayers.ai/reference/hosting/start-agent-build

`POST /v1/agents/{id}/builds` · scope `workspace:write`

Builds a snapshot of the agent's source with the platform's sealed builder (Cloud Native Buildpacks: no daemon, no internet but the package mirrors) and records the image by digest, so a version can name it. Left out, `snapshotId` is a snapshot of the working copy taken now. The tree must have its ecosystem's lockfile; the build is stopped with the limit named when it runs over its CPU, memory, disk or time limit. Builds are billed as room time at the small rate. Answers 202 with the build; read it with `getAgentBuild` until `state` is `succeeded`, `failed` or `stopped`. Refused with 402 `wallet` when the balance is empty.

Requires an API key with the `workspace:write` scope.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | The agent id. Example: `"0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78"` |
| `snapshotId` | body | string | no | The snapshot to build. Left out: the working copy is snapshotted first. |

## Request

cURL:

```bash
curl -X POST "https://api.vlayers.ai/v1/agents/$AGENT_ID/builds" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshotId": "0192f5c1-5e6f-7a8b-9c0d-1e2f3a4b5c67"
  }'
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { build } = await voicelayer.hosting.startAgentBuild('<agent-id>', {
  snapshotId: '0192f5c1-5e6f-7a8b-9c0d-1e2f3a4b5c67'
});
console.log(build.state);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.hosting.start_agent_build(
    "<agent-id>",
    snapshot_id="0192f5c1-5e6f-7a8b-9c0d-1e2f3a4b5c67",
)
print(result.build.state)
```

## Response `202`

```json
{
  "build": {
    "id": "bd-0a1b2c3d4e5f60718293",
    "agentId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78",
    "snapshotId": "0192f5c1-5e6f-7a8b-9c0d-1e2f3a4b5c67",
    "state": "requested",
    "limit": null,
    "reason": null,
    "detail": null,
    "imageDigest": null,
    "builderDigest": null,
    "ecosystem": null,
    "limits": {
      "cpuRequestMillicores": 500,
      "cpuMillicores": 2000,
      "memoryMiB": 4096,
      "diskMiB": 10240,
      "timeSeconds": 1800,
      "cacheExportSeconds": 600
    },
    "sizeClass": "small",
    "createdAt": "2026-10-20T15:04:05.000Z",
    "startedAt": null,
    "endedAt": null
  }
}
```
