Skip to main content

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.

​
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.

​
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: 
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: 
meshagent deploy \
  --room myroom \
  --tag registry.meshagent.com/myproject/my-app:dev \
  --env APP_ENV=dev
Example building and deploying from a local directory: 
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
  • override the deploy identity for --meshagent-token and --env-secret with --identity
  • inject a secret-backed environment variable with --env-secret NAME=SECRET_ID
  • 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.