> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build and Deploy Images

> Use `meshagent build` and `meshagent deploy` to build images inside a room and deploy them as room services.

## Overview

`meshagent build` and `meshagent deploy` are the main CLI commands for working with OCI images in MeshAgent.

Use them when you want to:

* build an image inside a room from a local directory streamed as build context
* publish that image into a project registry repository
* deploy an image directly as a room service
* build and deploy from a local directory in one command

These commands are useful both for developers working from the CLI and for agent workflows running inside a room. They give MeshAgent a room-native way to build, package, and ship images without requiring Docker on the local machine that triggers the workflow.

Before using a `registry.meshagent.com/<project-key>/<repository>:<tag>` tag, make sure the target repository exists in the project. See [Registries](../../project_admin/registries).

## How image build and deploy fit into MeshAgent

The image workflow sits between source files and a deployable MeshAgent service:

1. `meshagent build PATH --tag ...` streams a local directory into a room and builds an image there.
2. `meshagent deploy --tag ...` creates or updates a room service from an existing image.
3. `meshagent deploy PATH --tag ...` does both in one command.

This complements the normal service packaging flow. In practice, a room-connected agent can:

* prepare files in the room
* build an image from those files inside the room
* deploy a service that uses that image

That makes this workflow especially useful for cases where an agent is expected to build, test, and ship a containerized service for you from inside MeshAgent.

## Commands

### `meshagent build`

Use `build` when you want MeshAgent to build an image inside a room.

`meshagent build` streams a local directory into the room as the build context. If that directory contains a `Dockerfile`, MeshAgent uses it during the room-side build. The build runs in MeshAgent rather than requiring a local Docker daemon on the machine that started the command.

Example:

```bash theme={null}
meshagent build ./my-app \
  --room myroom \
  --tag registry.meshagent.com/myproject/my-app:dev
```

Key things to know:

* `PATH` is required and becomes the streamed build context
* `--tag` is required
* `--room` is required unless `MESHAGENT_ROOM` is already set
* `--context-path` and `--dockerfile-path` let you point at a different directory or Dockerfile inside the streamed context
* build logs stream back through the CLI while the build runs
* this is a good fit for agent-driven build workflows inside a room because the build happens in MeshAgent, not on the local machine

### `meshagent deploy`

Use `deploy` when you already have an image and want to create or update a room service from it, or when you want to build and deploy from a local directory in one step.

Example deploying an existing image:

```bash theme={null}
meshagent deploy \
  --room myroom \
  --tag registry.meshagent.com/myproject/my-app:dev \
  --env APP_ENV=dev
```

Example building and deploying from a local directory:

```bash theme={null}
meshagent deploy ./my-app \
  --room myroom \
  --tag registry.meshagent.com/myproject/my-app:dev \
  --env APP_ENV=dev
```

When deploying, you can also:

* mount room storage with `--room-mount`
* mount project storage with `--project-mount`
* mount another image with `--image-mount`
* mount scratch storage with `--empty-dir-mount`
* inject a `MESHAGENT_TOKEN` with `--meshagent-token`
* run the deployed container as a service account with `--run-as`
* inject a service-account secret-backed environment variable with `--env-secret NAME=SECRET_ID`; this requires `--run-as`
* publish a route with `--domain` when the service exposes exactly one published port

When you pass `PATH`, `meshagent deploy` builds first and then deploys the resulting image tag. When you omit `PATH`, it deploys the image tag directly. In both cases the service name is derived from the image tag, and MeshAgent updates the existing room service when one already exists.

## How image build and deploy work with service packaging

`meshagent build` and `meshagent deploy` are complementary to service packaging.

Use this workflow when:

* your workflow is image-first
* you want to build inside a room
* you want a fast path from image tag to room service
* you want an agent in the room to participate in building and shipping the service

Use the service packaging docs when:

* you are writing or reviewing a `meshagent.yaml`
* you need a fuller service spec with more explicit deployment structure
* you are working with ServiceTemplates or broader service configuration

In other words, `meshagent build` and `meshagent deploy` are the room-native image workflow, while service manifests are the broader service-definition workflow.

## Related guides

* [Deploy a Web App](../deployment/deploy_web_app)
* [Registries](../../project_admin/registries)
* [Service YAML](../deployment/deploy_services)
* [MeshAgent Base Images](./meshagent_base_images)
* [Optimizing Containers](./optimizing_containers)
* [MeshAgent CLI Reference](../../reference/meshagent_cli_help)